CallXML 3.0 Development Guide

Element Summary

Elements	Attributes
answer	id, test, value-is, value-is-not
assign	expr, id, test, value, value-is, value-is-not, var
block	choices, cleardigits, foreach, id, label, next, repeat, test, value, value-is, value-is-not, var
call	answeronmedia, callerID, id, maxtime, test, value, value-is, value-is-not, voxeo-cpa-maskevent, voxeo-cpa-maskstop, voxeo-cpa-maxsilence, voxeo-cpa-maxtime, voxeo-cpa-result, voxeo-cpa-runtime, voxeo-cpa-version
callxml	version
case	choices, cleardigits, foreach, id, label, next, repeat, test, test, value, value-is, value-is-not, var
clear	id, test, value-is, value-is-not, var
cleardigits	id, test, value-is, value-is-not
conference	id, termdigits, test, value, value-is, value-is-not
createconference	id, test, value, value-is, value-is-not, var
destroyconference	expr, id, test, value, value-is, value-is-not
do	choices, cleardigits, foreach, id, label, next, repeat, test, value, value-is, value-is-not, var
exit	id, submit, test, value-is, value-is-not
fetch	cache, id, method, submit, test, type, value, var
getdigits	cleardigits, id, includetermdigit, maxdigits, maxsilence, maxtime, termdigits, test, value-is, value-is-not, var
goto	cache, id, method, submit, test, value, value-is, value-is-not
hangup	id, test, value-is, value-is-not
if	choices, cleardigits, foreach, id, label, next, repeat, test, value, value-is, value-is-not, var
inputaudio	beep, cache, cleardigits, id, label, maxsilence, maxtime, next, playformat, playvalue, recordformat, repeat, say, termdigits, test, value, value-is, value-is-not
inputdigits	cache, cleardigits, format, id, includetermdigit, label, maxdigits, maxsilence, maxtime, next, repeat, say, termdigits, test, value, value-is, value-is-not, var
joinconference	entertone, exittone, listenonly, termdigits, test, value, value-is, value-is-not
log	test, value, value-is, value-is-not
menu	cache, choices, cleardigits, format, id, label, maxtime, next, repeat, say, termdigits, test, value, value-is, value-is-not
on	event, foreach, next, target, test
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, choices, cleardigits, format, id, say, test, value, value-is, value-is-not
playdate	cache, cleardigits, format, id, termdigits, test, value, value-is, value-is-not
playdtmf	duration, pause, test, value, value-is, value-is-not
playmoney	cache, cleardigits, format, id, termdigits, test, value, value-is, value-is-not
playnumber	cache, cleardigits, format, id, termdigits, test, value, value-is, value-is-not
prompt	cache, choices, cleardigits, format, id, maxtime, repeat, termdigits, test, value, value-is, value-is-not
recordaudio	beep, cleardigits, format, id, maxsilence, maxtime, termdigits, test, timevar, value, value-is, value-is-not
recordcall	info, test, value, value-is, value-is-not
reject	id, value-is, value-is-not
run	cache, id, method, submit, test, value, value-is, value-is-not, var
say	choices, id, test, value-is, value-is-not, voice
sendemail	from, subject, test, to, type, value-is, value-is-not
sendevent	id, session , test, value, value-is, value-is-not
switch	choices, cleardigits, foreach, id, label, next, repeat, test, value, value-is, value-is-not, var
text	cleardigits, termdigits, voice
throw	id, test, value, value-is, value-is-not
transfer	answeronmedia, callerID, id, maxtime, method, playrepeat, playvalue, termdigits, test, value, value-is, value-is-not
wait	choices, id, termdigits, test, value, value-is, value-is-not
with	choices, cleardigits, foreach, id, label, next, repeat, test, value, value-is, value-is-not, var

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.

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.

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.

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.

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.

The 'expr' attribute is a powerful new addition to the CallXML 3.0 markup that allows the developer to use XPath (http://www.w3.org/TR/xpath), features within applications. When used with the <assign> element, this attribute specifies the Xpath data for identifying XML nodes via Location Paths, and the built-in Expressions, and Functions. When using Xpath, note that both the 'expr' and the 'var' and 'value' elements must be specified.'

This attribute defines the variables declared value.

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.

The 'choices' attribute defines a list of comma delimited voice recognition utterances that will be active for the container element. Alternatively, the attribute can contain a choice followed parantheses containing different words which equate to that choice. Note that both dtmf grammars, and spoken word grammar utterances can be defined; digit values always indicate dtmf input, whereas spelled 'literals' for numbers imply that the grammar must be spoken:



<say choices="1, one">press, or say one</say>

One can also define multiple matches to return the same value to the application by specifying the values in the following format:

ContainerElementName choices="ReturnValue (subchoice1, subchoice2)">

As such, either of the 'subchoice' utterances will be interpreted as 'ReturnValue'. To illustrate in greater detail:

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

Lastly, developers can also make use of a built in number grammar for capturing a string of digit values by specifying [x DIGITS], where 'x' is the length of the string that you wish to collect:

<block choices="[5 DIGITS]">

This can also be modified to accept input of varying lengths by specifying [x-y DIGITS], where 'x' and 'y' are the minimum and maximum values for the length of the string being collected:

<block choices="[5-8 DIGITS]">

Note: You must add <assign var="settings.choices.completetimeout" value="10000ms"/> to set the wait time for variable digits. 10000ms=10s wait

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 'foreach' attribute, usable on any CallXML3.0 container elements, should look familiar to many web developers. A developer can indicate a comma-delimited array of values to iterate through within 'foreach' attribute, and then use the 'var' attribute to specify the variable that will hold the current iteration value while in the enclosing container element.

Alternatively, 'foreach' uses the "container.value" variable to store the current iteration if the 'var' is unspecified. and "container.value" will populate any unspecified 'value' attributes of child elements of the container in question.

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 'value' attribute is mappable to any of the container elements, (<block>, <with>, etc.), and specifies inheritance for attribute values that are enclosed within the container element. For instance, the below snippet will denote the values of 'test.wav' for the <playaudio>, <say>, and <log> elements :



<with value="test.wav"</hl>

  <playaudio />

<!-- equivalent to <playaudio value="test.wav">  -->

   <say />

<!-- equivalent to <say>test.wav</say>  -->

   <log />

<!-- equivalent to <log>test.wav</log>  -->

  </with>

The 'var' attribute is used to specify the variable that will hold the current iteration value while in a particular container, when a comma-delimited list of values is to be looped through.

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.

Also be aware that a developer can also use any of the aliases for the <block> element, which are identical in functionality, which allows you to pick a naming/programming scheme for container elements on a per-case basis that suits a developer's programming style. All of these identical <block> aliases are listed as follows:

<block>
<case>
<do>
<if>
<switch>
<with>

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 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 maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.

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 value for this attribute is '3.0'. Do note that it is recommended that you explicitly specify version '3.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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

The 'next' attribute sets the URL the CallXML platform will go to when the container ends.



<with value="test.wav"</hl>

  <playaudio />

<!-- equivalent to <playaudio value="test.wav">  -->

   <say />

<!-- equivalent to <say>test.wav</say>  -->

   <log />

<!-- equivalent to <log>test.wav</log>  -->

  </with>

Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error.

The <case> element is new to the CallXML3.0 markup, and is used in conjunction with the <switch> tag to execute specific blocks of code based on conditional logic. This combination of elements works exactly like the 'traditional' methods used in other markups for 'switch/case', in that the <switch> statement tests an expression against a number of <case> options, and then executes the statements associated with the first <case> that matches the <switch> value.

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 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 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 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 value 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.

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.

The <destroyconference> element is used o tear down active sessions spawned via <createconference> after the session has ended. Failure to destroy active conference sessions can result in degradation of system performance in a locally deployed IVR environment. As such, this element is required to be utilized when leveraging the multi-party conferencing functionality in CallXML 3.0



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

The 'next' attribute sets the URL the CallXML platform will go to when the container ends.



<with value="test.wav"</hl>

  <playaudio />

<!-- equivalent to <playaudio value="test.wav">  -->

   <say />

<!-- equivalent to <say>test.wav</say>  -->

   <log />

<!-- equivalent to <log>test.wav</log>  -->

  </with>

Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error.

The <do> element is a new addition to the CallXML3.0 markup language that serves as a container element, (much like <block> element), for nested XML content. It is commonly used with the new 'foreach' attribute to specify a list of items to iterate through, but can also use the 'container.value' variable to store the current iteration if no 'var=' statement is specified in the nested content.

This attribute is used explicitly to pass parameters from CallXML to CCXML. The variables can be "all" or "*" for everything, or a comma delimited list as shown in the following code example.



<exit submit="test,telephonenum"/>

The variables are received in the dialog.exit event as:



  <log expr="'received : '+event$.values.telephonenum"/>

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.

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

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.

The 'type' attribute allows the developer to specify the data type that is returned from a fetch: This can be useful where a developer needs to access an external document that is not well-formed XML to access string or integer data in the CallXML context.

The 'value' attribute of the <fetch> element is used to specify an .xml or .txt document that the CallXML should retrieve and execute. Used with standard XPath expressions, this allows the developer to bring the external document content to within the CallXML 3.0 context.

The 'var' attribute defines the variable that will store the fetched document's contents within the CallXML 3.0 context. The variable name is then referenced within the other elements of the document, (such as within a 'value' attribute of a container element), to output the contents of the fetched document.

The new <fetch> element, in combination with CallXML 3.0's native support for xpath expression, delivers a powerful way to separate the voice user interface, (VUI), from back-end logic. When using this powerful new addition to the CallXML arsenal, you can develop a fully-realized application without needing to embed server-side markup, (such as ASP/PHP/JSP/etc), within the XML itself. Using <fetch> properly, you can retrieve a document from the url specified in the value attribute, and store the contents of the document in the variable name specified by the var attribute.

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.

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

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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

The 'next' attribute sets the URL the CallXML platform will go to when the container ends.



<with value="test.wav"</hl>

  <playaudio />

<!-- equivalent to <playaudio value="test.wav">  -->

   <say />

<!-- equivalent to <say>test.wav</say>  -->

   <log />

<!-- equivalent to <log>test.wav</log>  -->

  </with>

Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error.

The <if> tag is yet another container element that is identical in functionality to <block>, <do>, <with>, etc., that allows the developer to specify conditional logic using a more 'familiar' syntax. Specifying a 'test' attribute with a value will check to see if a particular condition is met; if so, the application will execute any statements enclosed within the <if> tag, then transition to the anchor specified in the 'next' attribute. If the condition is NOT met, the application will execute the next element it encounters from the top down.

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.

m: minutes
s: seconds (default)
ms: milliseconds

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 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 'say' 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.

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.

m: minutes
s: seconds (default)
ms: milliseconds

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 'say' 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 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)

The value 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 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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

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 'say' 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 'event' attribute is used in conjunction with the <on> handler to specify the specific event name that we wish to filter. Using a generic handler, where we specify the exact condition to catch is much less cumbersome than the CallXML2.0 event handling scheme, where we had to define the correct element name of the event to catch.

The standard syntax for this new method of simple event handling is as follows:

<on event ="answer">
<on event ="callfailure">
<on event ="error">
<on event ="externalevent:user_event_name">
<on event="externalevent:busy">
<on event ="hangup">
<on event ="maxdigits">
<on event ="maxtime">
<on event ="maxsilence">
<on event ="user_event_name">
<on event ="choice:grammar_match">
<on event ="choice:nomatch">
<on event ="termdigit:#">
<on event ="cparesult:human">

The 'next' attribute sets the URL the CallXML platform will go to when the container ends.

The 'target' attribute is another new enhancement to the restructured <on> element that permits the developer to specify what elements a handler can accept events from. At a code level, this means that we can include, or exclude events from a specific handler on a per-case basis, thereby allowing fine-grained control over the event handling schema within the application.

The new <on> element replaces the deprecated <on(EVENTNAME)> handlers from CallXML2.0, and is compliant to the XML events specification, (http://www.w3.org/TR/2003/REC-xml-events-20031014/).
This also provides the developer with a cleaner, and more modular syntactic shorthand for the following CallXML2.0 elements:

<onanswer>
<oncallfailure>
<oncparesult>
<onerror>
<onexternalevent>
<onhangup>
<onmaxdigits>
<onmaxsilence>
<onmaxtime>
<ontermdigits>

The 'next' attribute sets the URL the CallXML platform will go to when the container ends.

DEPRECATED ELEMENT -- use the <on> handler element instead
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

DEPRECATED ELEMENT -- use the <on> handler element instead
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.

DEPRECATED ELEMENT -- use the <on event="cparesult:(result)"> handler element instead
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.

DEPRECATED ELEMENT -- use the <on> handler element instead
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.

DEPRECATED ELEMENT -- use the <on> handler element instead
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.

DEPRECATED ELEMENT -- use the <on> handler element instead
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.

DEPRECATED ELEMENT -- use the <on> handler element instead
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.

DEPRECATED ELEMENT -- use the <on> handler element instead
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.

DEPRECATED ELEMENT -- use the <on> handler element instead
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.

DEPRECATED ELEMENT -- use the <on> handler element instead
Used for catching and handling term digit events as they occur in the call flow.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

The 'say' 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.

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"/>

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.

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.

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'.

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.

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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.

The 'value' attribute specifies a comma-delimited "prompt list" to be output to the caller. If the audio file referenced is not found, then the string value will be output via TTS. The queuing and playback of the audio/TTS strings specified is entirely inherent, and no additional <say> elements are necessary. For instance, both of the snippets below are equivalent:



<prompt value="bread_and_butter, toast_and_jam">

<!-- the same as -->

<playaudio value="bread_and_butter.wav"/>

<playaudio value="toast_and_jam.wav"/>

Also, we can consider these next two snippets to be identical as well:



<prompt value="i like bread and butter, i like toast and jam">

<!-- the same as -->

<say> i like bread and butter</say>

<say>i like toast and jam</say>

The <prompt> element is a new addition to the CallXML3.0 markup that serves as a replacement for the <menu> element...but comes with much, much more in the way of features. Using the <prompt> element allows you to queue up a series of comma-delimited wav files and/or TTS strings, ("prompt lists"), to play to the caller.

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).

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.

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

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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

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 CallXML platform are:

en-us - English Female (Julie)
en-us-female1 - English Female (Kate) This was the previous Prophecy default voice.
en-us-male1 - English Male (Paul)
es-mx - Spanish Female

The new CallXML3.0 <say> element replaces the <text> element used in CallXML2.0, and allows the developer to output a TTS string to the caller. The TTS voice will default to the Prophecy 'English female' called Julie, if left unspecified in the 'voice' attribute.

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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

The 'next' attribute sets the URL the CallXML platform will go to when the container ends.



<with value="test.wav"</hl>

  <playaudio />

<!-- equivalent to <playaudio value="test.wav">  -->

   <say />

<!-- equivalent to <say>test.wav</say>  -->

   <log />

<!-- equivalent to <log>test.wav</log>  -->

  </with>

Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error.

The <switch> element is another new addition to the CallXML3.0 markup. This container element, in conjunction with the <case> tag, allows the developer to emualte the same functionality of a 'switch' in JS/JSP/etc, where a statement can cause a branch in the flow of a program's execution, based on whether or not the values within the <switch> and <case> match.

Also be aware that a developer can also use any of the aliases for the <block> element, which are identical in functionality, which allows you to pick a naming/programming scheme for container elements on a per-case basis that suits a developer's programming style. All of these identical <block> aliases are listed as follows:

<block>
<case>
<do>
<if>
<switch>
<with>

en-us - English Female (Julie)
en-us-female1 - English Female (Kate) This was the previous Prophecy default voice.
en-us-male1 - English Male (Paul)
es-mx - Spanish Female

DEPRECATED ELEMENT -- use the <say> element instead
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.

The 'value' attribute specifies the variable name containing the event to be thrown to the application.

The CallXML3.0 <throw> element is a new addition to the markup that allows the developer to programmatically send an event to the application, (and then handle it, via the <on> element), at any point in the application. This is an extraordinarily useful technique for debugging purposes, as well as initiating a 'shunt' operation that send a caller to a different place in the application based on user input and events.

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

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

Note: The playvalue attribute currently only works on Prophecy 8. For Prophecy 9 - 11, you can use the following workaround:

Spawn a child session using the run element and leveraging the conference element with "hold" music as your transfer audio file. The Voxeo tutorial at Tutorial: Hello World with call bridging describes this workaround.

"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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

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

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.



<say choices="1, one">press, or say one</say>

<say choices="Beatles (john, paul, ringo, george),

              Rolling Stones (mick, keith, charlie, ron)"

       Say the name of a Beatle, or a Rolling Stone.

</say>

The 'next' attribute sets the URL the CallXML platform will go to when the container ends.



<with value="test.wav"</hl>

  <playaudio />

<!-- equivalent to <playaudio value="test.wav">  -->

   <say />

<!-- equivalent to <say>test.wav</say>  -->

   <log />

<!-- equivalent to <log>test.wav</log>  -->

  </with>

Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error.

The <with> element is another container element that is new to the CallXML3.0 platform. It can hold nested XML content, (such as <playaudio>, <text>, etc), and allows the developer to use it's 'value' as syntactic shorthand to populate values for all elements that are nested within it.