CallXML 3.0 Development Guide

<recordaudio> element

The <recordaudio> element is used to record a caller's voice utterances for future storage and/or retrieval. Note that while the CallXML markup allows for both a 'mailto' and an 'ftp' for the resultant recording to be stored, it is considered best practice in a Production application to allow the server side language to handle the uploading or mailing of recorded audio.

usage

attributes

beep	Data Type: (true\|false)	Default: true
	The beep attribute, when set to true, allows the developer to insert a ‘beep tone’ to indicate to the caller that the application has begun recording. If set to 'false', the caller will not hear the beep indicating that the recording has started.
cleardigits	Data Type: (true\|false)	Default: false
	This attribute's value is a Boolean, indicating whether the queued digits buffer should be cleared when this action starts. "true" clears the digits buffer; "false" leaves the contents of the digit buffer alone.
format	Data Type: string - URI	Default: none - attribute is optional
	The format attribute defines the formatting string, or MIME type of the recorded audio file. If this value is undefined, then the value will default to 'audio/wav'.
id	Data Type: (element id)	Default: none - attribute is optional
	The new 'id' attribute in CallXML3.0 is applicable to all container and action elements. Specifying this attribute allows yet another level of control and event handling when events occur and are caught by the `<on>` element. When an event occurs, the handler will first check the event, and then verify that the handler has a handler specific to the 'id' attribute to execute. This allows the developer to plan a specific course of action for events based on where in the application that they occur.
maxsilence	Data Type: (m\|s\|ms)	Default: 5s
	This attribute defines the maximum amount of silence from the caller during a <recordaudio> session before the CallXML interpreter will assume that the caller is finished recording. If left unspecified, then this will dealut to a value of 5 seconds.
maxtime	Data Type: (m\|s\|ms)	Default: 30s
	The maxtime attribute delineates the maximum time that a caller is allowed to record audio. If unspecified, then the session will be limited to a maximum of 30 seconds, (default).
termdigits	Data Type: (123456789*#\|ABCD)	Default: none - attribute is optional
	This attribute holds the list of touch-tone digits which can terminate the current caller action. Note that for each termdigit specified, there should be an <ontermdigit> handler in the code to catch the event. Allowable values are any one of "012356789*#", the ordinary DTMF (Touch-Tone) keypad possibilities, plus the special keypad tones found on some telephones "ABCD".
test	Data Type: CDATA	Default: Optional
	The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document.
timevar	Data Type: (variable name)	Default: none - attribute is optional
	The 'timevar' attribute of the `recordaudio` tag allows the developer to specify the variable name that holds the duration of audio that a caller has recorded. This value will return the amount of time, in milliseconds, that a callers input has recorded within the `recordaudio` element.
value	Data Type: (variable name)	Default: Required
	For the record element, the value attribute indicates a variable or URL reference that designates where the recorded audio is to be sent. Do note that leaving this attribute undefined will result in a fatal application error.
value-is	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution.
value-is-not	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution.

code samples

<3.0 recordaudio mailto with headers>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">
<do>
<prompt value="Lets record a message"/>

<recordaudio value="mailto:hasselhoff@baywatch.com?subject=
Youre fired&fromname=
The Network&fromaddress=
muckitymucks@TheNetwork.com&body=
Sorry dave. Just found out that you have no appreciable talent.
The enclosed recording details the fact that Baywatch On The
Moon is cancelled&filename=fired.wav"/>
</do>
</callxml>

<3.0 recordaudio format-value-choices-maxtime-maxsilence-beep>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">

<do>
<prompt value="Record your message, and then press the pound key"/>

<recordaudio
value="ftp://MyPassword@Myserver.com/MyMsgTitle.wav"
format="audio/wav" termdigits="#" maxtime="10s" maxsilence="2s"
beep="true">

<on event="termdigit:#">
<prompt value="Your message was"/>

<playaudio value="http://MyServer.com/MyMsgTitle.wav"/>
</on>

<on event="maxtime">
<prompt value="Hey there Mister Long winded.
You can only record a message for 10 seconds"/>
</on>

<on event="maxsilence">
<prompt value="You were quiet for too long,
and your recording was terminated"/>
</on>

</recordaudio>

</do>

</callxml>

<3.0 recordaudio-timevar>

<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="3.0">

<do>
<prompt value="Re cord your message to Elvis after the tone.
Press pound when you are done"/>

<recordaudio timevar="rectime"
termdigits="#"
maxtime="3m"
maxsilence="10s"
format="audio/vox"
value="mailto:Elvis@TheKing.com"/>

<on event="termdigit:#">
<say>
The re cording time was $rectime;
milliseconds in duration.
Thunkya vur much.
</say>
</on>

</do>

</callxml>

<3.0 recordaudio-id>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">

<do label="D1">

<say>
Re cord three messages, and then press the pound key
whenever you like.
</say>

<recordaudio value="your_email@somewhere.com" format="audio/wav"
id="RA1" choices="#" beep="true">
<on event="choice:#" target="RA1">
<say>
You pressed the pound key while RA 1 was recording.
</say>
<goto value="#B2"/>
</on>

<on event="maxsilence">
<log>** MAXSILENCE **</log>
<goto value="#B2"/>
</on>

</recordaudio>

</do>

<do label="B2">
<recordaudio value="mailto:matt@voxeo.com" format="audio/wav"
id="RA2" choices="#" beep="true">

<on event="choice:#" target="RA2">
<say>
You pressed the pound key while RA 2 was recording.
</say>
</on>
</recordaudio>

</do>

</callxml>

<3.0 recordaudio-test>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">
<do label="B1">

<say>
Record your message at the beep, and then press the pound key.
</say>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle1.wav"
format="audio/wav" beep="true"
test="'l33tspeak' = 'english'"/>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle2.wav"
format="audio/wav" beep="true"
test="'paris_hilton'!='role_model'"
choices = "#">

<on event="choice:#">
<say>
Your messages are
</say>
<playaudio value="http://MyServer.com/MyMsgTitle2.wav"/>
</on>

<goto value="#B2"/>
</recordaudio>

</do>

<do label="B2" cleardigits="true">

<say>
Record your message at the beep, and then press the pound key.
</say>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle3.wav"
format="audio/wav" beep="true" test="6 = 7"/>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle4.wav"
format="audio/wav" beep="true" test="420 = 420" choices = "#">

<on event="choice:#">
<say>
Your messages are
</say>
<playaudio value="http://MyServer.com/MyMsgTitle4.wav"/>
</on>
</recordaudio>

</do>

</callxml>

<3.0 recordaudio-valueis>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">

<do value="kevin_bacon">

<say>
Record your messages at the beeps, and then press the pound key.
</say>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle1.wav"
format="audio/wav" beep="true" value-is="kevin_bacon" choices="#">

<on event="choice:#">
<say>
Your message is
</say>
<playaudio value="http://MyServer.com/MyMsgTitle1.wav"/>
<goto value="#david_duchovy"/>
</on>

</recordaudio>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle2.wav"
format="audio/wav" beep="true" value-is="ahmed_best">
</recordaudio>

</do>

<do label="david_duchovy">

<say>
Record another message at the beep, and then press the pound key.
</say>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle3.wav"
format="audio/wav" beep="true" value-is-not="kevin_bacon"
choices="#">

<on event="choice:#">
<say>
Your message is
<playaudio value="http://MyServer.com/MyMsgTitle3.wav"/>
</on>
</recordaudio>


<recordaudio
value="ftp://MyUserName:MyPassword@Myserver.com/MyMsgTitle4.wav"
format="audio/wav" beep="true" value-is-not="david_duchovy">
</recordaudio>

</do>

</callxml>

<3.0 recordaudio (null)>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">

<do>
<say>
Here we illustrate how we can use the re cord audio tag to detect
silence.
This assumes that the audio recording is disposable, and that we
really dont want to save the audio to any particular destination.
</say>

<recordaudio value="null://" maxsilence="3s" maxtime="20s" timevar="rectime"/>

<on event="maxsilence">
<say> The recording was $rectime; milliseconds long</say>
</on>

</do>

</callxml>

additional links

none

ANNOTATIONS: EXISTING POSTS

MattHenry

1/22/2007 2:28 PM (EST)

A few people have asked about this, so I thought it best to illustrate in full how you can also <recordaudio> to a .vox file, as opposed to a .wav file extension. The things to remember are:

* specify "audio/vox" as the format

* be sure to specify a .vox extension when you declare a user-defined filename

~Matt

<do>
<prompt value="Record your message, and then press the pound key"/>

<recordaudio
value="ftp://user:PASS@ftp.voxeo.net/cxml3-testVox.vox"
format="audio/vox"
termdigits="#"
maxtime="10s"
beep="true">

<on event="termdigit:#">
<prompt value="Your message was"/>
<playaudio value="ftp://user:PASS@ftp.voxeo.net/cxml3-testVox.vox"/>
</on>

</recordaudio>

</do>

mbaker

5/3/2007 11:48 PM (EDT)

Why would we use a .vox instead of a .wav file?

jbassett

5/4/2007 5:08 AM (EDT)

Hi,

A vox file is a file that is normally based on Dialogic ADPCM (Adaptive Differential Pulse Code Modulation) codec. It differs from WAV in that a vox file is usually raw and has no actual file information, whereas a wav will have built in filie information. So basically the rate and codec in which it needs to be played has to be specified elsewhere. You would only want to use this if you needed to be compliant in some way with an older legacy system. I hope this clears things up.

Thanks
Jesse Bassett
Voxeo Support

drewcogbill

1/30/2009 12:10 AM (EST)

Would it be possible to play a beep or some notification letting the user know the end of the available recording time is coming to an end?

voxeoAlexBring

1/30/2009 12:31 AM (EST)

Hello,
As it is there is no built in way to output a beep near the end of a recording. We would like you to also keep in mind that generally a beep will signify the end of a recording step so it may cause some confusion, also having a beep play during a recording could cause some unwanted interference within the recording itself.

Please let us know if you have any further questions or comments we may be able to help you with.

Regards,

Alex Bring
Voxeo Support

vpsrikanth

3/31/2009 8:10 AM (EDT)

Is it possible to sent the recorded voice as a message body.

VoxeoDustin

3/31/2009 9:50 AM (EDT)

Hey,

I'm not certain I understand your request. Would you mind clarifying a bit on what your goal is so we can get a better idea of how to assist you?

Regards,
Dustin Hayre
Customer Support Engineer 2
Voxeo Support

enalnostaw

4/15/2009 2:35 PM (EDT)

We're using the IVR to front-end a voice-enabled laboratory system. Everything is behind a firewall. As a consequence, we'd like to store the audio file on a local drive. Using a normal path string (value="c:\temp\recordings\MyRecording.wav") doesn't seem to work. Can you point us in the right direction?

jdyer

4/15/2009 3:05 PM (EDT)

Hello,

In order to enable local file access for CallXML you will need to make a few configuration changes. First we need to open the config.xml file. In the file we want to add the following section:

<category name="IO">

<item name="Disabled" type="int">1</item>
</category>

Then we want to locate the VCS section of the config file and make the following change:

<item name="AllowLocalFileAccess" type="int"> 1 </item>

Now you will need to restart services. Now you will have the ability to write to local file system using the following syntax:
<recordaudio value="file:///C:\myRecordings\myFile.wav">

Please note that this is only available in Prophecy 8.0.232.0+

I do hope this helps, please let us u know if there is anything else that we can do to be of service!

Regards,

John Dyer
Customer Engineer
Voxeo Support

Splatzone

4/16/2009 4:09 AM (EDT)

Hi.

Is it possible to upload the recorded file to a server via an HTTP post request?

voxeoJeffK

4/16/2009 7:20 AM (EDT)

Hello,

At this time HTTP POST is not available as an upload option, but you can use HTTP PUT. You must be sure the receiving server will allow PUTs to be sent. You would use recordaudio something like this:

<recordaudio
value="http:/myhost.com/myapp/servlet/myWavFile.wav"
format="audio/wav" termdigits="#" maxtime="100s" maxsilence="20s"
beep="true">

Regards,
Jeff Kustermann
Voxeo Support

cazyckck

8/7/2009 3:21 AM (EDT)

Hi,
is it possible to save files as a wav-ccitt u-law.
Because i need this format and i dont want to convert.
chris

VoxeoDante

8/7/2009 8:29 AM (EDT)

Hello cazyckck,

You should be able to achieve a 8bit/8khz/ulaw audio with the following.

<recordaudio
value="http:/myhost.com/myapp/servlet/myWavFile.au"
format="audio/ulaw" termdigits="#" maxtime="100s" maxsilence="20s"
beep="true">

I spoecifically set the format to audio/ulaw, and the file extension to .au.

That should do it for you.

Cheers,
Dante Vitulano
Customer Support Engineer II
Voxeo Corporation

cazyckck

8/12/2009 3:32 AM (EDT)

Thanks. Ok it was a dump question ...
Ok now I want to record audio(30s) and send this file to spinvox api vor text recognition .. than i want to sent this "text" with the telekom sdk to a mobile...
the problem I have no server. is this possible with voxeo-webhosting?

voxeoTonyT

8/12/2009 5:34 AM (EDT)

Hello,

If you want to send a recorded audio file and you have a URL reference then you should be able to send the audio file to any publicly accessible location using the value attribute. You can use ftp as well as http to send the audio file. I'm not exactly sure that I answered your question so let me know if you still have questions regarding the <recordaudio> functionality.

<recordaudio
value="http://<desination>/<name of file>"
format="audio/wav" termdigits="#" maxtime="100s" maxsilence="20s"
beep="true">

Regards,

Tony Taveras
Customer Engineer
Voxeo Support

tomatoboy

8/17/2009 11:41 PM (EDT)

Hello,

May I know is this <recordaudio value="file:///C:\myRecordings\myFile.wav"> working in 9.0.36060.0?

I tried this code in my voxeo but it shows me Local access is denied.

voxeoblehn

8/18/2009 8:54 AM (EDT)

Hello,

Be default, access to local files is not enabled in Prophecy. You will need to make the following changes in your config.xml file in order to read/write local audio files.

Changes to the config.xml file:

Change the following line under the VCS Services section -
[code]
<item name="AllowLocalFileAccess" type="int"> 0 </item>
[/code]
To this -
[code]
<item name="AllowLocalFileAccess" type="int"> 1 </item>
[/code]
In addition to making this change you will need to add:
[code]
<category name="io">
<item name="AllowLocalFileAccess" type="int"> 1 </item>
</category>
[/code]
right before the CT layer category section. It should look similar to this:
[code]
<category name="NAT">
<item name="NATMapping0"></item>
</category>

<category name="io">
<item name="AllowLocalFileAccess" type="int"> 1 </item>
</category>

<!--+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
CT layer category
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

[/code]

After making these changes save the config.xml file and restart Prophecy services. I suggest backing up the config.xml file before making these changes in case you need to go back to the original file for any reason. Please let us know if you have any additional questions or concerns.

Regards,

Brian Lehnen
Voxeo Support

tomatoboy

8/22/2009 12:30 AM (EDT)

Thanks Brian.
It works perfectly.
I have one more question, may I know is that possible two url in the value. What I want is I when recording the voice it will located the file on "file:///" and another url connect to my java servlet "http://" to store the information in database. Both of them do at the same time.

voxeoTonyT

8/22/2009 6:54 AM (EDT)

Hello,

It seems as if you are asking if you can use the recordaudio element to send the recorded file to a database and to a separate destination. If I am correct in my understanding then you will not be able to use the recordaudio element to send a recording to 2 places. You can only use that element to send the recording to one destination. Furthermore database connectivity can not be achieved from within any of our platforms (callxml, ccxml, vxml). Database connectivity will need to be handled via a server side script that you would need to implement outside of the callxml file and in the same server script you will need to interact with the database. Here is a link with more information regarding the usage of server side scripting with callxml, [link=http://docs.voxeo.com/callxml/3.0/intro_sstcxml30.htm]link[/link].

Let us know if you still have any questions.

Regards,

Tony Taveras
Customer Engineer
Voxeo Support