CallXML 2.0 Development Guide Home  |  Frameset Home
This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

Element Summary

Elements Attributes
answer none
assign var
block cleardigits, label, next, repeat
call answeronmedia, callerID, value, voxeo-cpa-maskevent, voxeo-cpa-maskstop, voxeo-cpa-maxsilence, voxeo-cpa-maxtime, voxeo-cpa-result, voxeo-cpa-runtime, voxeo-cpa-version
callxml version
clear var
cleardigits none
conference targetsessions, termdigits
createconference name, var
exit none
getdigits cleardigits, includetermdigit, maxdigits, maxsilence, maxtime, termdigits, var
goto cache, method, submit, value
hangup none
inputaudio beep, cache, cleardigits, label, maxsilence, maxtime, next, playformat, playvalue, recordformat, repeat, termdigits, text, value
inputdigits cache, cleardigits, format, includetermdigit, label, maxdigits, maxsilence, maxtime, next, repeat, termdigits, text, value, var
joinconference entertone, exittone, id, listenonly, termdigits
log value
menu cache, cleardigits, format, label, maxtime, next, repeat, termdigits, text, value
onanswer next
oncallfailure next, value
oncparesult type
onerror next, type
onexternalevent next, value
onhangup next
onmaxdigits next
onmaxsilence next
onmaxtime next
ontermdigit next, value
playaudio cache, cleardigits, format, termdigits, text, value
playdate cache, cleardigits, format, termdigits, value
playdtmf duration, pause, value
playmoney cache, cleardigits, format, termdigits, value
playnumber cache, cleardigits, format, termdigits, value
recordaudio beep, cleardigits, format, maxsilence, maxtime, termdigits, timevar, value
recordcall info, value
reject none
run cache, method, submit, value, var
sendemail from, subject, to, type
sendevent session , value
text cleardigits, termdigits, voice
transfer answeronmedia, callerID, maxtime, method, playrepeat, playvalue, termdigits, value
wait termdigits, value
This element will "answer" or "pick up" the call. Any time a new call is received by a CallXML browser, it will use a browser specific mechanism to determine a URL from which to fetch an initial CallXML document to use for that call. However, the CallXML browser does not "answer" or "pick up" the call until this element is executed.
Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error.
Assigns the value specified by the attribute value to the variable specified by the attribute var. As shown above, will assign the value "123" to a variable named "ttt". In addition to variables explicitly assigned by the CallXML markup, CallXML browsers may automatically create variables which contain information related to the call / session.
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.
This attribute designates the unique inter-document identifier of the parent element in question, and allows an easy way to navigate through applications as a destination 'anchor', as used in goto references
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
The value for the repeat attribute indicates the number of times to execute the content contained by the parent element. If this attribute is explicitly specified, this must be a valid number, or an error will result.  Also note that if the value is zero the content will be skipped.
The <block> element is used to logically group action and event elements together, as well as providing the ability to loop the actions in the block a specified number of times. Note that <block> elements may be nested within each other to foster more structured CallXML interface code.
Determines when audio passes from second call leg to the first. If set to "TRUE," this will pass audio back to the originating call leg upon the first instance of media. In practice, this will typically mean the caller hears the standard "telephone ring" as if they had picked up a normal telephone and dialed the number. If set to "FALSE," there will be silence until an actual answer or callfailure is achieved.

Note that this attribute is primarily used to detect that a phone has been answered in the event that the destination number does not send back the proper ISDN signal upon pickup, (common to some 800 numbers).
CallerID to present when placing the call. The list of allowable values declared for this attribute follow the same rules as the call value element/attribute combination, to wit:
  • "tel:"            classic phone number
  • "pstn:"          same as "tel:", deprecated value
  • "sip:"            SIP protocol address
The value for this attribute defines the URL describing the place to initiate a call to. An empty value will result in an error. Any value that does not begin with a valid prefix will be assumed to be a pure "tel:" number.

Valid URL values are:
  • "tel:"            classic phone number
  • "pstn:"          same as "tel:", deprecated value
  • "sip:"            SIP protocol address

Note that developers who use the non-US datacenters are required to specify an E164-formatted dial string:

tel:+[country code][number]
The 'cpa-maskevent' parameter lists the CPA results that should throw an event.  This assures that only desired results, important to your specific application, will be acknowledged.  The value for this parameter should be a comma-separated list, any combination of the following:
  • human
  • machine
  • beep
  • modem
  • faxtone
  • *sit
The 'cpa-maskstop' parameter lists the CPA results that, when received, will simply stop CPA from listening for further events. The value for this parameter should be a comma-separated list, any combination of the following:

  • human
  • machine
  • beep
  • modem
  • faxtone
  • sit
The cpa.maxsilence variable is the user-defined variable which designates the amount of time that the CPA should wait before it stops the human vs. machine analysis and returns the result of ‘human’. The setting for this variable is best set between 1000 and 2000ms.
The user-defined cpa.maxtime variable determines the amount of time that the CPA should wait before returning a result of ‘machine’ to the application. The ideal setting of this variable should be in the range between  5000 to 7000ms.  Note that care must be taken when assigning the value to this variable, for if the callee’s initial utterance is longer than the maxtime value, the resultant value will be returned as ‘machine’.
This variable holds the resultant value of the human vs. machine analysis, which is determined when the call is answered. The possible results are:
  • human
  • machine
  • unknown
The user defined cpa.runtime variable is set to the desired length of time in which the analyzer should work before returning the final result. We will want to make certain that the time value set in this variable is longer than the added cpa.maxtime and cpa.maxsilence values, as well as setting this value to be longer than the ‘average’ length of an answering machine message. Most answering machine messages are no longer than 15000-20000ms in length, which would be a good range of values to insert for this variable.
This attribute sets the Call Progress Analyzer version. This currently should always be cpa.version=2.0
The Call element allows for new outbound calls to be placed to the specified address. The address is specified by the attribute value and is in URL format.
The 'version' attribute is used to specify the CallXML version number of the code. The only allowable values for this attribute are '1.0' , (default), and  '2.0'. Do note that it is recommended that you explicitly specify version '2.0' to allow you to take advantage of the new element types and Call Progress Analyzer, (answering machine detection), features.
The root callxml element that contains all other elements. This element is required in any callXML documents.
The var attribute defines the name of the variable to set to an undefined state.
Clears variable specified by the attribute var. As show below, will clear a variable named "MyVar". Effectively this works the same as <assign var="MyVar" value="" />
The digits buffer contains any touch-tone digits the user may have pressed before a CallXML action is executed. The 'cleardigits' element will clear the digit buffer of any queued digits.
This attribute holds one or more unique session identifiers, separated by commas that the CallXML application will conference. An empty value, or an invalid target session will result in an error.
This attribute holds the list of touch-tone digits which can terminate the conference. 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".
This element allows multiple lines in separate sessions to be conferenced together so that the parties on each line can talk to each other simultaneously. The list of sessions to conference together is specified by the attribute targetSessions, and can be one more unique session identifiers separated by commas.
The name attribute specifies the conference name that is used to identify a particular conference. This is usually a numeric variable value that is derived from a preceding <input/getdigits> block that allows callers to specify a conference to join.
The var attribute defines the variable where the conference identifier is stored. Not specifying this attribute will result in a fatal error.
The <createconference> element is used to create a new multiparty conference for your callers. However, this element must also use it's sister element, <joinconference>, in order for callers to be connected to one another.
The <exit> element allows the developer to exit the session in question when it is executed in the callXML application. In short, it is much like an 'emergency brake' for a CallXML application. Note that in the event that an <exit> element is hit prior to a particular event handler executing, the <exit> will take precedence.
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.
This attribute defines whether the terminating digit should be included with the collected digit string. A value of 'true' indicates that the terminating digit will be appended to the string, and 'false' will ensure that the terminating digit pressed by the caller will not be included in the string.
This attribute denoted the maximum number of digits to collect from the caller. When the maximum amount of digits has been reached, application execution will resume from within the <onmaxdigits> handler, if present.
This attribute specifies the maximum time to wait between keypresses before a executing any repeat actions, if specified. The time string format is:
<numeric value>[<optional qualifier>] | nolimit

The string begins with a required numeric value. The valid qualifiers are:
  • m: minutes
  • s: seconds (default)
  • ms: milliseconds

Example: "45m 33s 117ms"

Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.
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".
This defines the variable name in which to store the digits collected. Not specifying a value for this attribute will cause a fatal application error.
The getDigits element reads input touch-tone digits from the call and places them into a variable by the var attribute. This element is typically used for such tasks as gathering PIN codes, pager numbers, and anything else that involves multiple digits coming from the user.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
The method attribute specifies the HTTP method to use when sending the request. Allowable values for the method attribute are:
  • "get" for HTTP GET
  • "post" for HTTP POST
  • "bin" for FTP binary transport
  • "asc" for FTP ASCII transport

    • Any other values defined for this attribute will result in a fatal error. If no method is specified, then it will always default to 'GET'.
List of variables to submit to the called URL/URI can be "all" or "*" for everything, or a comma delimited list of variables to submit:

submit = "Variable1, Variable2, Variable3, Variable5, Variable9"

Note that you can also specify "nothing" if no variables are to be submitted. If non-existant variable names are specified a fatal error will result. Also, if "all" or "*" is specified, no other variable names should be listed with it.
Either a full URL (http://MyServer.com/MyDocument.xml) or a local URI pointing to a <block> label in the same CallXML file (e.g., #main_menu).

Supported URL formats include:
  • http://    Read data
  • https://  Read data (over a secure connection)
  • ftp://      Read data
An empty or invalid value will result in a fatal error. Invalid values are:
  • value="[optional url]#"
  • value="[optional url]#foo", and "foo" does not exist as a label in the document
Domain names can contain port numbers and login information, for instance:

value="ftp://me:door@ftp.me.com:2345/myapp/start.xml"
This element can either:
Leap to another block of CallXML actions in the current file, by specifying value="#blocklabel", or
Perform an HTTP(S)/FTP to fetch a new CallXML document, by specifying value="url"
This element instructs the CallXML browser to "hang-up" or disconnect the call associated with the current session.
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.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
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.
This attribute designates the unique inter-document identifier of the parent element in question, and allows an easy way to navigate through applications as a destination 'anchor', as used in goto references
This attribute specifies the maximum time to wait between keypresses before a executing any repeat actions, if specified. The time string format is:
<numeric value>[<optional qualifier>] | nolimit

The string begins with a required numeric value. The valid qualifiers are:
  • m: minutes
  • s: seconds (default)
  • ms: milliseconds

Example: "45m 33s 117ms"

Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
The playformat attribute essentially mimes the functionality of the format attribute for the <play..> element. The value for this should reflect the MIME type of the audio file that will be played to the caller.
The playvalue attribute functions in the same way as the <playaudio> element, in that the value defined should be a URI reference which indicates the sound file to play to the caller.

The indicated value can either be a complete URI:
http://Myserver.com/MyDir/MySoundFile.wav

or a relative URI:
MySoundFile.wav
The recordformat attribute works essentially the same as the format attribute of the <recordaudio> element. Go figure. The value for this attribute should indicate the MIME type of the recorded audio. If unspecified, then this will default to the value of 'audio/wav'.
The value for the repeat attribute indicates the number of times to execute the content contained by the parent element. If this attribute is explicitly specified, this must be a valid number, or an error will result.  Also note that if the value is zero the content will be skipped.
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".
The 'text' attribute allows the developer to specify backup TTS to be output in the event that the .wav file cannot be found.
This attribute works the same as the value attribute for the <recordaudio> element. The value should specify a value in any of the following formats:
  • variable name in which to store the recorded audio file:
    < inputaudio... value="MyVar"...>
  • A URI indicating a FTP upload: < inputaudio... value="ftp://MyUsername:MyLogin@MyServer.com"...>
  • A URI indicating a mailto operation: < inputaudio... value="mailto:Jesus@Heaven.org"...> or http PUT operation: < inputaudio... value="http://MyServer.com/MycatherScript.cfm"...>
The <inputAudio> element combines the attributes and functionality of a <block> element, <playAudio> element, and a <recordAudio> element.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
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.
The 'format' attribute defines the string  formatting to use for the element.  If the value is undefined, the audio file format should be determined from the file name extension, if possible, and, if necessary, override the default format.
This attribute defines whether the terminating digit should be included with the collected digit string. A value of 'true' indicates that the terminating digit will be appended to the string, and 'false' will ensure that the terminating digit pressed by the caller will not be included in the string.
This attribute designates the unique inter-document identifier of the parent element in question, and allows an easy way to navigate through applications as a destination 'anchor', as used in goto references
This attribute denoted the maximum number of digits to collect from the caller. When the maximum amount of digits has been reached, application execution will resume from within the <onmaxdigits> handler, if present.
This attribute specifies the maximum time to wait between keypresses before a executing any repeat actions, if specified. The time string format is:
<numeric value>[<optional qualifier>] | nolimit

The string begins with a required numeric value. The valid qualifiers are:
  • m: minutes
  • s: seconds (default)
  • ms: milliseconds

Example: "45m 33s 117ms"

Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
The value for the repeat attribute indicates the number of times to execute the content contained by the parent element. If this attribute is explicitly specified, this must be a valid number, or an error will result.  Also note that if the value is zero the content will be skipped.
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".
The 'text' attribute allows the developer to specify backup TTS to be output in the event that the .wav file cannot be found.
The 'value' attribute defines the audio file to play to the caller when the parent element is first entered.
This defines the variable name in which to store the digits collected. Not specifying a value for this attribute will cause a fatal application error.
<inputdigits> is an element that combines the functionality and attributes of a <block> element, <playAudio> element, and a <getDigits> element. The intent of this element is to foster easy creation of scripts which prompt the user to enter variable DTMF digits such as pin codes, pager messages, and numeric values.
The entertone attribute allows the developer to modify or turn off entirely, the default tone that plays when a user joins an existing conference. Allowable values are 'false' or the user may specify a wav file to play instead of the default 'beep' tone that is normally heard.
The exittone attribute allows the developer to modify or turn off entirely, the default tone that plays when a user leaves an existing conference. Allowable values are 'false' or the user may specify a wav file to play instead of the default 'beep' tone that is normally heard.
The id attribute is used to specify a unique conference identifier. The value is set to the session variable of $conferenceid; which is used  internally by the CallXML platform.
The listenonly attribute allows the developer to specify that a member of the conferenece may eavesdrop only, and effectively create a half-duplex conference, (i.e. listenonly='true' means that a conference particpant will not be heard by other members of the conference)
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".
The joinconference element is used in conjunction with the createconference element to create multiparty conferencing. Specifically, this element allows you to join a caller to a specific existing conference.
The value attribute should define the string message to be output to the Voxeo logger.
The <log> element replaces the deprecated <simline> element for the purpose out outputting debugging text to the Voxeo logger.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
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.
The 'format' attribute defines the string  formatting to use for the element.  If the value is undefined, the audio file format should be determined from the file name extension, if possible, and, if necessary, override the default format.
This attribute designates the unique inter-document identifier of the parent element in question, and allows an easy way to navigate through applications as a destination 'anchor', as used in goto references
The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
The value for the repeat attribute indicates the number of times to execute the content contained by the parent element. If this attribute is explicitly specified, this must be a valid number, or an error will result.  Also note that if the value is zero the content will be skipped.
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".
The 'text' attribute allows the developer to specify backup TTS to be output in the event that the .wav file cannot be found.
The 'value' attribute defines the audio file to play to the caller when the parent element is first entered.
Menu is an element that combines the attributes and functionality of a <block> element with a <playAudio> element.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
This event occurs when a session determines that a call has been answered. This element is used as a handler to transition an action or event in a CallXML script after executing a <call> action.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
The value attribute defines the possible type of call failure encountered by the CallXML application. This can be useful in determining how to proceed when differnt responses are returned from the call destination The type given in an <onCallFailure> element will be compared against the actual failure type and, if identical, any CallXML contained within the <onCallFailure> element will be executed.

The possible values for this element are:
  • busy - destination number returned a busy signal
  • unreachable - this is returned when the destination number returns a SIT tone;( 'doo doo dee, the number you have dialed is not in service at this time'), most often, the dialed number is either employing a call screening device, or is indeed out of service
  • rejected - this event will very rarely get returned. In some circumstances, a switch or PSTN  might return a series of codes to the CallXML browser, informing it that the destination number has been rejected at the Telco level
  • unknown - the call was rejected for unknown reasons
This event occurs when the session determines that the attempted call cannot be completed because the dialed number is busy, a circuit is unavailable, a SIT tone was detected or other detectable call failure mode.
The 'type' attribute is used to denote the event that is trapped from the Call Progress Analyzer return value, so that the developer may perform logic based on this result.
The <oncparesult> element is an event handler for Call Progress Analyzer, (CPA), related events/results.  A CPA event/result can occur at any time while the CPA is active.  When encountered, the CallXML browser will interrupt the current block of execution, and process the corresponding <oncparesult> handler.

Note that while the <oncparesult> tag does not have any 'parent' elements per-se, it is considered a 'stepchild' element of <call> and <onanswer> tags. Logically speaking, the only time that <oncparesult> can be executed is after a <call> that specifies specific CPA parameters is placed, and after the <onanswer> event handler is executed upon callee pickup.

Also note that only one 'type' may be specified per tag; the following code would be considered invalid, and should be expected to throw a fatal error in the application:


<oncparesult type="beep, machine">
  <log value="got a machine"/>
</oncparesult>
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
The 'type' attribute, when used in conjunction with the <onerror> element is used for fine-grained event handling for specific circumstances. When a specific error is thrown, the callXML browser will look for a specific <onerror type> matching the event thrown, and execute the code contained within. If no specific handlers are present, the browser will then execute any generic <onerror> elements that are present and execute the code within.

The allowable values for this atribute are:
  • unknown - General error not fitting into any other category
  • internal - Server error -- alert Voxeo support
  • document - Document was unable to be fetched for all the reasons web servers are unavailable
  • telephony - Unable to issue a telephony event such as <call> or <playaudio> or <ftp>
  • serverbusy - No sessions available on the server for <run> or <answer> etc
  • lineactive  - Trying to issue a telephony event such as <answer> on an already active line
  • linenotactive - Trying to issue a telephony event such as <getdigits> or <playaudio> on a non-active line
  • invalidconference - Bad target conference
  • badnumber - Outbound destination returs a SIT tone
  • event -  When certain errors occur an <onError> event is generated. This gives the CallXML developer a way to handle error conditions that may occur while CallXML actions are executing.
When certain errors occur an <onError> event is generated. This gives the CallXML developer a way to handle error conditions that may occur while CallXML actions are executing.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
The value attribute for the <onexternalevent> element defines the type of event to be caught by the CallXML code, usually from a <sendevent> element loacted elsewhere in the application. When a specific event is effectively caught, any code contained within the <onexternalevent> will then be executed.
This event occurs when another session sends an external event to the current session.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
This event occurs when a session determines that one side of the call has hung up. A typical use for this handler is to execute any necessary clean-up code.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
This event occurs during user input if the length of the string of digits entered by the user exceeds the number indicated by a maxDigits attribute and a terminating digit has not yet been pressed.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
This event occurs when the application has waited too long between digit entries or detects too much silence at the end of a recording session.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
This event occurs during user input if the user takes more time than is allowed by a maxTime attribute to input their entire response.
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
This attribute defines the value to compare to the digit the user pressed to trigger an <ontermdigit> event. The value given in an <ontermdigit> element will be compared against the digit pressed, and if identical, any CallXML contained in the <ontermdigit> element will be executed. Allowable values are any one of "012356789*#", the ordinary DTMF (Touch-Tone) keypad possibilities, plus the special keypad tones found on some telephones "ABCD". Do note that not specifying the 'value' attribute will allow you to catch and handle *any* keypress from the caller.
Used for catching and handling term digit events as they occur in the call flow.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
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.
The 'format' attribute defines the string  formatting to use for the element.  If the value is undefined, the audio file format should be determined from the file name extension, if possible, and, if necessary, override the default format.
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".
The 'text' attribute allows the developer to specify backup TTS to be output in the event that the .wav file cannot be found.
The 'value' attribute defines the audio file to play to the caller when the parent element is first entered.
The <playAudio> element is used to output a .wav or a .vox file to the caller. Unless the caller takes some action, as (when used in conjunction with <getdigits>, for example),  the audio will repeat as many times as indicated for the parent <block> element.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
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.
The 'format' attribute defines the string formatting  to use for the <play> element.

Note that only the following format values are allowed:

<!-- day month year hour minutes -->
<playdate format="ddmmyyyyhhnn" value="180519700612"/>
<!-- day month -->
<playdate format="ddmm" value="1805"/>
<!-- hour minutes -->
<playdate format="hhnn" value="0732"/>
<!-- month day year -->
<playdate format="ddmmyyyy" value="18051970"/>
<!-- month day -->
<playdate format="ddmm" value="1805"/>
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".
The 'value' attribute defines the audio file to play to the caller when the parent element is first entered.
The <playdate> element is used to render a given date to the caller via Text-to-Speech.
The 'duration' attribute specifies how long each dtmf tone should be played to the called party. For instance, if specified as '10s', then each dtmf tone will be played for 10 seconds. Note that if this attribute is left unspecified, then the value will default to 120 milliseconds.
The 'pause' attribute defines the duration of the silence, (if any), between the dtmf tones specified in the 'value' attribute. If left unspecified, then this will default to 240 milliseconds.
The 'value' attribute defines the dtmf string to play to the caller when the element is executed.
The playdtmf element allows the developer to play a sequence of dtmf tones to the call destination, (most often used when using a http token inititiated outbound call). This is useful for postdialing operations, where you may wish to programmatically navigate to a particular extension, or to navigate through a PBX menu. Note that when using this element, care must be taken to 'marry' a particular dtmf string to the specific menu that you wish to step through, as no two PBX menus are the same in regards to timing.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
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.
The 'format' attribute defines the string formatting  to use for the <playmoney> element. AT this time, the only supported value for this attribute is "us", for United States denominations.
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".
The 'value' attribute defines the audio file to play to the caller when the parent element is first entered.
The <playmoney> element allows the developer to render a monetary amount to the caller via Text-to-Speech. The allowable ranges for this element are between '.00' and '999999999.99'.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
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.
The 'format' attribute defines the string formatting  to use for the <play> element. In the case of the playnumber element, this defines whether the variable value should be read off as a digit or a numeric value.
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".
The value attribute defines the numeric string to be played to the caller when the playnumber element is executed. Note that non-numeric characters, (including # and *), will cause a fatal application error, if specified as values in this attribute.
This element is used to play a digit or number value to the caller. The format may either be specified as a digit output, or a numeric output.
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.
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.
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'.
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.
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).
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".
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.
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.
The <recordaudio> element is used to record a caller's voice utterances for future storage and/or retrieval.
The 'info' attribute allows the developer to specify information that is inserted into the resultant recorded wav filename that makes identification easier. Note that ECMA values are NOT supported; (for instance, specifying the 'info' attribute with a value of 'MyVar' is not valid). Resultant audio filenames will be in the following format:

AccountID -ApplicationID-SessionID-UserData(Info).wav

As such, a sample file might well look like this:

111-22222-abcdefg1234567abcdefg1234567-MyUserDefinedInformation.wav
The 'value' attribute specifies what percentage of calls will be recorded. Setting this value to '100' will record all calls that hit the application, while setting it to '30' will record 3 out of 10 calls that come in. Setting this value to '0' allows the developer to programmatically turn call recording on and off within the application flow.
The <recordcall>element is a new element that allows the developer to record both sides of a call, recording the human and the application interaction to a wav file that is stored in the developer's Voxeo File Manager in the 'recordings' subdirectory.  <recordcall> can record to a stereo audio file and contains *two* 8-bit streams, (note that two 8-bit streams is not the same as recording in 16 bit).
The <reject/> element enables CallXML applications to reject incoming calls before they are answered.
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
The method attribute specifies the HTTP method to use when sending the request. Allowable values for the method attribute are:
  • "get" for HTTP GET
  • "post" for HTTP POST
  • "bin" for FTP binary transport
  • "asc" for FTP ASCII transport

    • Any other values defined for this attribute will result in a fatal error. If no method is specified, then it will always default to 'GET'.
List of variables to submit to the called URL/URI can be "all" or "*" for everything, or a comma delimited list of variables to submit:

submit = "Variable1, Variable2, Variable3, Variable5, Variable9"

Note that you can also specify "nothing" if no variables are to be submitted. If non-existant variable names are specified a fatal error will result. Also, if "all" or "*" is specified, no other variable names should be listed with it.
Either a full URL (http://MyServer.com/MyDocument.xml) or a local URI pointing to a <block> label in the same CallXML file (e.g., #main_menu).

Supported URL formats include:
  • http://    Read data
  • https://  Read data (over a secure connection)
  • ftp://      Read data
An empty or invalid value will result in a fatal error. Invalid values are:
  • value="[optional url]#"
  • value="[optional url]#foo", and "foo" does not exist as a label in the document
Domain names can contain port numbers and login information, for instance:

value="ftp://me:door@ftp.me.com:2345/myapp/start.xml"
A valid variable name in which to store the new session ID.
This element will run/start a new session, and fetches a CallXML document to use for the session from the URL or URI specified by value.
The 'from' attribute allows the developer to specify a return address for emails sent through the 'sendemail' element. Any valid email address is allowed, provided that it is parseable.
The 'subject' attribute allows the developer to specify a subject line that will be visible to the email recipient.
The 'to' attribute allows the developer to specify a return address for emails sent through the 'sendemail' element. Any valid email address is allowed, provided that it is parseable.
The 'type' attribute allows the developer to specify whether or not debugging output should be included in the message body of the email that is sent. Unless the setting of 'debug' is specified, the email will only contain the user data that is nested within the <sendemail> tags.
The 'sendemail' tag is a new addition to the CallXML arsenal. This tag allows you to programmatically send an email to a user specified destination. Additionally, this new element also allows you to output debugging information in the body of the email, which is a very useful 'watchdog' feature that allows you to be alerted via email, whenever errors are encountered within the application.
This attribute contains the ID of the session to which the event will be sent.
Be advised, that specifying an empty session attribute will result in an error, also if the session is ceased already or never existed at all.
The value attribute defines the string containing the body of the event message to be sent.
The <sendevent> element is a tag that allows one session to send a user-defined message to another entirely separate session, such as when a <run> element has been used in the document.


Note: CallXML can only send events to other CallXML sessions on the same computer handling both sessions and should not be used a hosted environment.
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.
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".
The voice attribute defines the Text-to-Speech voice that should be used for what is enclosed within that particular <text> element. This allows the developer a way to override the default voice genders/styles on a prompt by prompt basis. The currently supported voices for the CallXML2.0 platform are:

  • English-Female2 (default)
  • English-Male2
  • French-Female1
  • Spanish-Female1
Text is an element that is used to tell the CallXML browser to use a text-to-speech engine to read text contained within the element to the user.
Determines when audio passes from second call leg to the first. If set to "TRUE," this will pass audio back to the originating call leg upon the first instance of media. In practice, this will typically mean the caller hears the standard "telephone ring" as if they had picked up a normal telephone and dialed the number. If set to "FALSE," there will be silence until an actual answer or callfailure is achieved.

Note that this attribute is primarily used to detect that a phone has been answered in the event that the destination number does not send back the proper ISDN signal upon pickup, (common to some 800 numbers).
CallerID to present when placing the call. The list of allowable values declared for this attribute follow the same rules as the call value element/attribute combination, to wit:
  • "tel:"            classic phone number
  • "pstn:"          same as "tel:", deprecated value
  • "sip:"            SIP protocol address
Maximum amount of time to wait for the call to be answered. Time format strings are used for maxTime and maxSilence attributes, and in the <wait> tag.

The time string format is:
<numeric value>[<optional qualifier>] | nolimit

The string begins with a required numeric value. The valid qualifiers are:
  • m: minutes
  • s: seconds (default)
  • ms: milliseconds

Example: "45m 33s 117ms"

Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
This attribute determines the transfer method. At this time, only Bridged transfers are allowed on the Voxeo CallXML network.
This attribute defines whether or not the audio file indicated in the <playvalue> attribute should be repeated.
The playvalue attribute functions in the same way as the <playaudio> element, in that the value defined should be a URI reference which indicates the sound file to play to the caller in place of a ring tone.

The indicated value can either be a complete URI:
http://Myserver.com/MyDir/MySoundFile.wav

or a relative URI:
MySoundFile.wav
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".
The value for this attribute defines the URL describing the place to initiate a call to. An empty value will result in an error. Any value that does not begin with a valid prefix will be assumed to be a pure "tel:" number.

Valid URL values are:
  • "tel:"            classic phone number
  • "pstn:"          same as "tel:", deprecated value
  • "sip:"            SIP protocol address

Note that developers who use the non-US datacenters are required to specify an E164-formatted dial string:

tel:+[country code][number]
This element allows multiple lines in a single session to be conferenced together so that the parties on each line can talk to each other simultaneously.
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".
The time string format is:
<numeric value>[<optional qualifier>] | nolimit

The string begins with a required numeric value. The valid qualifiers are:
  • m: minutes
  • s: seconds (default)
  • ms: milliseconds

Example: "45m 33s 117ms"

Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
The wait element is used to instruct the CallXML browser to wait for a specified amount of time. This is most often used when you need to allow certain content within your code additional time to execute.

© 2011 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site