VoiceXML and Call Recording

Call Recording is a BVR-specific feature unrelated to the VoiceXML <record> element functionality, though audio may be submitted in the same way as when using that element.

Call recording captures both incoming audio (what the other endpoint says) and outgoing audio (what BVR sends to the other endpoint), allowing you to listen to the whole call in context.

You may make any number of concurrent recordings during the course of your application, identified with a recording name of your choice. Recordings started in a CCXML application that launches VoiceXML will also be available to the VoiceXML application and conversely recordings started in a VoiceXML application may be used in the CCXML application that started the VoiceXML application.

To modify the state of call recordings in a VoiceXML application the <property> element can be used to issue commands if set to the com.blueworx.call_record name:

<vxml version="2.0" xml:lang="en-US" xmlns="http://www.w3.org/2001/vxml">

<property name="com.blueworx.call_record" value="start=vxml"/>
<menu id="start">
	<property name="com.blueworx.call_record" value="start=menu"/>
	<prompt>Please say next to continue</prompt>
	<choice next="#collect">Next</choice>
</menu>
<form id="collect">
	<property name="com.blueworx.call_record" value="stop=menu;start=form"/>
	<field name="number">
		<property name="com.blueworx.call_record" value="start=digit"/>
		...

In the above snippet you can see all the valid places where <property> elements may be used:

in the top level of <vxml>, where the command will be enacted as soon as VoiceXML loads
in a <form> element, where the command will be enacted on the first <prompt> in the form, even if that is in an element like a <field> or <block>
in a <menu> element, where the command will be enacted when the menu prompt starts to play
in a <field> element, where the command will be enacted when the first <prompt> in that <field> starts to play. If no <prompt> is in the <field> then the command will never trigger.

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. In the above example we start four different recordings named vxml, menu, form and digit - these names are arbitrary and may be anything you like
stop - stops a call recording, making it stop recording any new audio and become available to be sent using the <submit> element.
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 submitted.
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, the command "resume=pausing_rec;unmute=muting_rec" would resume a call recording named pausing_rec and unmute a call recording named muting_rec.

Any incorrectly issued commands (e.g. pausing a non-existent recording) will report problems into the VXML log, but not halt VXML execution.

Using <submit>/<subdialog> to save your recording

The cache references for the call recordings that you make are stored in the blueworx.session.call_recording array in the VoiceXML and CCXML environments. You may supply the value stored there by the name of your call recording (assuming you have issue a stop or pause command to that call recording) by including a variable with that string value in your namelist

BVR will recognise the formatting of that string and submit the bytes of the WAV file as that variable in the multi-part form data of the http POST message.

In the example below, a user has set up a dynamic web application (saveAudio.cgi) which can interpret an HTTP POST multi-part form to save the audio data. The form saves the recording cache reference for the call recording named vxml.

Transition to this form is being used as a trigger to stop the call recording so that it is in a state where it can be submitted.

<form id="do_submit">
	<property name="com.blueworx.call_record" value="stop=vxml"/>
	<var name="the_recording" expr="session.blueworx.call_recording['vxml']"/> 
	<block>
		<prompt>The call recording will now be submitted. </prompt>
		<log>The audio file is <value expr="the_recording"/></log>
		<submit next="http://validIPAddressHere/saveAudio.cgi" method="post" namelist="the_recording" enctype="multipart/form-data"/>
	</block>
</form>

As per usual when using <submit> you may include any number of variables on the namelist, which may also include regular VoiceXML variables and references to the result of using the <record> tag.

You may use <subdialog> to attach call recordings in the same way as for <submit> - if the VoiceXML in the response executes a <return> then you can return to the currently executing part of the VoiceXML document after sending the audio, whereas <submit> leaves the current execution environment.

Therefore <subdialog> is useful if you want to send multiple call recordings without having to attach all of them to one HTTP request.

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' (this will be parsed to become '&format=mono' on the actual URI) to the cache reference in the session.blueworx.call_recording array:

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

Limitations of the Timing of Commands and <submit>/<subdialog>

Due to the way the Form Interpretation Algorithm or FIA works, supplying audio data using <submit>/<subdialog> may cut off some of what you might expect to be included in a call recording. This is because the elements are executed up until the next input collection point or the end of the document, which means the fetching of the document happens immediately whilst those prompts are queued up.

For example, if you have a <prompt> in a <filled> block that then moves to the form that <submit>s the audio, that <filled> block prompt would not be included in the audio data that was submitted as that <submit> would be processed instantly, using the audio data up until that point.

If you need audio including up to the end of the VoiceXML application then you may find more success submitting that data in a CCXML document that started the VoiceXML document.

When using CCXML it may be helpful to supply the CCXML document with the name of the call recording using <exit namelist="my_var"/>, which will then appear in the event$.values array in the dialog.exit CCXML event. You can of course simply use a hardcoded value in the CCXML, but if the document might launch different VoiceXML applications the feedback may be useful.

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 CCXML with call recordings, see Recording calls in CCXML