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.
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 <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>
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 root callxml element that contains all other elements. This element is required in any callXML documents.
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.
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 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 <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 <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 environmen. As such, this element is required to be utilized when leveraging the multi-party conferencing functionality in CallXML 3.0
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.
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.
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.
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.
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 <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 <inputAudio> element combines the attributes and functionality of a <block> element, <playAudio> element, and a <recordAudio> element.
<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 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 <log> element replaces the deprecated <simline> element for the purpose out outputting debugging text to the Voxeo logger.
Menu is an element that combines the attributes and functionality of a <block> element with a <playAudio> element.
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>
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.
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.
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>
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.
DEPRECATED ELEMENT -- use the <on> handler element instead
This event occurs when another session sends an external event to the current session.
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.
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.
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.
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.
DEPRECATED ELEMENT -- use the <on> handler element instead
Used for catching and handling term digit events as they occur in the call flow.
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 <playdate> element is used to render a given date to the caller via Text-to-Speech.
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 <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'.
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 <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 <recordaudio> element is used to record a caller's voice utterances for future storage and/or retrieval.
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.
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 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 Speechify2.0 'English female' persona, if left unspecified in the 'voice' attribute.
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.
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.
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>
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 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.
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.
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.
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.
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.
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 <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>
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 root callxml element that contains all other elements. This element is required in any callXML documents.
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.
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 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 <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 <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 environmen. As such, this element is required to be utilized when leveraging the multi-party conferencing functionality in CallXML 3.0
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.
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.
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.
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.
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 <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 <inputAudio> element combines the attributes and functionality of a <block> element, <playAudio> element, and a <recordAudio> element.
<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 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 <log> element replaces the deprecated <simline> element for the purpose out outputting debugging text to the Voxeo logger.
Menu is an element that combines the attributes and functionality of a <block> element with a <playAudio> element.
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>
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.
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.
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>
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.
DEPRECATED ELEMENT -- use the <on> handler element instead
This event occurs when another session sends an external event to the current session.
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.
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.
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.
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.
DEPRECATED ELEMENT -- use the <on> handler element instead
Used for catching and handling term digit events as they occur in the call flow.
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 <playdate> element is used to render a given date to the caller via Text-to-Speech.
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 <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'.
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 <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 <recordaudio> element is used to record a caller's voice utterances for future storage and/or retrieval.
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.
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 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 Speechify2.0 'English female' persona, if left unspecified in the 'voice' attribute.
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.
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.
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>
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 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.
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.
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.
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.
Development Guides
