Feedback
Table Of Contents
Cisco Voice Gateway Requirements
Overview of Cisco VoiceXML Features
Voice Store and Forward Feature
Volume and Rate Control Feature
Tcl IVR 2.0 and VoiceXML Integration (Hybrid Applications) Feature
T.37 Store and Forward Fax Detection Feature
cisco-typeaheadflush Attribute for <prompt>
Type-ahead Buffer with <goto> or <transfer> to an Application
Type-ahead Interaction with Barge-In
Typical Call Flow Using Recording
Continuous Fax Detection and Transfer
Cisco Extensions for <transfer>
Authentication and Authorization
Passing Headers in Voice Messages
Example: Passing a SIP URL with Headers Using SIP
Example: Passing a TEL URL with Headers Using H.323
GTD Manipulation, Cisco IOS Release 12.2(11)T
GTD Parameters and Fields Mapped to VoiceXML Variables
GTD Manipulation, Cisco IOS Release 12.3
GTD Object and Parameter Syntax
Reading and Modifying GTD Parameters
GTD Manipulation Sample Scripts
Using <transfer> and <disconnect> for GTD Manipulation
User-to-User Information Manipulation
Release to Pivot: Redirecting Calls for ISUP
Two B Channel Transfer: Redirecting Calls for ISDN
Cisco VoiceXML Features
Revised: October 2, 2009, OL-11175-01This chapter describes Cisco VoiceXML features, and their implementation based on the VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005) and contains the following sections:
•
Overview of Cisco VoiceXML Features
•
•
•
Audience
This guide is intended primarily for developers writing VoiceXML applications using Cisco VoiceXML features. It describes Cisco VoiceXML features based on the VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005) and must be used in conjunction with:
•
•
•
Note
Recommended Knowledge
We recommend you have the following knowledge before using this guide:
•
–
–
–
•
–
–
–
•
–
–
Prerequisites
This section describes the prerequisites necessary to develop a VoiceXML application using Cisco VoiceXML features:
•
•
VoiceXML Document Development
You must write a VoiceXML document using a web-authoring tool, defining your voice application. The document must be installed on a web or file server. A VoiceXML document can also call for the gateway to interact with various web applications (servlets and cgi executables) in which case you must also supply these web applications.
In general, HTTP is the preferred protocol for loading VoiceXML applications and audio prompts. The HTTP client code is implemented in Cisco IOS specifically for this purpose. The Cisco IOS File System (Cisco IFS) protocols (FTP, TFTP) were implemented for loading images, and saving and restoring configurations, so there are limits to the efficiency and number of concurrent loads. HTTP has been developed for efficiency over the Web; it has mechanisms to determine how long a file is considered valid in cache, and to determine if a cached version is still valid. With TFTP, the only way to determine if a cached version is valid is by reloading the entire file.
Pages which are loaded through a pointer within a document using TFTP are not cached on the gateway. TFTP should not be used for loading these dynamic documents. For example, the application attribute of the <vxml> tag and the next attribute in the <goto> tag should not use IFS protocols in the URI. These documents should use HTTP.
Note
For more information, see the following resources:
•
•
•
Note
Cisco Voice Gateway Requirements
For information on hardware and software requirements for the voice gateway, see the Cisco IOS Tcl IVR and VoiceXML Application Guide.
For information on configuring your external media server, see your vendor's documentation:
•
Note
Nuance Recognizer 9.0.1, RealSpeak 4.5.0, and Nuance Speech Server 5.0.1.
Overview of Cisco VoiceXML Features
This section provides an overview of the Cisco VoiceXML features implemented in Cisco IOS Release 12.(2)11T.
•
•
•
•
Note
Applications written in Voice eXtensible Markup Language (VoiceXML) provide access through a voice browser to content and services over the telephone, just as Hypertext Markup Language (HTML) provides access through a web browser running on a PC. The universal accessibility of the telephone and its ease of use makes VoiceXML applications a powerful alternative to HTML for accessing the information and services of the World Wide Web.
Cisco VoiceXML provides a platform for interpreting VoiceXML documents. When a telephone call is made to the Cisco VoiceXML-enabled gateway, VoiceXML documents are downloaded from web servers, providing content and services to the caller, typically in the form of prerecorded audio in an IVR application. Customers can access online business applications over the telephone, providing for example, stock quotes, sports scores, or bank balances.
VoiceXML brings the advantages of web-based development and content delivery to voice applications. It is similar to HTML in its simplicity and in its presentation of information. Cisco VoiceXML is based on the VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005) and is designed to provide web developers great flexibility and ease in implementing VoiceXML applications. Figure 1-1 shows components that can be configured as part of a VoiceXML application installed on a Cisco voice gateway.
Figure 1-1 Cisco VoiceXML Application Components
The following is an example of a call flow for a VoiceXML application:
Note
1.
For instance, the caller could be connected to a business providing sport scores over the telephone.
2.
For example, this business uses a VoiceXML document on an HTTP server to provide baseball game scores.
3.
An application might play a recorded prompt that asks the caller to press a specific dual tone multiple frequency (DTMF) key (for example, "Press 2 for the results of tonight's National League Playoff Game") to hear a spoken sport score ("Giants 4, Mets 0").
4.
For example, the application, after playing the score, might prompt the caller with the message: "If you sign up for a year's service now, you'll be entered in the drawing for two tickets to this year's World Series. Press 5 to contact one of our agents."
The following is an example of a call flow for VoiceXML application using recording:
1.
2.
3.
4.
5.
6.
7.
8.
9.
Voice Store and Forward Feature
The Voice Store and Forward feature in Cisco IOS Release 12.2(11)T expands the capabilities of Cisco VoiceXML to include the input and processing of form field entries using recorded voice clips, instead of numeric input only. This feature uses the VoiceXML 2.0 <record> element to capture voice clips which can then be submitted to an external web server using Hypertext Transfer Protocol (HTTP) or Real Time Streaming Protocol (RTSP), or to a messaging server using Simple Mail Transfer Protocol (SMTP) for additional processing.
This recording feature can be used to collect caller names or addresses for call screening, product registration, or similar e-commerce applications, and for simple voice messaging, or any voice browser application where alphanumeric input using dual tone multifrequency (DTMF) is cumbersome or impractical.
The Voice Store and Forward feature supports speech recording and playout with a choice of four different media targets, including:
•
•
•
•
The Voice Store and Forward feature enables voice messaging by dynamically switching a busy or no-answer voice call to a VoiceXML application. The voice gateway can operate in two modes:
•
•
Volume and Rate Control Feature
The volume of audio prompts can be adjusted during playback. Audio prompts that are played out from an HTTP server using the G.711 codec can also be speeded up or slowed down. A VoiceXML variable contains the rate and duration of the last prompt that was played.
The rate and volume of prompts is controlled by using specific attributes in the VoiceXML document. see the "Volume and Rate Control" section for details.
Note
ASR and TTS Features
Cisco IOS Release 12.4(15)T enables Cisco voice gateways to support automatic speech recognition (ASR) and text-to-speech (TTS) media services through Media Resource Control Protocol version 2 (MRCP v2) which uses Session Initiation Protocol (SIP) and Session Description Protocol (SDP) as session management protocols to create a session and set up media channels to the MRCP v2 server.
Cisco IOS Release 12.2(11)T introduces automatic speech recognition (ASR) and text-to-speech (TTS) capabilities for VoiceXML and Tcl IVR applications on Cisco voice gateways. This release also extends the Cisco VoiceXML interpreter to include support of some VoiceXML 2.0 features.
This release provides interfaces to ASR and TTS media servers using the Media Resource Control Protocol (MRCP), an application level protocol developed by Cisco and its ASR and TTS media server partner, Nuance Communications. MRCP is used to control media service resources such as speech synthesizers for TTS and speech recognizers for ASR. It provides a mechanism for client devices processing audio or video streams to control media resources or devices on external media servers. As shown in Figure 1-2, the Cisco gateway running an IVR application and the media servers providing TTS and ASR functionality maintain a client-server relationship through an RTSP connection; the RTSP client is the gateway and the RTSP server is the streaming media server providing ASR and TTS.
Note
Note
Nuance Recognizer 9.0.1, RealSpeak 4.5.0, and Nuance Speech Server 5.0.1.
Figure 1-2 A Network Implementing ASR and TTS
Tcl IVR 2.0 and VoiceXML Integration (Hybrid Applications) Feature
Tcl IVR 2.0 extensions allow Tcl applications to leverage support for ASR and TTS by invoking and managing VoiceXML dialogs within Tcl IVR scripts. This enables the implementation of hybrid applications using Tcl IVR for call control and VoiceXML for dialog management.
T.37 Store and Forward Fax Detection Feature
When a VoiceXML fax detection application is configured on the gateway, callers can dial a single number for both voice and fax calls. The gateway automatically detects that a call is a fax transmission by listening for CNG, the distinctive fax T.30 "calling" tone. When configured for fax detection, the Cisco VoiceXML gateway continuously listens to incoming calls to determine which calls are voice or fax. The gateway then routes the calls to the appropriate application or media server, as shown in Figure 1-3.
Figure 1-3 Fax Detection on Cisco Gateway
Note
After a call is established, the VoiceXML application can play an audio prompt to the caller while waiting for CNG detection. CNG detection continues for the entire duration of the call, so it is possible that a caller could first be connected to a voice-mail server and leave a voice message, then start to transmit a fax and the application would automatically switch the call to the fax application. After the application detects whether a call is voice or fax, the gateway routes the call based on dial peers. The fax detection application requires at least two dial peers:
•
•
For information on configuring fax relay or store-and-forward fax, see the Cisco IOS Fax and Modem Services over IP Application Guide.
System Output
This section includes:
Describes the playout methods for audio prompts and the types of audio file formats and codecs supported for a Cisco VoiceXML application.
Describes how to control the volume and rate of audio playout.
Describes how a type-ahead buffer works in a VoiceXML application.
Audio Playout
Cisco VoiceXML supports the following types of prompts:
•
•
Prerecorded Audio Prompts
Cisco VoiceXML supports HTTP, TFTP, RAM, RTSP, and flash memory as sources of prerecorded audio prompts for playout. The audio files can be played out in cached or buffered mode, or they can be streamed.
In cached mode, audio files are loaded into the gateway's memory and then streamed from the gateway to the specific call leg. The streaming occurs only after the entire audio file is loaded from an HTTP or TFTP server. The amount of memory required to store these audio files can be controlled by using the ivr prompt memory command. Caching can be performed only with HTTP and TFTP servers. RTSP servers can only conduct real-time streaming of audio files.
Streaming of audio files can be performed by both HTTP and RTSP servers; however there is a difference in the method of streaming. HTTP servers stream files to the gateway in chunks, using the transfer encoding method; RTSP servers stream files continuously to the gateway.
With an HTTP server, use the ivr prompt streamed command to enable the gateway to stream audio files during playout. HTTP prompts are streamed by default but they can be disabled by using the no ivr prompt streamed http command.
With an RTSP server, use the rtsp client timeout connect command to set the number of seconds allowed for the router to establish a TCP connection to an RTSP server. With Cisco IOS Release 15.0(1)M and later releases, use the cisco-maxtime attribute of the <prompt> element to control the playout time for RTSP live streaming. If cisco-maxtime is zero or has no value set, the RTSP stream is played indefinitely.
Cisco voice gateways support .au and .wav file formats, and 14 codecs for audio playout on the PSTN or IP side of a call leg. The VoiceXML document specifies the audio format at the time of recording. If the audio format is not specified, the default format of .au is used. The G.711 codec has an standard industry header that can be recognized by the voice gateway and third-party media players in the industry. However, the other codecs that are supported by Cisco voice gateways have specific Cisco headers that may have to be modified for playout on third-party media players.
For more information on supported codecs, and on how to modify the headers in a codec, see Appendix A, "Audio File Support" in the Cisco IOS Tcl and VoiceXML Application Guide for your Cisco IOS release.
For <audio> playout, the language CLI configuration is not used to locate the audio files. The VoiceXML document uses the full URI in the src attribute of the <audio> element. If src is a relative URL (just the filename), the base attribute of the <vxml> element is used to form a complete URI. If the base attribute is not present, the VoiceXML document uses the URI from where it loads as the base.
Note
Multiple <audio> Playout
If you use multiple audio files within a single <prompt> tag, the document first downloads all the audio files before playing them to avoid playback silence between each audio download. However, if the document cannot load one or more of the audio files, none of the audio files are played. The caller will not hear any playback and the document throws an error event.
Tip
You may also want to preload all or most of the commonly used audio files onto the gateway, or save them in the gateway flash memory instead of the HTTP server.
If you use a single audio file within each< prompt> tag, the document downloads and plays each audio file one at a time. For example:
<prompt><audio src= "http://1.2.16.1/audio/en_welcome.au"/></prompt><prompt><audio src= "http://1.2.16.1/audio/noaudio.au"/></prompt>If the document cannot load an audio file, the caller will hear the welcome prompt before the document throws an error event. Using multiple audio files within a single <prompt> tag works with RTSP because it is streamed; with HTTP, you must use a single audio file within each <prompt> tag.
Using multiple audio files within a single <prompt> tag is only intended for concatenated prompts where playback silence after each download is a concern. For example;
<prompt><audio src="http://1.2.16.1/audio/you_have.au"/><audio src="http://1.2.16.1/audio/3.au"/><audio src="http://1.2.16.1/audio/emails.au"/></prompt>In the above example, because the prompts are concatenated, they must all be embedded within a single <prompt> tag to ensure that the playback will be:
"You have 3 emails."
If you split these concatenated prompts by embedding each one within its own <prompt> tag, as shown below:
<prompt><audio src="http://1.2.16.1/audio/you_have.au"/></prompt><prompt><audio src="http://1.2.16.1/audio/3.au"/></prompt><prompt><audio src="http://1.2.16.1/audio/emails.au"/></prompt>The playback will be:
"You have <silence...> 3 <silence...> emails", which is inappropriate.
Tip
Note
Dynamic Prompts Playout
Note
Dynamic prompts consist of small audio files played out in sequence. The type of language and the TTS notation used in playout is defined by Tcl language modules or built-in language definitions. Cisco IOS software includes built-in modules for English, Chinese, and Spanish. To add support for a new language, you must configure a new Tcl language module on the voice gateway. For information on how to configure a language module, see Enhanced Multi-Language Support for Cisco IOS Interactive Voice Response.
The language and location of the audio files can specified in the VoiceXML document or they can be configured through the CLI by using the call application voice language and the call application voice set-location commands. If only one language is configured in the CLI, then that language is assumed for all documents that do not specify a language.
If the language and location is to be specified in the VoiceXML document, use the xml:lang attribute of the <prompt> element to select a specific language, and to point to the location of the recorded files.
Synthesized Audio Playout
Synthesized audio playout consists of dynamic prompt and text-to-speech (TTS) prompt playout. Dynamic prompts allow basic TTS operations such as playing dollar amounts, time, and dates. An external media server provided by a third-party is required to play TTS prompts. The type of language supported for TTS playout is dependent on the external media server. In the event of an external media server failure, the application developer can implement a backup server through the script. For details, see the "External Server Failure" section.
Text-to-Speech Prompts
For information on SSML, see the Speech Synthesis Markup Language Specification.
Mixed Audio and Text-to-Speech Prompts
Processing of prompts by a Cisco voice gateway depends on the control of the prompt. Prerecorded audio prompts load (or stream) through the Cisco voice gateway without any interaction from the TTS media server. By default, prerecorded prompts load through the voice gateway; however a user can force the voice gateway to direct the SSML to the external media server by modifying the script.
For example, using "alternate text" in <audio src= "audio-to-play"> alternate text </audio> forces the gateway to send the SSML to the media server for playout.For a <prompt> with SSML, the markup (which includes text and prerecorded audio) is sent to the TTS media server by configuring the CLI or using the com.cisco.tts-server property. The level of SSML support, and the types of file formats and codecs supported, are dependent on the support capabilities of the external media server.
Examples
The following example is handled by the TTS media server:
<prompt> this is a sample tts text <break/> with ssml </prompt>The following example is handled by the TTS media server because it contains SSML:
<prompt> this is a sample tts text <break/> with ssml and an audio src <="welcome.wav"/></prompt>The following example is handled by the voice gateway because it contains only .au and src.
<prompt><audio src="one.au"/><audio src="two.au"/></prompt>The following example shows how the voice gateway is forced to play SSML from the media server and the audio source from the gateway.
<prompt> this is a sample tts text <break/> with ssml and audio src </prompt><prompt><audio src="welcome.wav"/></Prompt>The limitations of TTS in the Cisco implementation of VoiceXML 2.0 are:
•
•
•
–
–
•
External Server Failure
In a Cisco VoiceXML solution, the Cisco voice gateway interacts with external media servers for automatic speech recognition, text-to-speech, and streamed recording. If an external media server fails to work, a backup server is desirable to take over the function of the failed media server. A typical approach is to use a content switch that is transparent to the VoiceXML application developer. However, this approach may not be very desirable because of the cost increase.
Cisco VoiceXML provides an alternate solution to external server failure where the application developer can handle server failure directly through the script. A backup external media server must be provided by the third party server vendor, and it must be initially configured on the voice gateway. In the event of a server failure, the VoiceXML interpreter throws an error event which is caught by the VoiceXML application, and the information is passed to a server side application.
The server side application is a web application written as a Java servlet or a Hypertext Preprocessor (PHP) script. For example, an error.noresource event is thrown if the external ASR server fails to operate. The VoiceXML script passes this error event information to a server side web application using the <submit> element. The server side application assigns a new backup media server using the <property> element in all subsequent VoiceXML pages that are generated dynamically.
The original VoiceXML document is regenerated and returned to the VoiceXML interpreter for execution. The regenerated VoiceXML document is similar to the original document with the exception of pointing to the new backup media server instead of the failed server.
Note
Example
This example shows how to recover from media server and HTTP server failures.
color.vxml
<?xml version="1.0"?><vxml version="2.0" xml:lang="en-US" application="root.vxml"><!-- color.vxmlThis is the main VoiceXML document invoked when the user calls into the gateway.This VoiceXML document plays a text-to-speech prompt and waits for user input.If the user's input matches the defined grammar, a prompt is played to indicate his selection.In the form, "colorSelection", the DOCUMENT_STATE and FORM_STATE are used to track theexecution state of this application. When an error event is caught in the root.vxml document, these variables are submitted to the application server. This allows the application server to generate a dynamic VoiceXML document according to the state of execution of this application.-- ><property name="fetchtimeout" value="5s"/><property name="timeout" value="5s"/><property name="interdigittimeout" value="3s"/><property name="termchar" value="#"/><property name="bargein" value="true"/><form id="colorSelection"><block><assign name="DOCUMENT_STATE" expr="'color.vxml'"/><assign name="FORM_STATE" expr="'colorSelection'"/></block><field name="color"><prompt bargein="true">Please select one of the following colors. Say red, blue or green</prompt><grammar version="1.0" xml:lang="en-US" root="colors"><rule id="colors" scope="public"><one-of><item>red</item><item>blue</item><item>green</item></one-of></rule></grammar><filled><prompt>You have selected <value expr="color"/></prompt></filled></field></form></vxml>root.vxml
<?xml version="1.0"?><vxml version="2.0"><!-- This is the root.vxml document which defines the catch handlers, the default properties and application variables.The error.noresource event handler is designed to handle two possible scenarios.The first scenario is a VoiceXML application trying to play a text-to-speech (TTS) prompt and collect user input for recognition. In this scenario, two error.noresource events are thrown.The first error event is thrown because of a TTS failure, the second event is thrown because of an ASR failure. When the first event is caught, an error counter is incremented. This counter is cleared when the second event is thrown.The second scenario is a VoiceXML application trying to play a TTS prompt or trying to conduct a recognition. In this case, only one error.noresource event is thrown.The two forms, "dummyForm" and "resetMediaServer" handle the two scenarios.-- ><var name="WEB_SERVER" expr="'http://httpServer1/'"/><var name="FORM_STATE" expr="'ROOT'"/><var name="DOCUMENT_STATE" expr="'ROOT'"/><var name="ERROR_EVENT" expr=""/><var name="ERROR_COUNTER" expr="0"/><catch event="error.noresource"><log> media resources unavailable</log><assign name="ERROR_EVENT" expr="'MEDIA_RESOURCE_UNAVAILABLE'"/><if cond = "ERROR_COUNTER == 0"><assign name="ERROR_COUNTER" expr="1"/><goto next="#dummyForm"/><else/><assign name="ERROR_COUNTER" expr="0"/><goto next="#resetMediaServer"/></if></catch><!-- This form is to handle the first error.noresource event thrown because of a failure to do Text To Speech --><form id="dummyForm"><block><prompt><audio src="silence.au"/></prompt><goto next="#resetMediaServer"/></block></form><form id="resetMediaServer"><block><log>Document state is <value expr="DOCUMENT_STATE"/> </log><log>Form state is <value expr="FORM_STATE"/> </log><submit expr="WEB_SERVER+'handleError.php'" method="get" namelist=" ERROR_EVENT DOCUMENT_STATE FORM_STATE"/></block></form><catch event="error.badfetch"><assign name="ERROR_EVENT" expr="'BAD_FETCH'"/><assign name="WEB_SERVER" expr="'http://mediaServer2/'"/><prompt>We are having technical difficulties. </prompt> <reprompt/><submit expr="WEB_SERVER+'handleError.php'" method="get" namelist=" ERROR_EVENT DOCUMENT_STATE FORM_STATE WEB_SERVER ERROR_COUNTER"/></catch><catch event="nomatch"><assign name="ERROR_EVENT" expr="'NOMATCH'"/><prompt>I did not get that. Please try again</prompt><reprompt/></catch><catch event="noinput"><assign name="ERROR_EVENT" expr="'NOINPUT'"/><prompt>I did not hear you.Please try again</prompt><reprompt/></catch><catch event ="noinput nomatch error" count="3"><assign name="ERROR_EVENT" expr="'FINAL_TRY'"/><prompt>Sorry,please try again later</prompt><exit/></catch></vxml>handleError.php
<vxml version="2.0" xml:lang="en-US" application="root.vxml"><!-- This PHP script handles the different error events and generates a dynamic VoiceXML document in response to a request by the root.vxml document. When a media server error is detected, the PHP script sets the properties for a backup media server.When a HTTP server is detected, the PHP script sets the global variable for the HTTP server. -- ><form id="handleError"><?phpif($ERROR_EVENT==MEDIA_RESOURCE_UNAVAILABLE){if(($FORM_STATE) && ($DOCUMENT_STATE)) {echo("<property name=\"com.cisco.asr-server\" value=\"rtsp://mediaServer2/recognizer\"/><property name=\"com.cisco.tts-server\" value=\"rtsp://mediaServer2/synthesizer\"/><block><log> Assign to a new media server </log></block>");}} elseif($ERROR_EVENT==BAD_FETCH){echo("<var name=\"WEB_SERVER\" expr=\"'http://backupServer/'\"/><block><log> Assign a backup web server </log></block>");} else{echo("<block><log> Fail to assign a new media server </log></block>");}?><property name="fetchtimeout" value="5s"/><property name="timeout" value="5s"/><property name="interdigittimeout" value="3s"/><property name="termchar" value="#"/><property name="bargein" value="true"/><block><assign name="DOCUMENT_STATE" expr="'color.vxml'"/><assign name="FORM_STATE" expr="'colorSelection'"/></block><field name="color"><prompt bargein="true">Please select one of the following colors. Say red, blue or green</prompt><grammar version="1.0" xml:lang="en-US" root="colors"><rule id="colors" scope="public"><one-of><item>red</item><item>blue</item><item>green</item></one-of></rule></grammar><filled><prompt>You have selected <value expr="color"/></prompt></filled></field></form></vxml>Volume and Rate Control
The attribute cisco-vcrprompt of the <prompt> element is used to control volume and the attribute cisco-rate specifies the rate of prompt playout. To control the playout volume or the rate of playout, set the cisco-vcrprompt attribute to TRUE before you use the <cisco-vcrcontrol> element. To enable volume and rate control, the <prompt> element uses two attributes cisco-vcrprompt and cisco-rate. The element <cisco-vcrcontrol> allows you to control the playback volume or the playout rate. For details on elements and their attributes, see <vcrcontrol> in Table B-1 in "Cisco VoiceXML Elements: Reference Table.". For information on implementing grammar for volume and rate control, see the "Implementing Grammar for Volume and Rate Control" section.
Note
You can control the volume and rate of audio prompt playout as described in the following sections:
Volume Control
You can control the playout volume by setting the output attenuation of the DSP. Volume control is supported only for PSTN ports, and has a range of -14 to +16 dB. The volume level, set in discrete steps of +1 or -1 dB, is valid for the entire duration of a call, unless you change it in the middle of a call. The new volume level is effective from the point at which you make the change. However, if you use the <transfer> tag, the volume level is reset to the default level. Volume control works across all codecs that are supported by Cisco's implementation of VoiceXML 2.1. It also works for IFS, RTSP, HTTP, TTS, recorded prompt playout, and dynamic prompts.
To enable volume control, set cisco-vcrprompt to TRUE and set volume as the value for the action attribute. Use the step attribute to change the playout volume. The step value for volume control is indicated as follows:
•
•
•
•
•
•
Note
•
•
•
On the Cisco AS5400, prompt playout is attenuated from the recorded volume. Since the default output attenuation is 0dB on the Cisco AS5400, record the prompts at a higher volume and then attenuate them in a normal manner.
In the example below, if a caller enters 1, it raises the volume by 2dB. If the caller enters 2, it reduces the volume to the minimum level. If the caller enters 3, it returns the volume to the default level.
<?xml version="1.0" ><vxml version="2.0"><form scope="document" id="get_msg"><cisco-vcrcontrol dtmf="1" action="volume" step="+2"/><cisco-vcrcontrol dtmf="2" action="volume" step="-99"/><cisco-vcrcontrol dtmf="3" action="volume" step="0"/><cisco-vcrcontrol dtmf="4" action="rate" step="+2"/><cisco-vcrcontrol dtmf="5" action="rate" step="-2"/><cisco-vcrcontrol dtmf="6" action="rate" step="0"/><block><prompt cisco-vcrprompt="true" bargein="false" cisco-rate="1"><audio src="http://msgserver/YourMessages/NextMsg.au"/></prompt></block></form>Rate Control
You can control the playout rate through the step attribute of the <cisco-vcrcontrol> element, allowing you to speed up or slow down the playout rate of an audio prompt. Rate control is implemented by dropping or duplicating packets for the defined rate, and is applicable only to HTTP based prompts for chunk and RAM based playout. Only the G.711 codec is supported.
To enable rate control, set cisco-vcrprompt to TRUE, and set rate as the value for the action attribute. For the attribute cisco-rate, use a value in the range of -4 to +4 to set the absolute playout rate. To set a step change in the playout rate, use the attribute step.
The step value for rate control is indicated as follows:
•
•
•
•
Note
•
Table 1-1 indicates step values for rate control.
Prompt Timing
To hold information about the last prompt that is played, use the Cisco specific application variable application.lastprompt$. It holds information about the last prompt that is played through the read-only variables application.lastprompt$.duration and application.lastprompt$.lastrate. For details on Cisco specific application variables, see the "Application Variables" section.
Information on timing for the last prompt is set to the application.com.cisco.lastprompt$ variable when:
•
or
•
or
•
or
•
Examples
In the example below, when <submit> tries to use the application variable lastprompt$, the timing information for prompt A is not defined because prompt A is still queued for playing when <submit> is executed. In this case, the lastprompt$ variable has value "undefined", or it may still contain timing information of the previous prompt from the last input collection.
<block><prompt A/><submit application.com.cisco.lastprompt$.../>In the example below, a prompt is queued before a <goto> statement.
•
•
•
<block><prompt B/><goto next="next.vxml"/>If a digit is handled by an item that has volume and rate control, it is unavailable to a field or menu that is active at the same time.
Type-ahead Support
Cisco VoiceXML includes a type-ahead buffer that holds DTMF digits collected from the caller. When the VoiceXML form interpretation algorithm collects user DTMF input, it uses the digits from this buffer before waiting for further input. For example, if the caller knows ahead of time that the document will prompt for account, PIN, and destination, and ask the caller to listen to the welcome message, then the caller can enter all the digits in advance without waiting.
In the <prompt> element, a set of audio tags with bargein enabled is played out as a group. The group of prompts is interrupted when the digit is received by the gateway, independent of when the digit is pulled out of the type-ahead buffer. A bargeinable prompt will not start playout if there are digits in the type-ahead buffer. This means multiple prompts may not be played because of a single digit entering the type-ahead buffer.
For a simple example, if a noninterruptable prompt (bargein=FALSE) is played, the set of digits received during that playout are put into the type-ahead buffer without interrupting the prompt. If the next field plays out a prompt with bargein=TRUE, that prompt will not play if there are digits in the type-ahead buffer.
For a more complex example, consider a document that plays an interruptible prompt without collecting digits. After the document transitions to another document, the new document plays an interruptible prompt while collecting a single digit, and finally plays a third interruptible prompt. If the caller enters a digit during the first prompt, it interrupts that prompt. When the second document is loaded, the initial interruptible prompt is not played because there is a digit in the type-ahead buffer. The third prompt is played because the digit collection consumed the digit from the type-ahead buffer.
A prompt with volume and rate control can have bargein=FALSE. For bargein=TRUE, the digits that are not handled or ignored by <cisco-vcrcontrol> stop prompt playout. If the field collects digits against a pattern with bargein enabled and <cisco-vcrcontrol> active, the prompt is not interrupted until the entire pattern is matched.
Buffer Control and Flushing
The VoiceXML specification does not provide information on explicit control over the type-ahead buffer. The type-ahead buffer is always enabled when a call comes in. It is flushed if a <grammar> tag in a field uses a regexp that does not match any digits in the buffer. This causes a nomatch event each time digits pulled from the buffer do not match the regular expression. By default, the typeahead buffer is automatically flushed when processing a nomatch event or a <reprompt> element. To override this default behavior, set the com.cisco.autoflush property to false where this change is required.
If the call is transferred to a third party with long-# enabled, the type-ahead buffer is flushed looking for the long-# digit in the type-ahead buffer. Therefore, a long-# entered during call setup will disconnect the call as soon as the setup completes and the system checks the buffer. Digits from the buffer are not played out toward the third party.
cisco-typeaheadflush Attribute for <prompt>
The default value of cisco-typeaheadflush is false. A false value means that the typeahead buffer is not flushed after the prompt plays out. If the prompt is bargeinable, the digit which barges in is not flushed.
com.cisco.autoflush Property
The type-ahead buffer is flushed by default for a nomatch or reprompt event. If the autoflush property is set to false, the type-ahead buffer is not flushed. For example, consider a document that has a nonbargeinable prompt followed by a collection pattern of 125. If a caller enters 1234 during the prompt, the document tries to collect 125 based on the collection pattern. The document reads 1, 2, 3, then gets a nomatch and flushes the 4.
If there is a nomatch event and audio is played inside it, the flush occurs immediately after the nomatch. The system handles the event which means that the caller can re-enter digits during the prompt playout.
Type-ahead Buffer with <goto> or <transfer> to an Application
Tcl applications do not utilize the type-ahead buffer, so calls handed from Tcl applications do not support type-ahead until the call is being handed from the VoiceXML application. If the call is handed between VoiceXML documents either using <goto> or using the <transfer> tag with an outbound VoiceXML application, the type-ahead buffer is active. It is not flushed during the handoff.
Type-ahead Interaction with Barge-In
A bargeinable prompt will not start playout if there are digits in the type-ahead buffer. See the "Prerecorded Audio Prompts" section for more details on this operation.
If bargein occurs during any prompt in a sequence, all subsequent prompts are not played, even those prompts whose bargein attribute is set to false. In the following example, if a digit is received during the first prompt playout, the second and third prompts will not play.
<field name="field1" ><grammar type="application/grammar+regex">.*</grammar><prompt bargein="false"><audio src="press1_2.au"/></prompt><prompt bargein="true" ><audio src="long_2m.au"/></prompt><prompt bargein="false"><audio src="en_welcome.au"/></prompt>...</field>A prompt with volume and rate control can have a bargein value of false. Digits that are ignored will stop prompt playout if the bargein value is true. Digits that are not used for volume and rate control are put in the typeahead buffer. If a field collects digits against a pattern with bargein enabled and, volume and rate control active, the prompt is uninterrupted until the entire pattern is matched.
The typeahead buffer is always flushed if there are digits in the typeahead buffer when playout starts for a prompt with volume and rate control.
User Input
VoiceXML allows two types of user input, voice and DTMF. Cisco VoiceXML accepts both types of input and processes them either through an external media server or through the voice gateway itself, depending on the type of input and grammar used to collect the input. For user input recognition based on DTMF, the voice gateway is capable of recognizing that input without the help of any external media recognition devices. Regex is the only grammar format supported for DTMF based recognition. Recognition of user input such as ASR or TTS involves an external media server working in conjunction with the voice gateway. The grammar formats required to process ASR and TTS based input are dependent on the support provided by the media server vendor. All external media servers are required to support at least the W3C XML grammar format. Media server vendors may support other standard or proprietary grammar formats such as Nuance's GSL grammar format.
Note
Voice Input
To handle voice input, an external media server is required to work with Cisco voice gateway. The media server conducts automatic speech recognition (ASR) and communicates the interpretation back to the VoiceXML interpreter, running on the voice gateway, for processing.
Cisco VoiceXML only supports W3C XML grammar for speech recognition. The user can dynamically change the media server for the next ASR by setting the Cisco specific VoiceXML property "com.cisco.asr-server" in the VoiceXML script. For example, the statement,
<property name= "com.cisco.asr-servervalue"= "rtsp://asr-server/recognizer"/> sets "rtsp://asr-server/recognizer" as the external media server for the next ASR, and continues with the same setting until the property is set again with a different server.
DTMF Input
To handle DTMF input, Cisco VoiceXML uses either an external media server or the Cisco voice gateway, which is capable of handling all DTMF applications.
For an external media server to collect DTMF input, use W3C XML grammar. For a Cisco voice gateway to collect DTMF input, use Cisco specific DTMF grammar.
Note
The user can dynamically change the media server for the next DTMF recognition by setting the Cisco proprietary VoiceXML property com.cisco.asr-server in the VoiceXML script.
Grammar Support
Cisco VoiceXML supports two types of grammar, W3C XML grammar and Cisco specific DTMF grammar. W3C XML grammar is used to collect both voice and DTMF input. Cisco specific DTMF grammar is only used to collect DTMF input.
Note
For all grammars that are automatically generated by the VoiceXML interpreter from <choice>, <option> and builtin, W3C XML grammar is the default. However, if at least one specific Cisco DTMF grammar is used in the application, all the automatically generated grammars are in Cisco specific DTMF grammar format.
XML Grammar
Cisco's VoiceXML interpreter supports the standard W3C XML grammar format. For user input using W3C XML grammar, an external media server is required. The interpreter does not process grammars; it checks the grammar for syntax. The external media server processes the grammar. Deviations from W3C XML grammar introduced by the media server are imposed on Cisco's implementation of VoiceXML. For example, with the current media server integrated with Cisco VoiceXML, the deviations are:
•
•
For more information on W3C XML grammar format, see Speech Recognition Grammar Specification for the W3C Speech Interface Framework (W3C Working Draft, 20 August 2001).
Cisco DTMF Grammar
The Cisco dual tone multiple frequency (DTMF) grammar supported is a regular expression (Regex) grammar. The media type of the grammar is application/grammar+regex. Cisco DTMF grammar has the following limitations:
•
•
•
Cisco DTMF grammar supports the following metacharacters:
Only the previously listed metacharacters are supported. When an unsupported metacharacter is used, no error will be triggered. However, input recognition will produce unexpected results.
In addition to matching the original pattern, the DTMF grammar matches the original pattern followed by extra digits. Matching of extra digits occurs only if the repetition operators are at the end of a pattern.
Regular expression for DTMF grammar allows you to use only empty spaces instead of the operator | to join characters.
For example:
•
<grammar type= "application/grammar+regex">\* .+</grammar>
The <field> builtin types digits and number accept any nondigit input. A nomatch event is not generated.
Implementing Grammar for Volume and Rate Control
The element <cisco-vcrcontrol> is used for volume and rate control of an audio prompt playout. For more information on using <cisco-vcrcontrol>, see the element <cisco-vcrcontrol> in Table B-1 in "Cisco VoiceXML Elements: Reference Table" and the "Volume and Rate Control" section. In-line DTMF grammar is used. External and ASR grammar is not supported.
Note
Applicable volume and rate control grammars are active when the interpreter plays a prompt <cisco-vcrcontrol> turned on. Volume and rate control can be applied to any prompt inside a VoiceXML document. For a prompt inside <field> or <menu>, volume and rate control grammar takes precedence over DTMF input grammar if both are active at the same time.
Volume and rate control grammar activates in the following order:
1.
2.
3.
4.
The grammar closest to the applicable item is activated.
Some dependencies for the scope of volume and rate control grammar are:
•
•
•
•
•
•
–
–
Recording Support
This section contains the following information about recording support:
•
For recording, the following four recording destinations are supported:
•
•
•
•
The recording is stored as a VoiceXML field item variable and can be referenced in the VoiceXML application document. The VoiceXML browser plays an audio file for a specific URI (<audio src=filename>) in a VoiceXML document and the recorded input can be played back using <value> or by submitting it to the server with <submit method= "post+enctype"= "multipart/form-data"/> saved as an audio file.
Note
Recognition of grammars during recording is supported in Cisco IOS Release 12.4(15)T and later releases. On the POTS call leg, recording with ASR grammar is supported in the G.711 u-law codec only. On the VoIP call leg, recording with ASR grammar is not supported.
Note
RTSP, SMTP and HTTP recording is done by streaming the voice data to the specified external server. The "cisco-dest" attribute is used to specify the target destination. If "cisco-dest" is not specified, the default target destination is RAM.
Using cisco-dest
The attribute "cisco-dest" is a specific Cisco attribute that points to a URL specifying a recording destination. The three recording choices are:
•
HTTP recording is done by streaming voice data to an HTTP server. The <record> name variable is not applicable. The HTTP URL must point to an application on the server which accepts the data and writes it into a file. Playback can be achieved by referring to the HTTP URL specified in <record>.
•
Specifying the recording URI causes the message to be streamed directly to an RTSP server. Here, the <record> name variable is not applicable. The RTSP URL must point to an application on the server which accepts the data and writes it into a file. Playback can be achieved by referring to the RTSP URL specified in <record>.
Recording status is returned by shadow variable name$.status (see Shadow Variables).
•
The message streams in real time to an SMTP server.
To write a VoiceXML document user interface for a simple voice mail system, use the <record> element with the attribute cisco-dest.
You can use <record cisco-dest> to record a voice message and deposit it at an external server for later retrieval. This extension works with another Cisco extension of <record> so that it can interoperate with the .au file format and with PC clients.
Recording ends when:
•
•
•
•
Table 1-2 gives information on Cisco-specific applications of the attributes for <record>:
Shadow Variables
Standard shadow variables from VoiceXML 2.1 are supported, including the following:
•
•
•
•
•
•
•
RAM Recording
You can play a RAM recording by referring to its variable name and using <prompt> and <audio expr= "nnn"/> together where "expr" is the recording name variable.
Note
Here is an example of playing a recording:
<vxml><form><record name="myrec" beep="false" maxtime="10s" dtmfterm="true" type="audio/basic;codec=g711ulaw"></record><block><prompt> Your recording is <audio expr="myrec" /></prompt></block></form></vxml>The RAM recording can then be saved to a server, as shown in the following example, where the Record.php script saves the file and returns a VoiceXML document.
<block><submit next="http://myserver/mypath/Record.php"namelist="myrec" method="post" enctype="multipart/form-data"/></block>Playing recording by referring to the RTSP, HTTP, or SMTP recording variable in <value expr> results in an error; an error.semantic event is thrown and an error message "cannot playback a streaming recording" is generated.
The other types of recording (RTSP, HTTP and SMTP) cannot be played back by referring to the <record> name variable because they are directly streamed to the external server.
For RTSP and HTTP, the recording can be played back by <audio src= "nnn"/> where "src" specifies the recording URL.
HTTP Recording
For HTTP recording, a PHP script must reside on the server. It is used to copy the recorded audio files into one of the server directories.
Here is an example of a VoiceXML 2.0 script for HTTP recording (nonstreaming mode) and the PHP servlet that is used to upload the audio files into a server directory.
Example
<form><record cisco-dest="http://goa/php/recordhttp.php?audiofile=httprecordaudio.au" dtmfterm="true"/><block>Your recording is <audio src="http://goa/httpaudio/httprecordaudio.au"/></block></form>In this example of HTTP recording, the PHP script http://goa/php/recordhttp.php?audiofile=httprecordaudio.au copies the audio file into the http://goa/httpaudio/httprecordaudio.au file.
Exception Handling
In addition to supporting standard error types in VoiceXML 2.1, the following application-specific error types are supported:
•
This event is thrown when a RTSP server communication error is generated; nnn is the corresponding protocol error code.
•
This event is thrown when the user specifies an unsupported audio format, codec type, or recording destination URL. If the codec specified by the user mismatches the codec type that is configured for VoIP, the VoIP configured codec is used for the recording and a warning message is generated to notify the user of the codec being used.
Note
error.badfetch.http.response_code
error.badfetch.protocol.response_code
Properties for <record>
You can use properties to specify the default attribute values for <record>. See the "Property" section and Table 1-9 for a list of Cisco specific properties that are supported for <record>. These properties can be specified at <vxml>, <form>, and <record> level, and allow the user flexibility in specifying a default value. The Cisco implementation of VoiceXML 2.1 supports message disposition notification (MDN) and delivery status notification (DSN).
The MDN address is specified by the following specific Cisco VoiceXML Properties:
•
Setting com.cisco.mta.send.mdn_request to TRUE sends the MDN request.
•
If these properties are not specified, the MDN address is composed by configuring the mta send return-receipt-to hostname and mta send return-receipt-to username Cisco IOS commands. If these commands are not configured, the MDN address is composed by configuring the mta send postmaster email-address command. If this command is not configured, the mta send mail-from command is used. For information on configuring these Cisco IOS commands, see the Cisco IOS Tcl IVR and VoiceXML Application Guide for your Cisco IOS release and the Cisco IOS Fax and Modem Services over IP Application Guide.
DSN is specified by the following specific Cisco VoiceXML properties:
•
•
•
The subject header is specified by the com.cisco.mta.send.subject property. If this property is not defined, the subject field of the e-mail header is set by using the mta send subject Cisco IOS command.
The following specific Cisco properties are also supported for platform-specific settings for SMTP:
•
•
•
•
Note
•
•
Typical Call Flow Using Recording
The following call flow illustrates recording:
1.
2.
3.
4.
5.
6.
7.
The VoiceXML application must be able to handle the case the user hanging up before choosing to submit the voice message.
8.
9.
10.
<cisco-data> Element
The <cisco-data> element allows an application to load data from a server for handling a call. It allows voice applications to send and receive information from an external server when answering and transferring calls.
For call center applications, the VoiceXML <transfer> element is limited because it can only inform the HTTP server if the call does not connect because of:
•
or
•
or if the call disconnects because of:
•
or
•
VoiceXML 2.0 does not support an event when the <transfer> connection is made and the two parties start talking to each other. However, this limitation can be overcome by using a Cisco VoiceXML hybrid script in which the Tcl script performing the transfer can use the <cisco-data> element to send a GET or POST HTTP request to a web server.
The VoiceXML interpreter running on a gateway uses the <cisco-data> element to post data to a server, and receives that data back from the server without transitioning to a new VoiceXML document. The <cisco-data> element occurs as executable content, or as a child of <form> or <vxml>. It has the same scoping rules as the <var> element. If a <data> element has the same name as a variable declared in the same scope, that variable is assigned a value retrieved by the <data> element.
If the name attribute is specified and the data is not retrieved, the VoiceXML interpreter throws an error event error.badfetch.http.nnn to indicate a fetch failure.
Note
•
•
The attributes of <cisco-data> are:
•
The URI specifying the location of data.
•
The name of the variable that contains the retrieved data. If this field is deleted, data can only be sent to the server, not retrieved.
•
The URI specifying the location of the data. The URI is dynamically determined.
•
Similar to the method attribute of the <submit> element in the VoiceXML 2.0 specification.
•
Similar to the namelist attribute of the <submit> element in the VoiceXML 2.0 specification.
•
Similar to the enctype attribute of the <submit> element in the VoiceXML 2.0 specification.
•
Similar to the fetchhint attribute of the <submit> element in the VoiceXML 2.0 specification.
•
Similar to the fetchtimeout attribute of the <submit> element in the VoiceXML 2.0 specification.
•
Similar to the fetchaudio attribute of the <submit> element in the VoiceXML 2.0 specification.
•
Indicates that the document is willing to use content whose age is no greater than the specified time in seconds. Compare to max-age in HTTP 1.1, RFC 2616. The document is not willing to use stale content, unless maxstale is also provided. If not specified, a value derived from the innermost relevant maxage property, if present, is used.
•
Indicates that the document is willing to use content that has exceeded its expiration time. Compare to max-stale in HTTP 1.1, RFC 2616. If maxstale is assigned a value, then the document is willing to accept content that has exceeded its expiration time by no more than the specified number of seconds. If not specified, a value derived from the innermost relevant maxstale property, if present, is used.
DTD for <cisco-data>
<!ELEMENT cisco-data EMPTY><!ATTRLIST cisco-datasrc %uri #IMPLIEDname NMTOKEN #IMPLIEDexpr %expression; #IMPLIED%cache.attrs;%submit.attrs; >Example
This example shows the use of <cisco-data> in posting information to a server and receiving that data back from the server.
In this example:
•
•
•
•
•
•
<vxml version="2.0"><form><var name="a" expr="123"/><var name="b" expr="456"/><block><cisco-datasrc="http://townsend.cisco.com/cgi-bin/rama.tcl"name="MyData"method="post"namelist="a b"></cisco-data></block><block><log> Yes. DATA received successfully.<value expr="MyData"/></log></block></form></vxml>Transfer Support
Note
The <transfer> element can place a call to a destination for the caller. This tag triggers the outbound dial peer selection and call setup.
Recognition of ASR and regular expression grammars during transfer is supported in Cisco IOS Release 12.4(15)T and later releases. A call handled between VoiceXML documents using the <transfer> tag with grammar can support the G.711 u-law codec only on the VoIP dial peer.
Note
Cisco Longpound Attribute
The most common case is to connect a caller through the Cisco gateway to a third party over any network the gateway supports. For this case, Cisco has implemented a cisco-longpound attribute for <transfer>, long-#, to allow the caller to terminate the connection by holding the pound (#) key down for more than a second. The Boolean value of this attribute specifies if long-# is used to terminate a transfer.
In the case of a bridging transfer, holding down the # key for more than a second resumes the session with the interpreter.
Note
Cisco-newguid Attribute
If you are a VoiceXML document writer, you can use the cisco-newguid attribute to specify that the call requested by the <transfer> tag will be made using a new globally unique identification (GUID) instead of inheriting the GUID of the incoming call leg. The use of this attribute is significant when a single inbound call generates multiple outbound calls (for example, in a debit card application, the user can make several calls in a single session).
For more information on GUID, see VSA number 24 (h323-conf-id=value) in Table 2 of the RADIUS Vendor-Specific Attributes Voice Implementation Guide.
You can specify the cisco-newguid attribute if:
•
or
•
The cisco-newguid attribute resolves to a boolean value with a default value of false.
For example:
<transfer...cisco-newguid="true">!assign a boolean value directly<transfer...cisco-newguid="new_guid">!new_guid is a variable that contains the boolean value "true" or "false".<transfer ... cisco-newguid="call_count > 0">!where call_count is a number variable tracking the number of calls made so far for this session.Continuous Fax Detection and Transfer
Cisco VoiceXML supports continuous CNG tone detection during all phases of a call. While the application is listening for CNG tones, VoiceXML scripts are being loaded and executed to play prompts, record voice, process DTMF input, etc.
When the VoiceXML script is running, the application continuously listens for CNG tones. When CNG is detected, a CNG tone detection event is passed to the VoiceXML application which in turn generates the VoiceXML event com.cisco.fax.cng.
This event is specific to Cisco's VoiceXML implementation. The VoiceXML document has to define a catch event handler to process this fax event. It may choose to respond to the fax and send it through T.37 Store & Forward by a blind transfer invoked by <transfer dest="fax://[dnis-to-match-dp]" bridge="false" cisco-mailtoaddress="[email-id]"> in a block outside the catch event handler of com.cisco.fax.cng.
Note
Fax Mailto Addressing
Cisco VoiceXML allows full control of e-mail addresses by providing the cisco-mailtoaddress attribute in the <transfer> element and the $e$ macro in the MMoIP dial peer. The cisco-mailtoaddress variable in the transfer element replaces the $e$ in the mailto address. In the VoiceXML script, the e-mail address can be constructed in the cisco-mailtoadress attribute through one of the following:
•
•
•
•
•
The VoiceXML document defines an e-mail address through the cisco-mailtoaddress variable in the <transfer> element.
Note
The VoiceXML application maps the cisco-mailtoaddress attribute to the e-mail address only if the $e$ macro is configured in the MMoIP dial peer. By default, if the cisco-mailtoaddress variable is not specified in the transfer element, the VoiceXML application maps the DNIS to $e$. The attribute cisco-mailtoaddress is optional in the <transfer> element. If the attribute is not specified, the VoiceXML application maps the e-mail ID to DNIS. Cisco VoiceXML is also capable of setting the MMoIP session mail-to $e$ variable to DNIS, RDNIS, or a string that represents a valid e-mail address.
$e$ is capable of accepting any of the following e-mail addresses:
•
•
•
•
•
•
•
Note
Example
This example shows a Cisco VoiceXML script (VoiceXML 2.0) used for CNG detection.
<?xml version="1.0"?><vxml version="2.0" base="tftp://audio directory path/"><catch event="com.cisco.fax.cng"><log>!!!!!!! Got com.cisco.fax.cng !!!!!! </log><goto next="#transferToFax"/></catch><catch event="nomatch noinput"><goto next="#transferToPhone"/></catch><catch event="telephone.disconnect.transfer"><log>!!!!!!! Got telephone.disconnect.transfer </log></catch><catch event="telephone.disconnect.hangup"><log>!!!!!!! Got telephone.disconnect.hangup </log></catch><catch event="error.badfetch"><log>!!!!!!! Got ERROR.BADFETCH !!!!!! </log></catch><var name="phone_num"/><var name="mydur"/><var name="defaultPhoneNum" expr="session.telephone.dnis"/><var name="junkvar"/><property name="timeout" value="9s"/><form id="main"><field name="get_phone_num" type="number"><dtmf type="regex">.......</dtmf><prompt bargein="true"> <audio src="audio/menu.au"/> </prompt><filled><assign name="phone_num" expr="get_phone_num"/><log>The number collected is <value expr="phone_num"/></log><goto next="#transferToFax"/></filled></field></form><form id="transferToFax"><block><assign name="phone_num" expr="5550112"/><log>Transferring to <value expr="phone_num"/></log></block><transfer name="mycall" destexpr="'fax://'+ phone_num" bridge="false" connecttimeout="15s" maxtime="180s" cisco-longpound ="true" cisco-mailtoaddress="user name" ><filled><assign name="mydur" expr="mycall$.duration"/><log>The value in mycall is <value expr="mycall"/></log><log>Duration of call is <value expr="mydur"/></log></filled></transfer></form><form id="transferToPhone"><block><assign name="phone_num" expr="5550112"/><log>Transferring to <value expr="phone_num"/></log></block><transfer name="mycall" destexpr="'tel: '+ phone_num" bridge="true" connecttimeout="150s" maxtime="180s" cisco-longpound ="true" ><filled><assign name="mydur" expr="mycall$.duration"/><log>The value in mycall is <value expr="mycall"/></log><log>Duration of call is <value expr="mydur"/></log></filled></transfer></form><form id="transferToFax"><property name="timeout" value="500s"/><field name="get_phone_num" type="number"><dtmf type="regex">.......</dtmf></field></form></vxml>Transfer Form Item Variable
The transfer form item variable is used to store the outcome of the transfer attempt. In VoiceXML 2.0, the possible values are: "busy", "noanswer", "network_busy", "near_end_disconnect", "far_end_disconnect", and "network_disconnect."
For a blind transfer, the value is "success" if the transfer was successful. The other possible values are "busy", "noanswer" and "network_busy."
Outcomes not described in the values provided in the specification are declared "unknown."
Cisco Extensions for <transfer>
Cisco VoiceXML supports specific Cisco telephony attributes listed in Table 1-3 in addition to supporting the standard VoiceXML attributes "dest" and "connecttimeout."
When the <transfer> element uses specific Cisco attributes to set signaling information in a transferred call, the voice gateway transfers the signaling information to remote equipment. If the gateway handling the incoming call contains a VoiceXML document, the signaling information is also available to the VoiceXML document as a set of session variables. Table 1-4 lists attributes of the <transfer> element mapped to specific Cisco VoiceXML variables for an incoming call.
The example below shows some of the specific Cisco attributes included in the <form> element:
<?xml version="1.0"><vxml version="2.0"><form id = "transfer"><var name="mydur"/><block><audio src="http://myserver/welcome.au"/></block><transfer name="mycall" dest="tel: 18005550134"connecttimeout="30s" bridge="true"cisco-username="1234-5678-ABCD-WXYZ"cisco-aniexpr="'tel: ' + (4085260000 + 1234)"cisco-anitype="0" cisco-aniplan="1"cisco-anipi="0" cisco-anisi="0"cisco-rdn="tel: 4085261000"cisco-rdntype="0" cisco-rdnplan="1"cisco-rdnpi="0" cisco-rdnsi="0"cisco-redirectreason="10"cisco-desttype="0"cisco-destplan="1"><audio src="http://anyname.anycompany.com/jdoe/spacemusic.au"/><filled><!-- call should pass andmycall$duration has new val --><assign name="mydur" expr="mycall$.duration = 99999"/><if cond="mycall$.duration == '11111111'"></if></filled></transfer><block><if cond="mycall$.duration"></if><goto next="#transfer2"/></block></form><form id = "transfer2"><block><if cond="mycall$.duration"></if></block></form></vxml>Definitions of Subfields For ANI, DNIS, and RDNIS
The subfields for ANI, DNIS, and RDNIS are defined below. For more details, see ITU-T Q.931, ISDN User Network Interface Layer 3 Specification for Basic Call Control.
Note
•
•
Type of Number
3 bits for ANI, DNIS, and RDNIS
Field values
0 = Unknown
1 = International number
2 = National number
3 = Network specific number
4 = Subscriber number
6 = Abbreviated number
Numbering Plan Identification
4 bits for ANI, DNIS, and RDNIS
Field values
0 = Unknown
1 = ISDN/telephony numbering plan
3 = Data numbering plan
4 = Telex numbering plan
8 = National standard numbring plan
9 = Private numbering plan
Presentation Indicator
2 bits for ANI and RDNIS
Field values
0 = Unknown
1 = Presentation restricted
2 = Number not available because of interworking
Screening Indicator
2 bits for ANI and RDNIS
Field values
0 = User-provided, not screened
1 = User-provided, verified and passed
2 = User-provided, verified and failed
3 = Network provided
Reason for Redirection
4 bits for RDNIS
Precedence Rules for Setting Parameters
The tables shown below specify the precedence used in setting up parameters for the second call leg. The corresponding parameters may or may not be present in the <transfer> element or property. In each table, the precedence is arranged from the highest to the lowest as the condition in each row is checked for the parameters to be set for the second call leg.
In the tables below:
•
•
RADIUS Username
If the RADIUS username is present, use its value cisco-username. If it is not present, use cisco-ani.
Calling Number
cisco-ani with subfields
•
•
cisco-ani without subfields
cisco-ani
subfield = incoming legsubfields without cisco-ani
An error event, error.semantic is thrown.
None
Calling number = incoming leg
subfield = incoming leg
1 cisco-anipi and cisco-anisi must be provided as a pair. Providing only one of these attributes may result in the loss of an attribute on the terminating gateway. No error events are thrown.
Called Number
dest with subfields
dest with subfields
dest without subfields
dest subfields = incoming leg
None
Call is not transferred.
Redirecting Number
cisco-rdn with subfields
•
•
•
cisco-rdn without subfields
cisco-rdn
subfield = incoming legsubfields without cisco-rdn
An error event error.semantic is thrown.
None—With RDNIS information in the first call leg.
Redirecting number = incoming leg
subfield = incoming legNone—Without RDNIS information in the first call leg.
•
•
•
•
1 cisco-rdntype and cisco-rdnplan must be provided as a pair. Providing only one of these attributes may result in the loss of an attribute on the terminating gateway. No error events are thrown.
2 cisco-rdnpi and cisco-rdnsi must be provided as a pair. They must be provided only when cisco-rdntype and cisco-rdnplan are present. Failure to follow this guideline may result in a loss of attributes on the terminating gateway. No error events are thrown.
Control Flow and Scripting
This section describes mechanisms such as variables and events. that are used to control dialog flow.
Variables
VoiceXML 2.0 defines a set of standard JavaScript variables under the following groups:
•
•
•
•
Supported Session Variables
Cisco VoiceXML supports the standard session variables in the VoiceXML Version 2.0 W3C Recommendation (March 16, 2004) and the extended session variables listed in Table 1-5.
For more information on signaling protocols applicable to the use of session variables, see the following documents:
•
•
•
•
The session variables have the following values:
The session.telephone.ani_pi values are:
•
•
•
•
The session.telephone.ani_si values are:
•
•
•
•
The session.telephone.ani_plan values are:
•
•
•
•
•
•
•
The session.telephone.ani_type values are:
•
•
•
•
•
•
•
The session.telephone.rdnis_pi values are:
•
•
•
•
The session.telephone.rdnis_si values are:
•
•
•
The session.telephone.rdnis_type values are:
•
•
•
•
•
•
•
The session.telephone.rdnis_plan values are:
•
•
•
•
•
•
•
The session.telephone.dnis_type values are:
•
•
•
•
•
•
•
The session.telephone.dnis_plan values are:
•
•
•
•
•
•
•
The session.telephone.redirect_reason values are a string set by the signaling protocol (redirect_reason).
The session.telephone.handoff_string values are a string set by the application (handoff_string).
The session.telephone.redirect_count values are a number. Values retrieved between 0 and 7.
The session.telephone.nas_port_id values are for the following interface types:
•
•
•
•
For example, a value for an ISDN interface is ISDN 7/1:D.
The session.telephone.iidigits values are:
•
•
•
•
•
•
•
Application Variables
Cisco VoiceXML supports the standard application variable application.lastresult$. For more information on this variable, see the VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005). In addition to the standard variable, Cisco IOS Release 12.2(11)T introduces specific Cisco application variables, listed in Table 1-6.
A specific Cisco application variable, application.lastprompt$ holds information about the last prompt that was played through the read-only variables listed in Table 1-6.
Dialog Variables
In VoiceXML 2.0, all dialog variables are represented as shadow variables.
Cisco VoiceXML supports all standard shadow variables including:
•
•
•
•
•
•
•
Event Variables
Cisco VoiceXML does not support standard event variables.
Event Handling
This section discusses:
•
•
Fax Event Handler
The VoiceXML document has to define a catch event handler to process the fax detection event. This definition should normally be done in the application root document so it can remain active as other VoiceXML documents are loaded and executed during the current session.
The VoiceXML specification does not allow transfer elements in VoiceXML catch blocks. To get around this, use a goto tag with an associated form id block, where the transfer element resides as shown in the following example:
<catch event="com.cisco.fax.cng"><!-Can't have a transfer tag inside a catch handler.....--><goto next="#transferToFax"/></catch>........<form id="transferToFax"><transfer dest=" fax://4085550134" bridge=false cisco-mailtoaddress = "'email-id'"></form>Events and Errors
Cisco VoiceXML supports the events and errors listed in Table 1-7.
Cisco VoiceXML provides a set of default event handlers if no appropriate event handler is specified in the VoiceXML document or in the root document; these are summarized in Table 1-8.
Note
Note
JavaScript Support
Cisco VoiceXML supports ECMAScript Specification 3.0 (Standard ECMA-262, ECMAScript Language Specification, 3rd edition, August 1998, available at http://www.ecma.ch/), approximately equivalent to JavaScript 1.5 with the following exceptions:
•
•
Use of these unsupported features causes the VoiceXML interpreter to throw an error.semantic event.
Cisco VoiceXML supports floating point operations with a limited number range:
•
•
The size limit for JavaScript scripts is 65K in Cisco IOS Release 12.4(12), Cisco IOS Release 12.4(12)T, and later releases. Javascript scripts consume memory and CPU resources. To avoid performance problems, make sure JavaScript scripts contain only the minimum required code.
Environment and Resources
This section consists of:
•
Resource Fetching and Caching
The Cisco implementation of VoiceXML 2.1 supports resource fetching and caching. For more information, see the VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005).
Fetching
The resources fetched by the VoiceXML interpreter context are:
•
•
•
•
Cisco VoiceXML supports the following attributes that govern fetching of content associated with a URI:
•
•
•
Note
The protocols supported for fetching are:
•
•
•
Caching
Cisco VoiceXML does not have its own caching mechanism. It relies on the HTTP protocol to provide caching.
Note
Cisco VoiceXML does not allow the user to control caching.
Property
Cisco <property> extensions are listed in Table 1-9:
Table 1-9 Cisco < property> Extensions
com.cisco.tts-server
Allows the document to specify an external media server for text-to-speech operations. The media server is specified in the form of an URI, and is used in all consecutive ASR operations until the next media server is specified. An external media server specified by a property in the script takes precedence over being specified by a command through the CLI.
It can be defined for:
•
•
•
The media server's URI can be formatted for Media Resource Control Protocol version 1 (MRCP v1) which uses Real Time Streaming Protocol (RTSP) or MRCP v2, which uses Session Initiation Protocol (SIP), for example:
<property name="com.cisco.tts-server" value="rtsp://tts-server1/synthesizer" />
<property name="com.cisco.tts -server" value="sip:mresources@mediaserver.com" />
There are two ways to specify an external media server for TTS and ASR operations:
•
•
For information on identifying TTS or ASR servers through the ivr tts-server and ivr asr-server commands, see the Cisco IOS Tcl IVR and VoiceXML Application Guide.
com.cisco.asr-server
Allows a document to specify an external media server for automatic speech recognition operations. The media server is specified in the form of an URI, and is used in all consecutive ASR operations until the next media server is specified. An external media server specified by a property in the script takes precedence over being specified by a command through the CLI.
The media server's URI can be formatted for Media Resource Control Protocol version 1 (MRCP v1) which uses RTSP or MRCP v2, which uses SIP, for example:
<property name="com.cisco.asr-server" value="rtsp://asr-server1/synthesizer" />
<property name="com.cisco.asr -server" value="sip:mresources@mediaserver.com" />
com.cisco.asr-builtin-grammar
Allows the document to specify a base URI for the external media server for ASR operations.
com.cisco.media-logging-id
•
•
•
com.cisco.autoflush
Prevents default flushing of the typeahead buffer by setting the property to FALSE.
com.cisco.record_finalsilence
Specifies the interval of silence that indicates the end of speech.
com.cisco.record_maxtime
Specifies the maximum duration of the recording.
com.cisco.record_type
Specifies the MIME format of the resulting recording.
com.cisco.mta.send.mdn_hostname
Specifies the hostname of the receiving e-mail address for message delivery notification (MDN).
com.cisco.mta.send.mdn_username
Specifies the username of the receiving e-mail address for message delivery notification.
com.cisco.mta.send.dsn_delay
Specifies a delay in the message delivery.
com.cisco.mta.send.dsn_failure
Specifies a failure in the message delivery.
com.cisco.mta.send.dsn_success
Specifies successful delivery of the message.
com.cisco.mta.send.from_hostname
Specifies the hostname from the originating address of the e-mail.
com.cisco.mta.send.from_username
Specifies the username from the originating address of the e-mail.
com.cisco.mta.send.origin_prefix
Specifies prefix header from the originating e-mail.
com.cisco.mta.send.server
Specifies the destination server.
com.cisco.mta.send.subject
Defines the text that appears in the "subject" field of the e-mail.
bargeintype
Specifies the type of bargein: speech or hotword.
markname
The name of the mark last executed by the SSML processor before bargein or the end of audio playback occurred.
marktime
The number of milliseconds that elapsed since the last mark was executed by the SSML processor until bargein or the end of audio playback occurred.
recordutterance
To enable recording during recognition, set the value of the recordutterance property to true. Recording during recognition is not supported for the <transfer> and <record> elements.
Note
In Cisco IOS Release 12.4(11)T and later releases, an error event error.semantic is thrown if a property value is found to be illegal.
Default Values and Ranges
This section describes values for the VoiceXML timeouts: fetchtimeout, timeout, interdigittimeout, connecttimeout, and maxtime. For all of these, a negative value is invalid and 0 means default.
The maximum supported value for each timeout described in this section is 2147483 seconds.
The duration string after fetchtimeout could be arbitrary. When a timeout is converted into a real value, it could assume only a valid positive integer value, ranging from 0 to 2147483647 milliseconds, that is, 596523 hours or about 68 years.The VoiceXML timeouts are listed in Table 1-10. For more information, see VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005). For information on configuring default values through the CLI, see the Cisco IOS Tcl and VoiceXML Application Guide for your Cisco IOS release.
Call Handoff
To understand call handoff, it is important to understand the concept of an application instance. In the Cisco IOS interactive voice response (IVR) infrastructure, an application instance is an entity that executes the application code, and receives, creates, and manages one or more call legs together to setup a call or to deliver a service to a user. The application instance owns and controls these call legs, and receives and manages all events associated with these call legs. Most applications will use a single application instance to deliver the services of a single call. A stand alone VoiceXML session acts as an application instance.
The term call handoff is used to describe the act of transferring complete control of a call leg from one application instance to another. When a call leg is handed off, all future events associated with that call leg are received and handled by the target application instance. There are different types of call handoff, and they occur depending on whether the call leg needs to return to the application instance that is the source of the handoff operation. A normal call handoff is similar to a goto statement with no automatic memory of a return address where the target application instance cannot return the call leg back to the source. During the handoff of a call leg, any legs conferenced to that call leg are also handed off. During a handoff or a handoff return operation, an application instance can pass parameters as argument strings.
The call handoff functionality allows a developer to write applications that may interact with each other for various reasons; for example, to use or leverage functionality in existing applications, or to modularize a larger application into smaller application segments and use the handoff mechanism to coordinate and communicate between them. During call handoff, only one application instance controls the call leg and receives events. Hybrid scripting is a recommended alternative for developers implementing applications that use VoiceXML and Tcl IVR 2.0. For more information on hybrid scripting, see the "Hybrid Applications" section.
The call handoff functionality in Cisco VoiceXML is similar to the call handoff initiated by the handoff appl and handoff callappl verbs in Tcl IVR 2.0. For more information on the Tcl IVR 2.0 verbs, see the Tcl IVR Version 2.0 Programmer's Guide.
Call Handoff in Cisco VoiceXML
Call handoff in Cisco VoiceXML is invoked through the <object> element as follows:
<objectname= "ResultVariableName"classid= "builtin://com.cisco.callhandoff"<param name= "return" expr="<Boolean value>"/><param name= "app-uri" expr="<URI>"/><param name= "arg-string" expr="a string"/></object>Call handoff can take place between any combination of VoiceXML and Tcl IVR applications, and is of two types:
•
<param name= "return" expr="<false>"/>Before the handoff takes place, both applications must be configured on the gateway. After the handoff is successful, a handoff event telephone.disconnect.com.cisco.callhandoff is thrown at the invoking session, and the VoiceXML document continues executing without a call leg, similar to a <transfer> with bridging set to false.
•
<param name= "return" expr="<true>"/>If the return flag is true, the VoiceXML interpreter execution is blocked until the handoff is complete. The interpreter waits for the called application to return with the call leg. During this handoff, no grammars can be active on the leg because the VoiceXML application instance has no control on the call leg. If the destination application does not return the leg but disconnects it, the VoiceXML interpreter is released from being blocked, throws a telephone.disconnect.com.cisco.handoff event to the VoiceXML application, and continues executing without a call leg, similar to a <transfer> with bridging set to false. If the target application returns the call leg, the field variable is filled with the handoff completion status and the form continues to be processed. If the target application returns the call leg with additional parameters, they can be accessed through the field variable of the <object> element and the field variable is filled with a complex object.
•
•
Table 1-11 lists the attributes and parameters for the call handoff script shown above.
Events and Errors in Call Handoff
•
–
–
•
This error event is thrown in both types of call handoff if there is an error in handing off the call leg to the destination application. For example, an error occurs if the destination application is not configured or built into the voice gateway.
•
This error event is thrown if the specific platform variable com.cisco.callhandoff is not supported.
Example
The call handoff example shown here has a return value of true.
<var name="appName" expr="'builtin://coapp'"/>!coapp is the name of the application configured on the gateway using the call application voice command.<object name="myhandoff" classid="builtin://com.cisco.callhandoff"><param name="return" expr="true"/>!For a return value of false, expr="false".<param name="app-uri" expr="appName"/><param name="arg-string" expr="'arg 1'" /></object>Authentication and Authorization
Cisco VoiceXML implements the aaa authorize and aaa authenticate commands through the <object> element. The implementation is very similar to the use of aaa authorize and aaa authenticate in Tcl IVR 2.0, where authentication and authorization requests are sent to a RADIUS (or TACACS) server.
Some of the main differences between authentication and authorization are:
•
•
•
•
RADIUS is a distributed client-server system protocol that secures networks against unauthorized access. In Cisco's implementation of RADIUS, clients run on Cisco routers, access servers, and gateways, and send authentication requests to a central RADIUS server that contains user authentication and network service access information.
For information on how to configure Cisco IOS security features on your network device, see the Cisco IOS Security Configuration Guide, Release 12.4T, and the Cisco IOS Security Command Reference Guide, Release 12.4T.
Authentication
In Cisco VoiceXML:
•
classid="builtin://com.cisco.aaa.authenticate"•
•
name="ResultVariableName"It contains the authentication result (represented as pass or fail) and any vendor specific attributes that are sent by the billing server as part of the authentication response.
•
•
Table 1-12 summarizes the attributes and parameters of the authentication object.
The authentication object is accessed as follows:
<objectname="ResultVariableName"classid="builtin://com.cisco.aaa.authenticate"<param name="account" expr="user_account_num"/><param name="password" expr="user_passwd"/><param name="server-tag" expr="server_tag"/><param name="key1" expr="value1" valuetype="com.cisco.datatype.list"/><param name="key2" expr="value2" valuetype="com.cisco.datatype.list"/>..<param name="keyN" expr="valueN" valuetype="com.cisco.datatype.list"/></object>
Events and Errors in Authentication
•
This error event is thrown if the voice gateway does not connect with the RADIUS server and authentication fails. This error event is also thrown if there is a server error after the voice gateway connects with the RADIUS server.
•
This error event is thrown if the specific platform function com.cisco.authentication is not supported.
Authorization
In Cisco VoiceXML:
•
classid="builtin://com.cisco.aaa.authorize"•
•
•
name= "ResultVariableName"It contains the authorization result (represented as pass or fail) and any vendor specific attributes that are sent by the billing server as part of the authorization response.
•
•
The authorization object is accessed as follows:
<object>name="ResultVariableName"classid="builtin://com.cisco.aaa.authorize"<param name="account" expr="user_account_num"/><param name="password" expr="user_passwd"/><param name="ani" expr="calling_num"/><param name="dnis" expr="called_num"/><param name="server-tag" expr="server_tag"/><param name="key1" expr="value1" valuetype="com.cisco.datatype.list"/><param name="key2" expr="value2" valuetype="com.cisco.datatype.list/>..<param name="keyN" expr="valueN" valuetype= "com.cisco.datatype.list"/></object>Table 1-13 summarizes the attributes and parameters of the authorization object.
Events and Errors in Authorization
•
This error event is thrown if the voice gateway does not connect with the RADIUS server and authorization fails. This error event is also thrown if there is a server error after the voice gateway connects with the RADIUS server.
•
This error event is thrown if the specific platform function com.cisco.aaa.authorization is not supported.
SIP and H.323 Support
Cisco IOS Release 12.3(T) allows VoiceXML applications to pass and receive URI and SIP header information in call setup messages, specify headers that are sent in SIP INVITE or H.323 setup messages, and initiate blind call transfers.
SIP and TEL URL Support
This feature allows VoiceXML applications to place a call to a destination address containing a URI, and to pass and receive URI and SIP header information in a call setup message for inbound and outbound calls. For Cisco IOS configuration tasks related to this feature, see the following documents:
•
•
Limitations
Limitations of SIP and TEL URL Support in Cisco VoiceXML are:
•
•
•
•
–
–
–
–
–
–
–
Excluding this list of headers, a VoiceXML application is allowed to pass any header, including extended and nonstandard headers.
•
–
–
Reserved Characters
For example, sip:joe@big.com?Subject=Hello&Priority=Urgent must be rewritten as:
sip:joe@big.com?Subject=Hello&Priority=Urgent.
If the URL in a header contains a reserved character from this list, the header must be rewritten with the equivalent escape sequence.
Passing Headers in Voice Messages
In Cisco IOS Release 12.3 T, Cisco VoiceXML allows a VoiceXML document to specify headers that are sent in the SIP INVITE or H.323 setup message. Voice applications can use headers in SIP invite messages to pass information about a call to an application on another server. For example, an account number can be passed in a SIP header if the caller entered an account number and the application transfers the call to another application on another platform. A typical scenario is an airline application where a call comes into an airline application, and then needs to be transferred to a hotel reservation application. If the voice browser cannot load VoiceXML documents directly from the HTTP servers of the airline and the hotel, the voice application can use headers in SIP messages to transfer call information. That call can then be transferred to a hotel reservation application that is being hosted by a different service provider.
The script writer enters the header in the destination URI after the ? as part of the SIP URL, or after the ; as part of the TEL:URL. Headers embedded in SIP URLs are separated by &. Headers embedded in TEL URLs are separated by a semicolon (;).
Note
Example
In this SIP:URL, "sip:joe@big.com?Subject=Car Rental&Priority=urgent&Account=1234567890" the header Subject=Car Rental&Priority=urgent&Account=1234567890 is embedded into the SIP URL after the question mark ? .
In this TEL: URL, "tel:5550123;Subject=Car Rental;Priority=urgent;Account=1234567890" the header Subject=Car Rental;Priority=urgent;Account=1234567890 is embedded in the TEL URL after the semicolon ; .
Headers in Outbound Calls
Cisco VoiceXML allows access to headers in only the following messages:
•
•
•
•
Passing Headers from <transfer> to SIP INVITE
A VoiceXML document appends the header value-pairs as part of the destexpr (or dest) attribute of the <transfer> element.
In the example shown here, the subject, priority, and X-ReferenceNumber headers are embedded in the destexpr URI and are sent out in the SIP INVITE message.
<transfer name="mycall"destexpr="'sip:joe@big.com?Subject=Hotel Reservation&Priority=urgent& X-ReferenceNumber=1234567890'"...</transfer>The SIP INVITE message that is transferred out is shown below. The headers that are passed from the VoiceXML application are Subject: Hotel Reservation, Priority: urgent, and X-ReferenceNumber: 1234567890.
INVITE sip:joe@1.100.7.32 SIP/2.0Via: SIP/2.0/UDP 192.168.6.121:5060From: 4085550134@192.168.6.121To: joe@big.comCall-ID: c2943000-e0563-2a1ce-2e323931@192.168.6.21Subject: Hotel ReservationPriority: urgentX-ReferenceNumber: 1234567890
Note
VoiceXML Handoff String
In Cisco IOS Release 12.3T, a <transfer> attribute cisco-handoffexpr is used to hand off a string to an outbound application.
Example
The example shown here demonstrates the use of the cisco-handoffexpr in the handoff string of the <transfer> element.
<transfer name="mycall"destexpr="'sip:joe@big.com?Subject=Car Rental&Priority=urgent&Account='+callerID"bridge="true" connecttimeout="15s" maxtime="180s" cisco-longpound ="true"cisco-handoffexpr="'my handoff string goes here'"...</transfer>In Cisco IOS release 12.2(11)T, if the <transfer> element is used to transfer calls between VoiceXML applications, the script writer can embed ? and a string after the destination number as shown below.
<transfer name = "mycall"dest ="tel: 5550124?reference-prompt=http://1.10.21.7/audio/hello.au">The string was forwarded to the receiving VoiceXML application which received reference-prompt=http://1.10.21.7/audio/hello.au in session.handoff_string.
Cisco IOS Release 12.3T allows this method of handing off a string to an outbound application; however, the use of the cisco-handoffexpr attribute is recommended to hand off the string.
<transfer> DTD
<!ELEMENT transfer (%audio; | %event.handler; | filled | %input;| prompt | property)* ><!ATTLIST transfer%item.attrs;...cisco-handoffexpr %expression; #IMPLIED>PSTN Outbound Calls
•
•
•
Headers in Inbound Calls
For incoming calls, Cisco VoiceXML allows a VoiceXML application to receive headers in session variables.
VoiceXML Document Receiving Headers
In Cisco VoiceXML, headers are received in a VoiceXML document by using session variables of the following syntax:
session.com.cisco.proto_headers[`<attribute name>']
where, session.com.cisco.proto_headers is a JavaScript object.
<attribute name> is one of the following:
•
•
•
Examples
1.
Returns the request-URI in the incoming INVITE message.
2.
Returns the "To" header value in the incoming INVITE message.
3.
Returns all headers concatenated into a single string with an `&' to separate each header avpair. For example "To=Joe@big.com&Subject=Hotel Reservation&...".
If the DNIS or ANI includes a SIP URI, information is returned in the following session variables:
•
Returns the requested URI received in the INVITE message which may or may not be an E.164 number.
•
Returns the "From" header field received in the INVITE message which may or may not be an E.164 number.
The example below demonstrates the use of Cisco session variables in the <submit> element.
<submit next="http://Hotel-X/Reservation/servlets/getInfo" method="post"namelist="session.com.cisco.proto_headers['To']session.com.cisco.proto_headers['From']session.com.cisco.proto_headers['Subject']session.com.cisco.proto_headers['X-ReferenceNumber']/>The namelist format submitted to the server appears as shown below:
session.com.cisco.proto_headers['To']=Joe@big.com& \session.com.cisco.proto_headers['From']=4085550134@192.168.6.121& \session.com.cisco.proto_headers['Subject']=HotelReservation& \sesion.com.cisco.proto_headers['X-ReferenceNumber']=1234567890If the specified variable name is a header received in a SIP message, its value is received and submitted to the web server http://Hotel-X/Reservation/servlets/getInfo. If the requested header name does not exist, the session variable contains an empty string. For example, if the header To does not exist, the string is To= with nothing after the = sign.
Retrieving DNIS, ANI, and Headers in Outbound Applications
If a call is handed off to an outbound application, that application retrieves all headers handed off to it from the previous application, and it also retrieves headers from the incoming call leg. The session variable session.telephone.com.cisco.handoff.proto_headers[`<attribute name>'] is used to retrieve the handoff headers. The session variable session.telephone.com.cisco.handoff.dnis returns the DNIS and the ANI set by the inbound application in the <transfer> element. They are returned to the specific outbound application that received the handoff call from the inbound application. The session variable session.telephone.dnis always returns the DNIS and the ANI from the original incoming call leg.
Example: Passing a SIP URL with Headers Using SIP
This example demonstrates two features of Cisco VoiceXML:
•
•
See the Cisco IOS Tcl and VoiceXML Application Guide for the originating gateway (OGW) call flow and Cisco IOS configuration.
Originating Gateway
In this example, a Tcl script is used on the OGW. The Tcl script prompts the caller for an account number. It calls the URL sip:elmo@sip.tgw.com and after receiving the account number, passes it in the SIP header named accountinfo. Other static headers such as Subject, To, From, and Priority are also passed by the Tcl script either independently or as part of the URL.
Terminating Gateway
In this example, a Tcl or VoiceXML script is used on the terminating gateway (TGW). See the Cisco IOS Tcl and VoiceXML Application Guide for the originating gateway (OGW) call flow and Cisco IOS configuration.
The Tcl script plays the account number and the prompt "The number is" both of which are received from the OGW. Other headers received are displayed in debug messages such as debug voip ivr script.
In this example, the VoiceXML script get_headers.vxml on the terminating gateway plays the account number and the prompt "The number is," both of which are received from the OGW. Other headers received are displayed in debug messages such as debug voip application vxml puts.
get_headers.vxml
<?xml version="1.0"?><vxml version="2.0"><form><block><log> get_headers: ani is<value expr="session.telephone.ani"/></log><log> get_headers: dnis is<value expr="session.telephone.dnis"/></log><log> get_headers: header Subject is<value expr="session.com.cisco.proto_headers['Subject']"/></log><log> get_headers: header Priority is<value expr="session.com.cisco.proto_headers['Priority']"/></log><log> get_headers: header From is<value expr="session.com.cisco.proto_headers['From']"/></log><log> get_headers: header To is<value expr="session.com.cisco.proto_headers['To']"/></log><log> get_headers: header Via is<value expr="session.com.cisco.proto_headers['Via']"/></log><log> get_headers: tsp is<value expr="session.com.cisco.proto_headers['tsp']"/></log><log> get_headers: phone-context is<value expr="session.com.cisco.proto_headers['phone-context']"/></log><log> get_headers: Non-Exist is<value expr="session.com.cisco.proto_headers['Non-Exist']"/></log><log> get_headers: request-URI is<value expr="session.com.cisco.proto_headers['request-URI']"/></log><log> get_headers: All headers are<value expr="session.com.cisco.proto_headers['']"/></log><log> get_headers: header AccountInfo is<value expr="session.com.cisco.proto_headers['AccountInfo']"/></log><prompt><audio src="tftp://townsend.cisco.com/audio/num_is.au"/><value expr="session.com.cisco.proto_headers['AccountInfo']" class="digits" mode="recorded"recsrc="tftp://servername/location/audio/en/"/></prompt></block></form></vxml>Example: Passing a TEL URL with Headers Using H.323
This example demonstrates two features of Cisco VoiceXML:
•
•
Originating Gateway
See the Cisco IOS Tcl and VoiceXML Application Guide for the originating gateway (OGW) call flow and Cisco IOS configuration.
In this example, a VoiceXML script tel_headers.vxml on the OGW prompts the caller for an account number, and after receiving it, calls the TEL URL "tel:7671234;phone-context=408;tsp=lalaland.com;Subject=HelloTelVXML;\
To=oscar@abc.com;From=nobody;Priority=urgent'+';AccountInfo='+acctInfo".
The header accountinfo is passed to the leg setup along with other standard and user-defined headers in the destination URL.
tel_headers.vxml
<vxml version="2.0"><form><var name="mydur" expr="0"/><field name="acctInfo" type="digits"><prompt bargein="true"><audio src="http://townsend.cisco.com/vxml/audio/enterAccount.au"/></prompt></field><transfer name="mycall"destexpr="'tel:7671234;phone-context=408;tsp=lalaland.com;Subject=HelloTelVXML;\To=oscar@abc.com;From=nobody;Priority=urgent'+';AccountInfo='+acctInfo"connecttimeout="30s" bridge="true"/><filled><assign name="mydur" expr="mycall$.duration"/><log> ORIG OUTBOUND APP </log><log> The duration of the call is<value expr="mydur"/></log></filled></form></vxml>Terminating Gateway
See the Cisco IOS Tcl and VoiceXML Application Guide for your Cisco IOS release for the terminating gateway (TGW) call flow and Cisco IOS configuration.
In this example:
•
•
•
See the Cisco IOS Debug Command Reference, Release 12.4T for more information on debug commands.
SIP Blind Call Transfer
Cisco IOS releases after 12.2(11)T allow VoiceXML applications to initiate a blind call transfer using the Refer method in SIP.
For information on SIP blind call transfers, see SIP Call Transfer and Call Forwarding Suplementary Services.
GTD Manipulation, Cisco IOS Release 12.2(11)T
Note
GTD Parameters and Fields Mapped to VoiceXML Variables
The ISUP signaling message set used in SS7 networks contains information that is used for call establishment, routing and billing functions. To help transport these messages from SS7 networks (using ISUP based messages) to VoIP networks (using H.323 and SIP based messages), ISUP messages and parameters are represented in generic transparency descriptor (GTD) format and transported by the underlying call signaling messages to each node transited by the call.
Table 1-14 describes the GTD parameters and Table 1-15 maps the GTD parameters and fields to VoiceXML variables.
The section below describes the Cisco VoiceXML variables that are mapped to the GTD parameters in Table 1-15.
Note
The Cisco VoiceXML variables providing GTD parameters are:
com.cisco.rgn_noa
com.cisco.rgn_npi
com.cisco.rgn_pi
Syntax
com.cisco.rgn_pi
GTD parameter
Redirecting number (RGN)
Field
pi—Presentation indicator
Field values
0—Unknown
1—Presentation allowed
2—Presentation not allowed
3—Address not available
com.cisco.rgn_num
Syntax
com.cisco.rgn_num
GTD parameter
Redirecting number (RGN)
Field
# —Address. # is represented by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
com.cisco.rni_ri
Syntax
com.cisco.rni_ri 1
GTD parameter
Redirection information (RNI)
Field
ri— Redirecting indicator
Field values
0—No redirection or unknown
1—Call rerouted
2—Call rerouted, all redirection info presentation restricted
3—Call diverted
4—Call diverted, all redirection information presentation restricted
5—Call rerouted, redirection number presentation restricted
6—Call diversion, redirection number presentation restricted
1 This session variable may be replaced in a future Cisco IOS release by an alternate method of accessing signaling information.
com.cisco.rni_orr
Syntax
com.cisco.rni_orr1
GTD parameter
Redirection information (RNI)
Field
orr— Original redirection reason
Field values
1—User busy
2—No reply
3—Unconditional
4—Deflection during alerting
5—Deflection immediate response
6—Mobile subscriber not reachable
252—Unknown
com.cisco.rni_rc
Syntax
com.cisco.rni_rc 1
GTD parameter
Redirection information (RNI)
Field
rc— Redirection counter
Field values
Valid values are in the range of 1-15.
com.cisco.rni_rr
Syntax
com.cisco.rni_rr1
GTD parameter
Redirection information (RNI)
Field
rr— Redirection reason
Field values
V1—User busy
2—No reply
3—Unconditional
4—Deflection during alerting
5—Deflection immediate response
6—Mobile subscriber not reachable
252—Unknown
com.cisco.ocn_noa
Syntax
com.cisco.ocn_noa1
GTD parameter
Original called number (OCN)
Field
noa— Nature of address
Field values
0—Unknown, number present
1—Unknown, number absent, presentation restricted
2—Unique subscriber number
3—Nonunique subscriber number
4—Unique national (significant) number
5—Nonunique national number
6—Unique international number
7—Nonunique international number
8—Network specific number
9—Nonsubscriber number
10—Subscriber number, operator requested
11—National number, operator requested
12—International number, operator requested
13—No number present, operator requested
14—No number present, cut through call to carrier
15—950+ call from local exchange carrier public station, hotel/motel or nonexchange access end office
16—Test line test code
17—Unique 3 digit national number
18—Credit card
19—International inbound
20—National or international with carrier access code included
21—Cellular - global ID GSM
22 - Cellular - global ID NWT 900
23 - Cellular - global ID autonet
24 - Mobile (other)
25 - Ported number
26 - VNET
27 - International operator to operator outside WZ1
28 - International operator to operator inside WZ1
29 - Operator requested - treated
30 - Network routing number in national (significant) format
31 - Network routing number in network specific format
32 - Network routing number concatenated with called directory number
33 - Screened for number portability
34 - Abbreviated number
com.cisco.ocn_npi
Syntax
com.cisco.ocn_pi1
GTD parameter
Original called number (OCN)
Field
npi— Numbering plan indicator
Field values
1—ISDN numbering plan
2—Data numbering plan
3—Telex numbering plan
4—private numbering plan
5—national
6—maritime mobile
7—land mobile
8—ISDN mobile
252—unknown
com.cisco.ocn_pi
Syntax
com.cisco.ocn_pi1
GTD parameter
Original called number (OCN)
Field
pi— Presentation indicator
Field values
0—unknown
1—presentation allowed
2—presentation not allowed
3—address not available
com.cisco.ocn_num
Syntax
com.cisco.ocn_num1
GTD parameter
Original called number (OCN)
Field
#— Address. # is representated by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
com.cisco.chn_noa
Syntax
com.cisco.chn_noa1
GTD parameter
Charge number (CHN)
Field
noa— Nature of address
Field values
0—unknown
1—calling subscriber - not available
2—calling subscribers number
3—calling subscriber - national number
4—calling subscriber - international number
5—calling subscriber VPN
6—called subscriber no number present
7—called subscriber number
8—called subscriber national number
9—called subscriber international number
10—called subscriber VPN
11—VNET
com.cisco.chn_npi
Syntax
com.cisco.chn_npi1
GTD parameter
Charge number (CHN)
Field
npi— Numbering plan indicator
Field values
1—ISDN numbering plan
2—data numbering plan
3—telex numbering plan
4—private numbering plan
5—national
6—maritime mobile
7—land mobile
8—ISDN mobile
252—unknown
com.cisco.chn_num
Syntax
com.cisco.chn_num1
GTD parameter
Charge number (CHN)
Field
#— Address. # is represented by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
com.cisco.gea_type
Syntax
com.cisco.gea_type 1
GTD parameter
Generic address (GEA)
Field
type— Type of address
Field values
0—dialed number
1—destination number/additional called number
2—supplemental user provided calling address; failed network screening
3—supplemental user provided calling address; not screened
4—completion number
5—ported number
6—transfer number 1
7—transfer number 2
8—transfer number 3
9—transfer number 4
10—transfer number 5
11—transfer number 6
12—caller emergency service ID
13—reserved
14—called number emergency service ID
com.cisco.gea_noa
Syntax
com.cisco.gea_noa1
GTD parameter
Generic address (GEA)
Field
noa— Numbering plan indicator
Field values
0—unknown, number present
1—unknown, number absent, presentation restricted
2—unique subscriber number
3—nonunique subscriber number
4—unique national (significant) number
5—nonunique national number
6—unique international number
7—nonunique international number
8—network specific number
9—nonsubscriber number
10—subscriber number, operator requested
11—national number, operator requested
12—international number, operator requested
13—no number present, operator requested
14—no number present, cut through call to carrier
15—950+ call from local exchange carrier public station, hotel/motel or nonexchange access end office
16—test line test code
17—unique 3 digit national number
18—credit card
19—international inbound
20—national or international with carrier access code included
21—cellular - global ID GSM
22—cellular - global ID NWT 900
23—cellular - global ID autonet
24—mobile (other)
25—ported number
26—VNET
27—international operator to operator outside WZ1
28—international operator to operator inside WZ1
29—operator requested - treated
30—network routing number in national (significant) format
31—network routing number in network specific format
32—network routing number concatenated with called directory number
33—screened for number portability
34—abbreviated number
com.cisco.gea_npi
Syntax
com.cisco.gea_npi1
GTD parameter
Generic address (GEA)
Field
npi— Numbering plan indicator
Field values
1—ISDN numbering plan
2—data numbering plan
3—telex numbering plan
4—private numbering plan
5—national
6—maritime mobile
7—land mobile
8—ISDN mobile
252—unknown
com.cisco.gea_cni
Syntax
com.cisco.gea_cni1
GTD parameter
Generic address (GEA)
Field
cni— Complete number indicator
Field values
0—unknown
1—number complete
2—number incomplete
com.cisco.gea_pi
Syntax
com.cisco.gea_pi 1
GTD parameter
Generic address (GEA)
Field
pi— Address presentation indicator
Field values
0—unknown
1—presentation allowed
2—presentation restricted
3—address not available
com.cisco.gea_si
Syntax
com.cisco.gea_si 1
GTD parameter
Generic address (GEA)
Field
si— Screening indicator
Field values
1—user provided not screened (verified)
2—user provided screening passed
3—user provided screening failed
4—network provided
252—unknown or not applicable
com.cisco.gea_num
Syntax
com.cisco.gea_num1
GTD parameter
Generic address (GEA)
Field
#—Address. # is represented by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
com.cisco.cpc
Syntax
com.cisco.cpc1
GTD parameter
Calling party category (CPC)
Field
cpc— Calling party category
Field values
0—unknown
1—operator, language French
2—operator, language English
3—operator, language German
4—operator, language Russian
5—operator, language Spanish
6—admin1
7—admin2
8—admin3
9—ordinary calling subscriber
10—ordinary calling subscriber with customer meter
11—calling subscriber with priority
12—data call
13—test call
14—customer pay phone
15—public pay phone
16—emergency service call
17—high priority emergency service call
18—national security and emergency preparedness (NS/EP call)
19—trunk offering
20—mobile customer
21—PBX subscriber
22—operator with forward facility
23—intercept operator
24—cross-border operator
25—long distance pay phone
26—international pay phone
27—international test equipment
28—check calling party number
29—national operator
com.cisco.oli
Syntax
com.cisco.oli1
GTD parameter
Originating line information (OLI)
Field
oli— Originating line information
Field values
0—pots
1—multiparty line
2—ANI failure
6—station level rating
7—special operator handling required
8—inter-LATA restricted
10—test call
20—AIOD-listed DN sent
23—coin or noncoin on calls using database access
24—800 service call
25—800 service call from a pay station
27—pay phone using coin control signaling
29—prison/inmate service
30—intercept (blank)
31—intercept (trouble)
32—intercept (regular)
34—telco operator handled call
36—CPE
52—OUTWATS
60—TRS call from unrestricted line
61—wireless/cellular PCS (type 1)
62—wireless/cellular PCS (type 2)
63—wireless/cellular PCS (roaming)
66—TRS call from hotel
67—TRS call from restricted line
68—inter-LATA restricted hotel
78—inter-LATA restricted coin-less
70—private pay-stations
93—private virtual network
com.cisco.cid_ton
Syntax
com.cisco.cid_ton1
GTD parameter
Carrier identification (CID)
Field
ton— Type of network
Field values
0—unknown
1—ITU/CCITT
2—national
com.cisco.cid_cid
Syntax
com.cisco.cid_cid1
GTD parameter
Carrier identification (CID)
Field
cid— Carrier identification
Field values
One or more characters from 0-9 and A-F to identify the carrier.
com.cisco.tns_ton
Syntax
com.cisco.tns_ton1
GTD parameter
Transit network selection (TNS)
Field
ton— Type of network
Field values
0—unknown
1—ITU/CCITT
2—national
com.cisco.tns_nip
Syntax
com.cisco.tns_nip1
GTD parameter
Transit network selection (TNS)
Field
nip— Network identification plan
Field values
1—public data network identification code
2—public land mobile network identification code
3—3-digit carrier identification with circuit code
4—4-digit carrier identification with circuit code
252—unknown
com.cisco.tns_cc
Syntax
com.cisco.tns_cc1
GTD parameter
Transit network selection (TNS)
Field
cc— Circuit code
Field values
1—international call, no operator requested
2—international call, operator requested
251—not applicable
252—unknown
com.cisco.tns_tns
Syntax
com.cisco.tns_ns1
GTD parameter
Transit network selection (TNS)
Field
tns— Network identification
Field values
IA5—Characters from 0-9 and A-F of length defined by the fields ton and nip.
com.cisco.pci_instr
Syntax
com.cisco.pci_instr1
GTD parameter
Parameter compatibility (PCI)
Field
instr— Instruction
Field values
0—release call regardless of the ability to forward the parameter
1—discard message regardless of the ability to forward the parameter, no notification required, but continue call
2—discard message regardless of the ability to forward the parameter, send notification (in confusion), but continue call
3—discard parameter regardless of the ability to forward the parameter, no notification required, but continue call
4—discard parameter regardless of the ability to forward the parameter, send notification (in Confusion) but continue call
5—attempt to forward the parameter, if unable to forward the parameter release the call
6—attempt to forward the parameter, if unable to forward the parameter discard message without notification but continue the call
7—attempt to forward the parameter, if unable to forward the parameter, discard message, send notification but continue the call.
8—attempt to forward the parameter, if unable to forward the parameter, discard the parameter, without notification but continue the call.
9—attempt to forward the parameter, if unable to forward the parameter discard the parameter, send notification but continue the call.
252—unknown
com.cisco.pci_tri
Syntax
com.cisco.pci_tri1
GTD parameter
Parameter compatibility (PCI)
Field
tri— Transit at intermediate exchange indicator
Field values
0—no transit
1—yes transit
com.cisco.pci_dat
Syntax
com.cisco.pci_dat1
GTD parameter
Parameter compatibility (PCI)
Field
dat— Representation of the parameter contents.
Field values
One or more characters from 0-9 and A-F representing the hexadecimal value of the parameter.
com.cisco.fdc_parm
Syntax
com.cisco.fdc_parm1
GTD parameter
Known field compatibility information (FDC)
Field
parm— Parameter name
Field values
A string of three ASCII characters.
com.cisco.fdc_fname
Syntax
com.cisco.fdc_field1
GTD parameter
Known field compatibility information (FDC)
Field
fname— Field name. Refers to the field name declared against the parameter.
Field values
A string of five ASCII characters with a lower case alphabetic field name.
com.cisco.fdc_instr
Syntax
com.cisco.fdc_instr1
GTD parameter
Known field compatibility information (FDC)
Field
instr— Instruction
Field values
1—release call if not understood, regardless of the ability to forward the call.
2—use the default value if not understood regardless of the ability to forward; no notification required, but continue the call.
3—use the default value if not understood regardless of the ability to forward; send notification (in Confusion), but continue the call.
4—attempt to forward value; if unable to forward the value, release the call.
5—attempt to forward value; if unable to forward the value, use default value without notification, but continue the call.
6—attempt to forward value; if unable to forward the value, use default value and send notification, but continue the call.
252—unknown
com.cisco.fdc_dat
Syntax
com.cisco.fdc_dat1
GTD parameter
Known field compatibility information (FDC)
Field
dat— Hexadecimal representation of the contents of the parameter .
Field values
One or more ASCII characters from 0-9 and A-F . The entire parameter uses ASCII characters to represent hexadecimal values.
GTD Parameter Reference
This section describes the GTD parameters used for implementing call control features in Cisco VoiceXML. For detailed information on GTD parameters, see MIME Media Types for Generic Transparency Descriptor (GTD) Objects.
GTD parameter
Redirecting number (RGN)
Field
pi—Presentation indicator
Field values
0—unknown
1—presentation allowed
2—presentation not allowed
3—address not available
GTD parameter
Redirecting number (RGN)
Field
# —Address. # is represented by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
GTD parameter
Redirection information (RNI)
Field
rc— Redirection counter
Field values
Valid values are in the range of 1-15.
GTD parameter
Original called number (OCN)
Field
pi— Presentation indicator
Field values
0—unknown
1—presentation allowed
2—presentation not allowed
3—address not available
GTD parameter
Original called number (OCN)
Field
#— Address. # is representated by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
GTD parameter
Charge number (CHN)
Field
#— Address. # is represented by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
GTD parameter
Generic address (GEA)
Field
cni— Complete number indicator
Field values
0—Unknown
1—Number complete
2—Number incomplete
GTD parameter
Generic address (GEA)
Field
pi— Address presentation indicator
Field values
0—Unknown
1—Presentation allowed
2—Presentation restricted
3—Address not available
GTD parameter
Generic address (GEA)
Field
#—Address. # is represented by num in the Cisco VoiceXML variable.
Field values
A string of one or more telephony digits.
GTD parameter
Carrier identification (CID)
Field
ton— Type of network
Field values
0—Unknown
1—ITU/CCITT
2—National
GTD parameter
Carrier identification (CID)
Field
cid— Carrier identification
Field values
One or more characters from 0-9 and A-F to identify the carrier.
GTD parameter
Transit network selection (TNS)
Field
ton— Type of network
Field values
0—Unknown
1—ITU/CCITT
2—National
GTD parameter
Transit network selection (TNS)
Field
cc— Circuit code
Field values
1—International call, no operator requested
2—International call, operator requested
251—Not applicable
252—Unknown
GTD parameter
Transit network selection (TNS)
Field
tns— Network identification
Field values
IA5—Characters from 0-9 and A-F of length defined by the fields ton and nip.
GTD parameter
Parameter compatibility (PCI)
Field
tri— Transit at intermediate exchange indicator
Field values
0—No transit
1—Yes transit
GTD parameter
Known field compatibility information (FDC)
Field
parm— Parameter name
Field values
A string of three ASCII characters.
GTD Manipulation, Cisco IOS Release 12.3
Cisco VoiceXML enables a VoiceXML script to access GTD parameters before and after a call transfer, to append and override GTD parameters, and to create new GTD messages. For example, if an incoming call setup event contains a GTD IAM message, the <transfer> element uses the IAM message and overrides or appends the parameters specified by the <transfer> GTD attributes. If the incoming setup event does not contain the IAM message, and if the VoiceXML script wants to send a GTD message on the outgoing leg, it creates a new IAM GTD message and adds or appends the required GTD parameters to it. The VoiceXML script sends this new GTD message to the outgoing leg using the <transfer> element. The GTD messages can only contain parameters specified in the tables in this document.
GTD messages and their individual parameters are represented as JavaScript objects. The GTD message object is at the top level, and the individual parameters are represented at the subobject level. The individual subfields of GTD parameters can be accessed and modified as properties of the parameter subobject. GTD messages received on an incoming call leg during the setup event are represented by the Cisco VoiceXML session variable com.cisco.signal.gtdlist which is an array of GTD objects indexed by the call signal event name (setup_indication). This session variable allows the VoiceXML script to only read the GTD parameters received in the setup message. Being a session variable, the VoiceXML script has read-only acccess to the GTD parameters.
The Cisco VoiceXML shadow variable of the form <transfer_name>$.com.cisco.signal.gtdlist is used to read GTD parameters on the outgoing leg after the call transfer terminates. This shadow variable is a read-only variable representing an array of GTD objects indexed by the call signal event name. The VoiceXML script uses the Cisco shadow variable to only read GTD messages passed in the alert, disconnect, and connect events. Reading a valid parameter that is not included in a GTD message results in the return value undefined. Setting a parameter that is not supported causes an exception error event to be thrown by the system.
The object com.cisco.objclass.gtd is a Cisco object class that is used to modify an existing GTD message or create a new GTD message that allows the VoiceXML script to have read-write access to the GTD messages.
The VoiceXML script can use the Cisco attribute cisco-gtd with the <transfer> element to send a modified GTD message to the outbound call leg. The attribute represents the GTD object that is sent on the outbound leg. cisco-gtd is also used with the <disconnect> element to send a GTD message during a call release.
Usage Guidelines
Table 1-16 describes GTD parameters. Table 1-17 describes the GTD messages mapped to the GTD parameters and their fields.
Note
Table 1-17 GTD Parameters and Fields
RGN.noa
RGN.npi
RGN.pi
RGN.#
RNI.ri
RNI.orr
RNI.rc
RNI.rr
OCN.noa
OCN.npi
OCN.pi
OCN.#
CHN.npi
CHN.#
CHN.noa
GEA.type
GEA.noa
GEA.npi
GEA.cni
GEA.pi
GEA.#
GEA.si
CPC.cpc
OLI.oli
CID.ton
CID.cid
TNS.nip
TNS.cc
TNS.tns
PCI.instr
PCI.tri
PCI.dat
FDC.parm
FDC.instr
FDC.dat
RNN.noa
RNN.inn
RNN.npi
RNN.#
RNR.rnr
CDI.nso
CDI.rr
GNO.ni
CNN.noa
CNN.npi
CNN.pi
CNN.si
CNN.#
PRN.prot
PRN.c
PRN.o
PRN.prv
RDC.rc
CGN.noa
CGN.npi
CGN.pi
CGN.si
CPN.noa
CPN.npi
CAI.cau 1
UUS.dat
1 CAI.cau is set by passing it as an attribute cisco-disc_cause through the <disconnect> element.
To create, modify, and read GTDs, the following Cisco objects are used:
•
This is a JavaScript Cisco-specific object class that is used to create new GTD messages. To create an object of a specific class (instantiate) for creating a new GTD message, use:
X= new com.cisco.objclass.gtd()
Later, the GTD message can be represented in a format similar to:
X.message_type = "IAM"
Note
•
This is a Cisco-specific session variable that represents an array of GTD objects (each object representing a GTD message) for signaling events arriving on the incoming leg. The elements of this array can be accessed in read-only mode. The VoiceXML script accesses the GTD parameters and their fields from this session variable which is indexed by the signaling event as shown in the following format:
com.cisco.signal.gtdlist["setup_indication"] where
The elements of this array are read-only.
The VoiceXML/JSE script can access the GTD parameters and their fields from com.cisco.signal.gtdlist indexed by the signaling event as in:
X = com.cisco.signal.gtdlist["setup_indication"]
Initially, at the start of a session, an array is created with only one element (for Setup Ind event). Later, as other events are received, the GTD objects for the associated GTD messages are added to this array. For example,
X = com.cisco.signal.gtdlist["setup_indication"] where X is read-only.
dat1 = X.PCI[0].dat for the dat field in the first instance of the PCI parameter.
Another Object can be created from com.cisco.signal.gtdlist using the new operation in com.cisco.objclass.gtd as in:
Y = new com.cisco.objclass.gtd(com.cisco.signal.gtdlist["setup_indication"])
In this case, the new object Y contains a copy of the GTD message that arrived with the Setup Ind event and is a read-write object. Y can now be used for modifying GTD parameters.
•
This is a Cisco-specific shadow variable that is used by the VoiceXML script to access GTD parameters on the outgoing leg after the <transfer> is complete. The shadow variable consists of the transfer name and "$" prepended to com.cisco.signal.gtdlist.
In <transfer name= "gtd_xfer"..../>, gtd_xfer$.com.signal.gtdlist is an array of GTD objects for the outgoing leg indexed by signaling event names mentioned in gtd_xfer$.com.cisco.signal.gtdlist["<event-name>"] where
<event-name> represents the following signaling events arriving on the incoming leg:
–
–
–
Example:
<assign name="data" expr= "gtd_xfer$.com.cisco.signal.gtdlist['alert_indication'].PCI[0].dat"/>GTD Object and Parameter Syntax
GTD Parameter Syntax
<gtd-object-name>.<gtd-parameter-name> [<instance-number>]
For example, the first instance of the PCI parameter is referenced as my_gtd.PCI[0], where my_gtd is created as an instance of the GTD message or com.cisco.signal.gtdlist.
GTD Parameter Field Syntax
<gtd-object-name>.<gtd-parameter-name>[<instance-number>].<field-name>
For example, the data field of the first instance of the PCI parameter is referenced as my_gtd.PCI[0].dat, where my_gtd is created as an instance of the GTD message or com.cisco.signal.gtdlist.
Multiple Instances
A parameter in a GTD message can have multiple instances which need not be contiguous. In VoiceXML and JavaScript, indexing of instance numbers of GTD parameters starts with zero. For example, the first instance of a GTD parameter is referenced with the index number zero, the second instance is referenced with the index number one, the third instance is referenced with the index number two.
The syntax <gtd-object-name>.<gtd-parameter-object-name>[<instance-number>] refers to a specific instance. The property instance_count is exposed to every GTD parameter object. The VoiceXML script must first read this property before accessing a specific instance. The instance number must be less than or equal to the total number of instances read by the script.
For example:
<assign name="my_gtd" expr= "new com.cisco.objclass.gtd(com.cisco.signal.gtdlist['setup_indication'])"/><assign name="total_pci_inst" expr="my_gtd.PCI.instance_count"/><assign name="pci2" expr="my_gtd.PCI[2]" >/<assign name="tri2" expr="my_gtd.PCI[2].tri">/GTD parameter instance numbers start with 0 for the first instance. For example,
<assign name= "my_gtd" expr= "com.cisco.signal.gtdlist['setup_indication']"/><assign name= "pci1" expr= "my_gtd.PCI[0]"/> ==> for first PCI instance<assign name= "pci2" expr= "my_gtd.PCI[1]"/> ==> for second PCI instance
Note
Creating a New GTD Message
The Cisco object class com.cisco.objclass.gtd is used to create GTD objects for read-write purposes. This object class is used to create a completely new GTD message or to create a copy of a GTD message received in a signaling event.
To create a new GTD message, use the format new com.cisco.objclass.gtd().
Example:
<var name= "my_new_gtd" expr= "new com.cisco.objclass.gtd()"> creates a new empty GTD message. The message type for this GTD can be set later. For example,
<var name= "my_new_gtd.message_type" expr="IAM"/>. This GTD message is sent out using the <transfer> element.
Only GTD objects can be created; parameter objects cannot be created. For example,
<assign name="my_pci" expr="new PCI"/> is incorrect.
<assign name="my_pci" expr="my_gtd.PCI[0]"/> is correct (for the first instance).
Reading and Modifying GTD Parameters
To modify a GTD message, an instance is created using the new operator in com.cisco.objclass.gtd.
Examples
1.
This example creates a copy of the GTD message that came with the Setup Ind event on the incoming leg.
2.
This example creates a copy of the GTD message from the <transfer> shadow variable gtd_xfer$.com.cisco.signal.gtdlist (assuming that gtd_xfer was the name of the transfer.) out_gtd contains a copy of the GTD parameters that arrived in the alert message on the outgoing leg. This is a read-write variable and is used to modify GTD parameters.
3.
This example creates a copy of the GTD message received in the setup message on the incoming leg which will be used to modify a GTD message.
<assign name= "my_gtd.PCI[0].tri" expr="99"/> updates the tri field of the first instance of the PCI parameter of the GTD message represented by my_gtd.
<var name= "my_pci" expr= "my_gtd.PCI[0]"/> // first instance of PCI parameter<var name= "pci_data" expr= "my_pci.dat"/><assign name= "my_pci.dat" expr= "pci_data+5"/>This example shows a VoiceXML script modifying a GTD message that arrived with a Setup Ind event.
The same example is shown here using an ECMAScript:
<script>var my_gtd= new com.cisco.objclass.gtd(com.cisco.signal.gtdlist["setup_indication"])var my_pci= my_gtd.PCI[0]; // first instance of PCI parametervar pci_data= my_pci.datmy_pci.dat= pci_data+5;<script/>The following modifications of a GTD parameter or field are supported:
•
•
Delete is not supported.
If the VoiceXML script adds an instance of a GTD parameter with the instance number being greater than the current instance count by one, the parameter is appended. If the instance number is less than or equal to the current instance count, the specified parameter is replaced.
Examples
If the number of instances currently existing in a GTD message is two, and:
•
•
•
GTD Manipulation Sample Scripts
Here are some sample scripts you can use to get familiar with GTD Manipulation.
Accessing GTD parameters received during call setup.
<vxml version="2.0"><form><var name="X" expr="com.cisco.signal.gtdlist['setup_indication']"/><var name="rgn1" expr="X.RGN[0].noa"/><var name="rgn2" expr="X.RGN[0].npi"/><var name="rgn3" expr="X.RGN[0].pi"/><var name="x" expr="X.RGN[0]['#']"/><var name="cgn1" expr="X.CGN[0].noa"/><var name="cgn2" expr="X.CGN[0].npi"/><var name="cgn3" expr="X.CGN[0].pi"/><var name="cgn4" expr="X.CGN[0].si"/><var name="y" expr="X.CGN[0]['#']"/><var name="cpn1" expr="X.CPN[0].noa"/><var name="cpn2" expr="X.CPN[0].npi"/><var name="z" expr="X.CPN[0]['#']"/><block><log> x is:<value expr="x"/>:</log><log> y is:<value expr="y"/>:</log><log> z is:<value expr="z"/>:</log><var name="rc" expr="'passed'"/><if cond="x != '9876543210' && y != '9876543210' && z != '0123456789'"><assign name="rc" expr="'failed'"/></if><log> WB_FEAT_GTD_1001:END: <value expr="rc"/> </log><disconnect/></block></form></vxml>Accessing a Valid but Unavailable GTD Parameter
<form><var name="X" expr="com.cisco.signal.gtdlist['setup_indication']"/><var name="pcidat" expr="X.PCI[0].dat"/><block><if cond="pcidat== 'Undefined' || pcidat== 'undefined'"><log> Got expected value for GTD parameter PCI.dat as <value expr="pcidat"/>:</log><else/><log> Got UNEXPECTED value for GTD parameter PCI.dat as <value expr="pcidat"/>:</log><assign name="test" expr="'failed'"/></if><goto next="#printresult"/></block></form><form id="printresult"><block><log> <value expr="testcase"/>:END: <value expr="test" /> </log></block></form></vxml>Creating a GTD Message
<form><var name="my_new_gtd0" expr="new com.cisco.objclass.gtd()"/><var name="my_new_gtd1" expr="new com.cisco.objclass.gtd()"/><var name="my_new_gtd2" expr="new com.cisco.objclass.gtd()"/><var name="my_new_gtd3" expr="new com.cisco.objclass.gtd()"/><var name = "my_new_gtd0.message_type" expr = "'IAM'"/><var name = "my_new_gtd1.message_type" expr = "'ACM'"/><var name = "my_new_gtd2.message_type" expr = "'CPG'"/><var name = "my_new_gtd3.message_type" expr = "'REL'"/><block><log> message type for my_new_gtd0 is <value expr="my_new_gtd0.message_type"/></log><log> message type for my_new_gtd1 is <value expr="my_new_gtd1.message_type"/></log><log> message type for my_new_gtd2 is <value expr="my_new_gtd2.message_type"/></log><log> message type for my_new_gtd3 is <value expr="my_new_gtd2.message_type"/></log><goto next="#printresult"/></block></form><catch event="error.semantic"><assign name="res" expr="'failed'"/><goto next="#printresult"/></catch><form id="printresult"><block><log> <value expr="testcase"/>:END:<value expr="res"/> </log></block></form></vxml>Modifying Attributes in a GTD Message
<form><var name="my_gtd0" expr="new com.cisco.objclass.gtd()"/><var name = "my_gtd0.message_type" expr = "'IAM'" /><var name = "my_gtd0.RGN[0].npi" expr = "4" /><var name = "my_gtd0.RGN[0].pi" expr = "'y'" /><var name = "my_gtd0.RGN[0]['#']" expr = "'408-527-4800'" /><!-- Second gtd message use if needed --><var name="my_gtd1" expr="new com.cisco.objclass.gtd()"/><var name = "my_gtd1.message_type" expr = "'CPG'" /><block><log> message type for my_gtd0 is <value expr="my_gtd0.message_type"/></log><log> rgn.npi for my_gtd0 is <value expr="my_gtd0.RGN[0].npi"/></log><log> rgn.pi for my_gtd0 is <value expr="my_gtd0.RGN[0].pi"/></log><log> rgn.# for my_gtd0 is <value expr="my_gtd0.RGN[0]['#']"/></log><if cond="my_gtd0.RGN[0].npi== '4' || my_gtd0.RGN[0].pi== 'y' || my_gtd0.RGN[0]['#'] == '408-527-4800'"><assign name="res" expr="'passed'"/><else/><log> Failed to modify new GTD instance.</log></if><goto next="#printresult"/></block></form><form id="printresult"><block><log> <value expr="testcase"/>:END:<value expr="res"/> </log></block></form></vxml>Using <transfer> and <disconnect> for GTD Manipulation
The Cisco-specific attribute cisco-gtd is used with the <transfer> element to send GTDs on the outgoing call leg.
<transfer name="gtd_xfer" dest="tel: +1-555-555-0167" bridge="true"!!cisco-gtd="my_gtd"!!/>It is also used as an attribute of the <disconnect> element to send GTDs during a call release.
<disconnect> cisco-disc_cause="cause_code"cisco-gtd="my_gtd"!/>User-to-User Information Manipulation
User-to-user information allows an external entity represented by a user-to-user information element (UUIE), to pass additional information for interaction with the Cisco IVR infrastructure. For example, a UUIE can pass "callerName=Joe; callerAccount=1234" which is processed by the ECMAScript and sent to the application server. A UUIE is sent in the UUS parameter of a GTD message through the <transfer> or <disconnect> elements. UUIE manipulation operations supported include read, append, and replace.
A VoiceXML script can access user-to-user information for ISDN and ISUP by reading the dat field of the UUS GTD parameter. The information can be set or modified by writing to the same dat field. This information is sent through the <transfer> and <disconnect> elements by specifying the GTD object that contains the information in the cisco-gtd attribute. If the GTD object specified in the attribute is invalid or null, an error event error.com.cisco.invalid.gtd.object is generated.
GTD Manipulation Error Events
Accessing a GTD parameter or its field returns an undefined value, and modifying a parameter or its field throws an error.semantic exception for the following errors in VoiceXML or JavaScript:
•
•
•
•
If the cisco-gtd attribute in <transfer> and <disconnect> does not translate to a valid GTD object, it is ignored with no error events are thrown, and the GTD message received from the incoming leg (in setup Indication) is sent to the outgoing leg.
If the disconnect cause code in <disconnect> is not translated to a positive integer, an error.semantic error event is thrown and VoiceXML document is terminated. No further validation (for example, checking the range) is performed on the disconnect cause code. It is the responsibility of the VoiceXML script to provide correct disconnect cause codes.
Redirecting Calls
Cisco IOS Release 12.3 allows a call to be redirected either through the CLI, or through a VoiceXML script using Cisco VoiceXML. These calls are redirected through the following two mechanisms:
•
•
Release to Pivot: Redirecting Calls for ISUP
Call redirection using the Release-to-Pivot (RTPvt) mechanism can be invoked through the Cisco IOS CLI or through a VoiceXML script in Cisco VoiceXML. In Cisco VoiceXML, RTPvt is invoked through the <transfer> element with bridge= `FALSE'. The call transfer modes are controlled through the Cisco root document property com.cisco.transfer.mode.
For more information on invoking RtPvt through the CLI, see "Configuring Telephony Call-Redirect Features" chapter of the Cisco IOS Tcl IVR and VoiceXML Application Guide.
Invoking Release-to-Pivot
In Cisco VoiceXML, the Release-to-Pivot (RTPvt) mechanism is invoked through the <transfer> element with bridge= `FALSE'. The Cisco root document property com.cisco.transfer.mode with a specific value is used in the VoiceXML script to invoke RTPvt.
com.cisco.transfer.mode
The following transfer modes apply to RTPvt:
•
•
•
•
Sample Script
This sample script shows RTPvt invoked in VoiceXML version 2.0. The incoming GTD message contains RDC=3.
<<var name="res" expr="'failed'"/><var name="testcase" expr="'ABC'"/><var name="phone_num" expr="session.telephone.dnis" /><var name="mydur" /><catch event="error.semantic" ><log> got the unexpected error event </log><goto next="#printresult"/></catch><property name="com.cisco.transfer.mode" value="redirect-rotary" /><form id = "transfer_me"><block><audio src="en_welcome.au " /></block><transfer name="mycall" destexpr="'tel: '+ phone_num"connecttimeout="50s" bridge="false" maxtime="50s"cisco-longpound="true"><filled><assign name="mydur" expr="mycall$.duration"/><log>The value in mycall is <value expr="mycall"/> </log><log>Duration of call is <value expr="mydur"/></log></filled><catch event="telephone.disconnect.transfer" ><log> Call Transfered as expected </log><var name="res" expr="'passed'"/><goto next="#printresult"/></catch></transfer></form><form id="printresult"><block><log> <value expr="testcase"/>:END:<value expr="res"/> </log><disconnect/></block></form></vxml>Two B Channel Transfer: Redirecting Calls for ISDN
Two B-Channel Transfer (TBCT) is an ISDN based call transfer feature that enables a Cisco voice gateway to perform call redirection through a VoiceXML script using Cisco VoiceXML. Call redirection using the Two B-Channel Transfer (TBCT) mechanism is invoked as a transfer initiator only for call setup. TBCT is invoked using VoiceXML blind transfer under the following conditions:
•
–
–
•
If TBCT is invoked successfully, the call legs are eventually disconnected. If TBCT cannot be invoked because of an ISDN switch rejecting the TBCT request, the transfer falls back to a hairpinned call.
Invoking Two B-Channel Transfer
Two B-Channel Transfer (TBCT) for multiple trunk groups is invoked through a VoiceXML script using blind transfer under the following transfer modes:
To ensure successful TBCT for multiple trunk or trunkgroups that can reach the same destination, the voice gateway uses carrier sensitive routing to place an outgoing call from the router to the interfaces that are connected to the same trunk group as the incoming call.
To enable TBCT for multiple trunk or trunk groups:
•
•
•
For information on configuring the carrier source ID and the outbound dial peers, see the Cisco IOS Tcl and VoiceXML Application Guide.
The following specific Cisco session variables and <transfer> attributes are used in a VoiceXML script to identify the carrier ID:
Session Variables
•
•
<transfer> attributes
•
•
Sample Script
This sample script shows a TBCT invoked for multiple trunk groups through a VoiceXML version 2.0 script using blind transfer.
<var name="res" expr="'failed'"/><var name="testcase" expr="'T_1_2'"/><var name="phone_num" expr="session.telephone.dnis"/><var name="source" expr="session.com.cisco.carrierid.source"<var name="mydur" /><catch event="error.semantic" ><log> got the unexpected error event </log><goto next="#printresult"/></catch><property name="com.cisco.transfer.mode" value="redirect-at-alert"/><form id = "transfer_me"><block><audio src="flash:en_welcome.au" /></block><transfer name="mycall" destexpr="'tel: '+ phone_num"connecttimeout="20s" bridge="false" maxtime="20s"cisco-longpound="true"cisco-carrierid-target="source"><filled><assign name="mydur" expr="mycall$.duration"/><log>The value in mycall is <value expr="mycall"/> </log><log>Duration of call is <value expr="mydur"/></log></filled><catch event="telephone.disconnect.transfer" ><log> Call Transfered as expected </log><var name="res" expr="'passed'"/><goto next="#printresult"/></catch></transfer></form><form id="printresult"><block><log> <value expr="testcase"/>:END:<value expr="res"/> </log><disconnect/></block></form></vxml>Blind Transfer Using SIP
Cisco VoiceXML can initiate a blind transfer using the Refer method in SIP. For more information on using the Refer method in SIP, see SIP Call Transfer Enhancements Using the Refer Method.
Disconnect Cause Code
Cisco VoiceXML allows a Cisco-specific disconnect cause code cisco-disc_cause to be specified as an attribute of the <disconnect> element. The cause code is specified as a value in the script. For cause code values, see the Tcl IVR Version 2.0 Programmer's Guide.
Example
<disconnect> cisco-disc_cause="cause_code"cisco-gtd="gtd_object"/>!cisco-disc_cause and cisco-gtd are of type %expression.
Note
•
•
Hybrid Applications
Cisco IOS allows developers to use Tcl and VoiceXML scripts to develop hybrid applications. Tcl IVR 2.0 extensions allow Tcl applications to leverage support for ASR and TTS by invoking and managing VoiceXML dialogs within Tcl IVR scripts. This enables the implementation of hybrid applications using Tcl IVR for call control and VoiceXML for dialog management. VoiceXML is used for designing and conducting dialogs with the user over the telephone. For example, VoiceXML dialog is mainly used for IVR activities such as collecting user input, or playing prompts. However, it has limited capabilites for call control. Call control is the ability to receive, create, and manage new connections (call legs) with one or more users. Call control also allows advanced calling features to be implemented through the interconnection of these call legs. These advanced calling features create and manage multiple sessions with multiple users and simultaneously conduct dialogs with them. To allow implementation of these advanced calling features, the Cisco voice application infrastructure uses hybrid applications. Hybrid applications enable simple implementations of advanced call services that require ASR, TTS, or web integration.
Cisco hybrid applications use both Tcl IVR 2.0 and VoiceXML APIs that allow a developer to write only one application that runs and behaves like a single application instance. VoiceXML dialogs can be invoked through the Tcl IVR script. These VoiceXML dialogs are directed at any of the connected call legs or user sessions that are managed by the Tcl IVR application. The VoiceXML dialog code and the Tcl IVR script execute simultaneously, sharing control over the call leg and working together as one application.
The Tcl IVR script controls the call and all its call legs. It receives ev_setup_indication events for incoming call legs and issues leg alert or call leg acceptance commands through the leg connect Tcl IVR verb. The Tcl script can also create outgoing call legs and bridge multiple call legs. The Tcl script has two choices in conducting a dialog a with the user. It can use the existing leg collectdigits and media play Tcl IVR verbs to play individual audio prompts and collect digits, or it can use the leg vxmldialog Tcl IVR verb to initiate the VoiceXML dialog on the call leg. This verb starts a VoiceXML interpreter session on the call leg under the direct control of the Tcl IVR script. The initial VoiceXML document can be embedded in a Tcl IVR script or it can be referenced by the Tcl script in form of a URI pointing to a VoiceXML document on a web server.
The VoiceXML session started on a call leg does not support the <transfer> element. In a hybrid application, calls are transferred in Tcl using the leg setup Tcl IVR command. The leg setup command requests the system to place a call to the specified destination number. To transfer a call, the VoiceXML dialog completes its execution, and passes control to the Tcl application to perform a leg setup for the call.
When the Tcl IVR script initiates a VoiceXML dialog on a call leg, it passes an array of parameters to the leg vxmldialog verb. The parameters are accessible in the VoiceXML session through the com.cisco.params.xxxx variable. In the VoiceXML session, the com.cisco.params object gets populated with information from the Tcl array where xxxx is the index of the array. After the VoiceXML dialog is complete, some information is returned to the Tcl IVR script throw the namelist attribute of the <exit> element. Upon completion of the VoiceXML dialog, the Tcl script receives a ev_vxmldialog_done event which contains the information returned in the <exit> element including a status code which can be accessed through the evt_status information tag.
The Tcl IVR script can also send intermediate messages to a VoiceXML dialog in progress through the leg vxmlsend Tcl IVR verb. The event specified in this verb is thrown inside the VoiceXML interpreter and caught by a <catch> handler looking for that event. The leg vxmlsend verb can also have a Tcl parameter array which is accessible inside the VoiceXML catch handler through the scoped variable _message.params.xxxx which is similar in function to the com.cisco.params.xxxx variable.
The VoiceXML interpreter environment or the VoiceXML document can also send events to the Tcl IVR script during various stages of execution. These events arrive at the Tcl script as ev_vxmldialog_event events. A VoiceXML dialog that is executing can use an <object> extension with classid= "builtin://com.cisco.ivrscript.sendevent" to send a specific message with associated parameter information to the parent Tcl script. If the VoiceXML dialog executes certain elements such as <transfer> or <disconnect> in the hybrid mode, the Tcl script receives an ev_vxmldialog_event event implicitly. An ev_vxmldialog_done event or an ev_vxmldialog_event event can arrive with the following information:
•
The evt_vxmlevent information tag contains a vxml.dialog.* string, if:
–
–
•
Execution of the <disconnect> element in hybrid mode does not disconnect a call leg. A vxml.session.disconnect event is sent to the Tcl IVR script where a <disconnect> is emulated, the disconnect event is thrown, and the script continues execution. From this point onward, the VoiceXML dialog cannot play prompts or collect input. When the user hangs up, a <disconnect> is again emulated and the leg stays connected. The Tcl script receives an ev_disconnected event and then must decide to either disconnect the leg immediately, or wait for the VoiceXML dialog to terminate and then disconnect the leg.
Execution of the <transfer> element in hybrid mode results in two events:
•
•
Events and Errors
•
The VoiceXML interpreter receives this event when the VoiceXML dialog executes a <transfer> element. The <transfer> element is not supported in hybrid applications.
sendevent Object
Recorded objects are represented as audio object variables in a VoiceXML script. In a Tcl script which is text based, they are represented in the form "ram://xxxx"URI. When information is sent from the Tcl to the VoiceXML script, Tcl array elements which have a value of "ram://xxxx" are available as audio variables or objects in the VoiceXML script. Similarly, when information is passed from a VoiceXML to a Tcl script, the audio variables or objects in the VoiceXML script will be available as Tcl array elements through the sendevent object in the form "ram://xxxx"URI in the Tcl script. The Tcl IVR script can play the audio object through the media play Tcl IVR verb. The sendevent object allows the VoiceXML session to send asynchronous events to the Tcl IVR script. The events are sent as parameters, in the form of strings, under the parameter eventname in the script shown below. The Tcl IVR script receives an ev_vxmldialog_event when the VoiceXML application invokes the sendevent object. The event name is available to the Tcl IVR script through the evt_vxmldialog_event infotag and is of the form vxml.dialog.eventname. The event carries the variables specified as com.cisco.datatype.list in the parameter name.
The sendevent object is accessed as follows:
<object>name="sendevent"classid="builtin://com.cisco.ivrscript.sendevent"<param name="eventname" expr="section6.stage5"/><param name="name1" expr="value1" valuetype= "com.cisco.datatype.list"/><param name="name2" expr="value2" valuetype= "com.cisco.datatype.list"/>....<param name="nameN" expr="valueN" valuetype= "com.cisco.datatype.list"/></object>
Limitations and Restrictions
For limitations and restrictions on using Cisco VoiceXML, see the Cisco IOS Tcl IVR and VoiceXML Application Guide.
VoiceXML Document Loops
Cisco IOS VoiceXML provides safeguards against denial of service attacks that use infinite looping VoiceXML documents.
A maximum of ten loops are permitted per VoiceXML session to help prevent disruption of the system by a malicious looping program. Loops are counted when a VoiceXML document transits to another dialog within a document or goes to another document using <submit> or <goto> without any user interaction. If a document goes to another dialog or another document ten times without any prompts or digit collection, the session is aborted.
The loop count includes both before <disconnect> and after <disconnect> events. After <disconnect>, the VoiceXML document is mostly unrestricted if there is no user interaction.
Additional References
The following sections provide references related to Cisco VoiceXML.
Related Documents
Tcl and IVR
Enhanced Multi-Language Support for Cisco IOS Interactive Voice Response
Voice
Cisco IOS Voice Command Reference, Release 12.4T
Basic Configuration
Cisco IOS Configuration Fundamentals Configuration Guide
Cisco IOS Configuration Fundamentals Command Reference, Release 12.4T
Security
Configuring RADIUS with a Livingston Server
RADIUS Vendor Specific Attributes Implementation Guide
Authentication, Authorization, and Accounting: Cisco IOS Security Configuration Guide, Release 12.2
VoiceXML
Cisco VoiceXML Solution Infrastructure
Standards
ECMA-262
ECMAScript Specification 3.0 (Standard ECMA-262, ECMAScript Language Specification, 3rd edition, August 1998
RFCs
RFC 2298
An Extensible Message Format for Message Dispostion Notification
RFC 1894
An Extensible Message Format for Delivery Status Notifications
Technical Assistance
