Recording calls in CCXML

Recording calls in CCXML Internally

Call recording allows a user to record audio data from calls and send that audio to another server once the recording is complete.

Commands may be issued by both CCXML and VoiceXML applications to control the recording(s) - VoiceXMl applications started by CCXML applications may reference call recordings started prior to their existence, and call recordings started in VoiceXML may be referenced in their parent CCXML application.

For more information on how VoiceXML interacts with the call recording system, see VoiceXML and Call Recording

How to Control Call Recordings In CCXML

Use the CCXML <send> element to send commands to a connection using the name bvr.call_record and supplying a variable named command in the namelist of that <send>

<var name="command" expr="'<command string>'"/>
<send name="'bvr.call_record'" target="event$.connectionid" targettype="'connection'" namelist="command"/>

A return event will be generated - either a bvr.call_record.successful or an error.bvr.call_record depending on how the commands went. These events will have command and connectionid as event variables, containing the command that was processed and the connectionid of the connection that it was sent to.

The error.bvr.call_record event will also have a reason event variable detailing why one or more of the instructions failed. Only one event is generated regardless of how many instructions are included in the command.

Each command may give instructions to multiple named call recordings, in a list separated by semicolons. Each instruction takes the form of ACTION=RECORDING_NAME

The available instructions are:

start - creates a new call recording with the supplied name. Names are arbitrary labels for the recordings and may be anything except 'length', which would conflict with ECMAscript internals.
stop - stops a call recording, making it stop recording any new audio and become available to be sent using the <http.submit> or <subdialog> method (see below).
pause - pauses a call recording, stopping it from recording any more audio until a resume command is given to it. As with stop, pausing a recording makes it available to be used
resume - resumes a paused call recording, allowing it to record more audio. There will be no gap between the moment the audio was paused and the moment it resumed.
mute - makes the call recording record silence instead of the audio until told to unmute
unmute - unmutes a previously muted call recording, letting it record the audio of the call once more.
erase - destroyed a stopped or paused call recording, deleting it from BVR entirely. Recordings will be disposed of even if not told to erase once the application terminates

For example, to start three recordings with the names call_long, muted and just_the_start, you could use the command string 'start=call_long;start=muted;start=just_the_start'.

Note that once the call has disconnected, you can no longer issue any commands to call recordings that may be running on that call - however, BVR will automatically issue a stop command to those recordings when the hangup occurs, and you can immediately use them on a connection.disconnected event for a far end disconnect.

Whilst it will often be most useful to record calls during the running of voice applications, CCXML can simply record whatever the caller might say independent of any running VoiceXML or other dialog.

Using HTTP POST to Save Call Recordings

A new targettype 'audio_submit' has been added for <send> that allows a CCXML application to make an HTTP POST using multi-part form data to an address. That page can then use the POSTed WAV file data as it wishes.

Please note that basichttp messages cannot be used to send call recordings.

A variable named the_recording must be included in the namelist, containing the relevant value from the session.blueworx.call_recording array. Any other variables included in the namelist of the <send> will also be submitted.

  <var name="the_recording" expr="session.blueworx.call_recording['call_long']"/>
  <var name="id_code" expr="event$.connectionid.substr(17)"/><!-- This strips off the front and leaves _ followed by a four digit number -->
  <var name="filename" expr="'call_long' + id_code + '.wav'"/>
  <send name="'http.submit'" target="'http://validIPAddressHere/saveAudio.cgi'" targettype="'audio_submit'" namelist="the_recording filename"/>

The above example submits the audio of the call recording named call_long to the target webpage. There will be two HTTP POST fields included in that request, one for the_recording containing the bytes of the audio in WAV file format, and one named filename containing a string based on the connectionid

By default, call recordings use a stereo (2 channel) WAV format. You may tell BVR to convert this into mono (1 channel containing mixed audio) WAV audio by appending '&format=mono' to the cache reference in the session.blueworx.call_recording array:

  <var name="the_recording" expr="session.blueworx.call_recording['call_long'] + '&amp;format=mono'"/>

Full example applications using CCXML and VoiceXML can be found in /opt/blueworx/vr/sample/ccxml/ with call_record_sample.ccxml and call_record_sample.vxml. You will need to modify these samples to point them at your target http location to deliver the audio POSTs.

For details on how to use VoiceXML with call recordings, see VoiceXML and Call Recording