callxml elements - recordaudio

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

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: none - attribute is optional
	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: 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