Cisco VoiceXML Programmer’s Guide

Cisco IOS Release 15.0(1)M

Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883

Customer Order Number: OL-11175-01

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL
STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT
WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT
SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE
OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public
domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH
ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT
LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF
DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING,
WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO
OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

CCVP, the Cisco logo, and the Cisco Square Bridge logo are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn is a service mark of
Cisco Systems, Inc.; and Access Registrar, Aironet, BPX, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, Cisco, the Cisco Certified Internetwork Expert logo,
Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Fast Step,
Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iPhone, IP/TV, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, iQuick Study,
LightStream, Linksys, MeetingPlace, MGX, Networking Academy, Network Registrar, Packet, PIX, ProConnect, ScriptShare, SMARTnet, StackWise, The Fastest Way to
Increase Your Internet Quotient, and TransPath are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.

All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply a partnership relationship
between Cisco and any other company. (0705R)

Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the
document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.

Licensing Information

The following license agreement covers the XML parser code that is used by the VoiceXML interpreter and is contained in the Cisco IOS software image.

The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may
obtain a copy of the License at http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific
language governing rights and limitations under the License.

Alternatively, the contents of this file may be used under the terms of the GNU General Public License (the "GPL"), in which case the provisions of the GPL are applicable
instead of those above. If you wish to allow use of your version of this file only under the terms of the GPL and not to allow others to use your version of this file under the
MPL, indicate your decision by deleting the provisions above and replacing them with the notice and other provisions required by the GPL. If you do not delete the provisions
above, a recipient may use your version of this file under either the MPL or the GPL.

The Original Code is expat.

The Initial Developer of the Original Code is James Clark.

Portions created by James Clark are Copyright (C) 1998, 1999

James Clark. All Rights Reserved.

Contributor(s): Jenny Yao from Cisco Systems, Inc.

Modification of the source code made by Jenny Yao is controlled by definition of "TARGET_CISCO".
Cisco Modification of Expat Source Code

File Modified Description of Modification

hashtable.h Remove include file <stddef.h>.
xmldef.h Include Cisco IOS <master.h> file.
hashtable.c Change filename from hashtable.c to xmlhashtable to avoid a generic filename.
Cisco Modification of Expat Source Code (continued)

File Modified Description of Modification

xmlparse.c Remove some variables defined but not used, like errorProcessor and internalEnc.

Type cast (int) for sizeof() during arithmetic operation.

Add new routine XML_realloc(), replacing realloc() in this file because usage of realloc() could cause memory
leakage.
xmltok.c Add argument type void for function with empty argument.

Type cast (int) for sizeof() during arithmetic operation.

xmltok.h Add argument type void for function with empty argument.
xmltok_impl.c Initialize variable open to 0.
filexmltok_impl.h Remove file including for <stddef.h>.

Cisco VoiceXML Programmer’s Guide

© 2006-2007 Cisco Systems, Inc. All rights reserved.
 C O N T E N T S

Preface ix

Audience ix

Structure of This Guide ix

Document Conventions x

Obtaining Documentation x
Cisco.com xi
Product Documentation DVD xi
Ordering Documentation xi
Documentation Feedback xi

Cisco Product Security Overview xi

Reporting Security Problems in Cisco Products xii

Product Alerts and Field Notices xii

Obtaining Technical Assistance xiii

Cisco Support Website xiii
Submitting a Service Request xiv
Definitions of Service Request Severity xiv
Developer Services xiv
Obtaining Additional Publications and Information xv

Cisco VoiceXML Features 1-1

Audience 1-1

Recommended Knowledge 1-2

Prerequisites 1-2
VoiceXML Document Development 1-2
Cisco Voice Gateway Requirements 1-3
Overview of Cisco VoiceXML Features 1-3
Voice Store and Forward Feature 1-5
Volume and Rate Control Feature 1-6
ASR and TTS Features 1-6
Tcl IVR 2.0 and VoiceXML Integration (Hybrid Applications) Feature 1-7
T.37 Store and Forward Fax Detection Feature 1-7
System Output 1-8
Audio Playout 1-9

Cisco VoiceXML Programmer’s Guide

OL-11175-01 v
Contents

Prerecorded Audio Prompts 1-9

Synthesized Audio Playout 1-11
External Server Failure 1-13
Volume and Rate Control 1-16
Type-ahead Support 1-20
Buffer Control and Flushing 1-20
cisco-typeaheadflush Attribute for <prompt> 1-21
com.cisco.autoflush Property 1-21
Type-ahead Buffer with <goto> or <transfer> to an Application 1-21
Type-ahead Interaction with Barge-In 1-21
User Input 1-22
Voice Input 1-22
DTMF Input 1-22
Grammar Support 1-23
Recording Support 1-25
Using cisco-dest 1-26
Shadow Variables 1-28
RAM Recording 1-28
HTTP Recording 1-29
Exception Handling 1-29
Properties for <record> 1-30
Typical Call Flow Using Recording 1-31
<cisco-data> Element 1-31
Transfer Support 1-34
Cisco Longpound Attribute 1-34
Cisco-newguid Attribute 1-34
Continuous Fax Detection and Transfer 1-35
Transfer Form Item Variable 1-38
Cisco Extensions for <transfer> 1-38
Control Flow and Scripting 1-43
Variables 1-43
Supported Session Variables 1-43
Application Variables 1-48
Dialog Variables 1-49
Event Variables 1-49
Event Handling 1-49
Fax Event Handler 1-49
Events and Errors 1-49
JavaScript Support 1-52

Cisco VoiceXML Programmer’s Guide

vi OL-11175-01
 Contents

Environment and Resources 1-52

Resource Fetching and Caching 1-53
Fetching 1-53
Caching 1-53
Property 1-54
Default Values and Ranges 1-56
Call Handoff 1-56

Authentication and Authorization 1-59

Authentication 1-59
Authorization 1-61
SIP and H.323 Support 1-63
SIP and TEL URL Support 1-63
Passing Headers in Voice Messages 1-65
Headers in Outbound Calls 1-65
Headers in Inbound Calls 1-67
Example: Passing a SIP URL with Headers Using SIP 1-68
Example: Passing a TEL URL with Headers Using H.323 1-69
SIP Blind Call Transfer 1-70
GTD Manipulation, Cisco IOS Release 12.2(11)T 1-71
GTD Parameters and Fields Mapped to VoiceXML Variables 1-71
GTD Parameter Reference 1-87
GTD Manipulation, Cisco IOS Release 12.3 1-98
Usage Guidelines 1-99
GTD Object and Parameter Syntax 1-103
Creating a New GTD Message 1-104
Reading and Modifying GTD Parameters 1-104
GTD Manipulation Sample Scripts 1-105
Using <transfer> and <disconnect> for GTD Manipulation 1-108
User-to-User Information Manipulation 1-108
GTD Manipulation Error Events 1-108
Redirecting Calls 1-109
Release to Pivot: Redirecting Calls for ISUP 1-109
Two B Channel Transfer: Redirecting Calls for ISDN 1-110
Blind Transfer Using SIP 1-112
Disconnect Cause Code 1-112
Hybrid Applications 1-113
sendevent Object 1-115
Limitations and Restrictions 1-116
VoiceXML Document Loops 1-116

Cisco VoiceXML Programmer’s Guide

OL-11175-01 vii
 Contents

Additional References 1-117

Related Documents 1-117
Standards 1-117
RFCs 1-117
Technical Assistance 1-118

Cisco VoiceXML Troubleshooting 2-1

Debugging Cisco VoiceXML Applications 2-1

<cisco-puts> 2-1
debug vxml puts 2-1
<cisco-debug> 2-2
CallID and GUID in Debug Messages 2-3
Error Events 2-4

JavaScript/ECMA Script 2-5

Cisco VoiceXML Applications 3-1

Hybrid Application 3-1

Speech Enabled Banking Application 3-7

ASR and TTS Application 3-12

Multi-Language Application 3-15

Recording Application 3-16

Cisco VoiceXML DTD A-1

Cisco VoiceXML Elements: Reference Table B-1

Cisco VoiceXML Programmer’s Guide

viii OL-11175-01
 Preface

Revised: June 20, 2007, OL-11175-01

Voice Extensible Markup Language (VoiceXML) applications provide access to content and services
over the telephone, just as Hypertext Markup Language (HTML) web pages provide access over a web
browser residing 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 content and services of the
World Wide Web.
Use this guide in conjunction with the Cisco IOS TCL and VoiceXML Application Guide for your
Cisco IOS release, and the TCL IVR API Version 2.0 Programmer’s Guide.

Audience
This guide is written for developers writing applications using Cisco VoiceXML features and must be
used in conjunction with the Cisco IOS TCL and VoiceXML Application Guide, and the TCL IVR API
Version 2.0 Programmer’s Guide. It describes features based on the Cisco implementation of the
VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005).

Structure of This Guide

This guide contains the following chapters and appendixes:
• Chapter 1, “Cisco VoiceXML Features”
• Chapter 2, “Cisco VoiceXML Troubleshooting”
• Chapter 3, “Cisco VoiceXML Applications”
• Appendix A, “Cisco VoiceXML DTD”
• Appendix B, “Cisco VoiceXML Elements: Reference Table”

Cisco VoiceXML Programmer’s Guide

OL-11175-01 ix
 Preface
Document Conventions

Document Conventions
This guide uses the following conventions to convey instructions and information.

Convention Description

boldface font Commands and keywords.

italic font Variables for which you supply values.

[ ] Keywords or arguments that appear within square brackets are optional.

{x | y | z} A choice of required keywords appears in braces separated by vertical bars.

You must select one.

screen font Examples of information displayed on the screen.

boldface screen Examples of information you must enter.

font

< > Nonprinting characters, for example passwords, appear in angle brackets in
contexts where italic font is not available.

[ ] Default responses to system prompts appear in square brackets.

Note Means reader take note. Notes contain helpful suggestions or references to additional information and
material.

Timesaver This symbol means the described action saves time. You can save time by performing the action
described in the paragraph.

Caution This symbol means reader be careful. In this situation, you might do something that could result in
equipment damage or loss of data.

Tip This symbol means the following information will help you solve a problem. The tips information might
not be troubleshooting or even an action, but could be useful information, similar to a Timesaver.

Obtaining Documentation
Cisco documentation and additional literature are available on Cisco.com. This section explains the
product documentation resources that Cisco offers.

Cisco VoiceXML Programmer’s Guide

x OL-11175-01
 Preface
Documentation Feedback

Cisco.com
You can access the most current Cisco documentation at this URL:
http://www.cisco.com/techsupport
You can access the Cisco website at this URL:
http://www.cisco.com
You can access international Cisco websites at this URL:
http://www.cisco.com/public/countries_languages.shtml

Product Documentation DVD

The Product Documentation DVD is a library of technical product documentation on a portable medium.
The DVD enables you to access installation, configuration, and command guides for Cisco hardware and
software products. With the DVD, you have access to the HTML documentation and some of the
PDF files found on the Cisco website at this URL:
http://www.cisco.com/univercd/home/home.htm
The Product Documentation DVD is created and released regularly. DVDs are available singly or by
subscription. Registered Cisco.com users can order a Product Documentation DVD (product number
DOC-DOCDVD= or DOC-DOCDVD=SUB) from Cisco Marketplace at the Product Documentation
Store at this URL:
http://www.cisco.com/go/marketplace/docstore

Ordering Documentation
You must be a registered Cisco.com user to access Cisco Marketplace. Registered users may order Cisco
documentation at the Product Documentation Store at this URL:
http://www.cisco.com/go/marketplace/docstore
If you do not have a user ID or password, you can register at this URL:
http://tools.cisco.com/RPF/register/register.do

Documentation Feedback
You can provide feedback about Cisco technical documentation on the Cisco Support site area by
entering your comments in the feedback form available in every online document.

Cisco Product Security Overview

Cisco provides a free online Security Vulnerability Policy portal at this URL:
http://www.cisco.com/en/US/products/products_security_vulnerability_policy.html
From this site, you will find information about how to do the following:
• Report security vulnerabilities in Cisco products

Cisco VoiceXML Programmer’s Guide

OL-11175-01 xi
 Preface
Product Alerts and Field Notices

• Obtain assistance with security incidents that involve Cisco products

• Register to receive security information from Cisco
A current list of security advisories, security notices, and security responses for Cisco products is
available at this URL:
http://www.cisco.com/go/psirt
To see security advisories, security notices, and security responses as they are updated in real time, you
can subscribe to the Product Security Incident Response Team Really Simple Syndication (PSIRT RSS)
feed. Information about how to subscribe to the PSIRT RSS feed is found at this URL:
http://www.cisco.com/en/US/products/products_psirt_rss_feed.html

Reporting Security Problems in Cisco Products

Cisco is committed to delivering secure products. We test our products internally before we release them,
and we strive to correct all vulnerabilities quickly. If you think that you have identified a vulnerability
in a Cisco product, contact PSIRT:
• For emergencies only — security-alert@cisco.com
An emergency is either a condition in which a system is under active attack or a condition for which
a severe and urgent security vulnerability should be reported. All other conditions are considered
nonemergencies.
• For nonemergencies — psirt@cisco.com
In an emergency, you can also reach PSIRT by telephone:
• 1 877 228-7302
• 1 408 525-6532

Tip We encourage you to use Pretty Good Privacy (PGP) or a compatible product (for example, GnuPG) to
encrypt any sensitive information that you send to Cisco. PSIRT can work with information that has been
encrypted with PGP versions 2.x through 9.x.

Never use a revoked encryption key or an expired encryption key. The correct public key to use in your
correspondence with PSIRT is the one linked in the Contact Summary section of the Security
Vulnerability Policy page at this URL:

http://www.cisco.com/en/US/products/products_security_vulnerability_policy.html

The link on this page has the current PGP key ID in use.

If you do not have or use PGP, contact PSIRT to find other means of encrypting the data before sending
any sensitive material.

Product Alerts and Field Notices

Modifications to or updates about Cisco products are announced in Cisco Product Alerts and Cisco Field
Notices. You can receive these announcements by using the Product Alert Tool on Cisco.com. This tool
enables you to create a profile and choose those products for which you want to receive information.

Cisco VoiceXML Programmer’s Guide

xii OL-11175-01
 Preface
Obtaining Technical Assistance

To access the Product Alert Tool, you must be a registered Cisco.com user. Registered users can access
the tool at this URL:
http://tools.cisco.com/Support/PAT/do/ViewMyProfiles.do?local=en
To register as a Cisco.com user, go to this URL:
http://tools.cisco.com/RPF/register/register.do

Obtaining Technical Assistance

Cisco Technical Support provides 24-hour-a-day award-winning technical assistance. The
Cisco Support website on Cisco.com features extensive online support resources. In addition, if you
have a valid Cisco service contract, Cisco Technical Assistance Center (TAC) engineers provide
telephone support. If you do not have a valid Cisco service contract, contact your reseller.

Cisco Support Website

The Cisco Support website provides online documents and tools for troubleshooting and resolving
technical issues with Cisco products and technologies. The website is available 24 hours a day at
this URL:
http://www.cisco.com/en/US/support/index.html
Access to all tools on the Cisco Support website requires a Cisco.com user ID and password. If you have
a valid service contract but do not have a user ID or password, you can register at this URL:
http://tools.cisco.com/RPF/register/register.do

Note Before you submit a request for service online or by phone, use the Cisco Product Identification Tool
to locate your product serial number. You can access this tool from the Cisco Support website
by clicking the Get Tools & Resources link, clicking the All Tools (A-Z) tab, and then choosing
Cisco Product Identification Tool from the alphabetical list. This tool offers three search options:
by product ID or model name; by tree view; or, for certain products, by copying and pasting show
command output. Search results show an illustration of your product with the serial number label
location highlighted. Locate the serial number label on your product and record the information
before placing a service call.

Tip Displaying and Searching on Cisco.com

If you suspect that the browser is not refreshing a web page, force the browser to update the web page
by holding down the Ctrl key while pressing F5.

To find technical information, narrow your search to look in technical documentation, not the
entire Cisco.com website. After using the Search box on the Cisco.com home page, click the
Advanced Search link next to the Search box on the resulting page and then click the
Technical Support & Documentation radio button.

To provide feedback about the Cisco.com website or a particular technical document, click
Contacts & Feedback at the top of any Cisco.com web page.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 xiii
 Preface
Obtaining Technical Assistance

Submitting a Service Request

Using the online TAC Service Request Tool is the fastest way to open S3 and S4 service requests. (S3 and
S4 service requests are those in which your network is minimally impaired or for which you require
product information.) After you describe your situation, the TAC Service Request Tool provides
recommended solutions. If your issue is not resolved using the recommended resources, your service
request is assigned to a Cisco engineer. The TAC Service Request Tool is located at this URL:
http://www.cisco.com/techsupport/servicerequest
For S1 or S2 service requests, or if you do not have Internet access, contact the Cisco TAC by telephone.
(S1 or S2 service requests are those in which your production network is down or severely degraded.)
Cisco engineers are assigned immediately to S1 and S2 service requests to help keep your business
operations running smoothly.
To open a service request by telephone, use one of the following numbers:
Asia-Pacific: +61 2 8446 7411
Australia: 1 800 805 227
EMEA: +32 2 704 55 55
USA: 1 800 553 2447
For a complete list of Cisco TAC contacts, go to this URL:
http://www.cisco.com/techsupport/contacts

Definitions of Service Request Severity

To ensure that all service requests are reported in a standard format, Cisco has established severity
definitions.
Severity 1 (S1)—An existing network is “down” or there is a critical impact to your business operations.
You and Cisco will commit all necessary resources around the clock to resolve the situation.
Severity 2 (S2)—Operation of an existing network is severely degraded, or significant aspects of your
business operations are negatively affected by inadequate performance of Cisco products. You and Cisco
will commit full-time resources during normal business hours to resolve the situation.
Severity 3 (S3)—Operational performance of the network is impaired while most business operations
remain functional. You and Cisco will commit resources during normal business hours to restore service
to satisfactory levels.
Severity 4 (S4)—You require information or assistance with Cisco product capabilities, installation, or
configuration. There is little or no effect on your business operations.

Developer Services
Questions and support issues related to Cisco IOS TCL and VoiceXML Application scripting, and TCL
IVR scripting are not covered by Cisco Technical Support. Cisco Technical Support is limited to standard
Cisco product installation/configuration and Cisco-developed applications—it does not include services
or support on this product.
Developers using this guide may be interested in joining the Cisco Developer Services Program. This
fee-based subscription program was created to provide you with a consistent level of services that you
can depend on while leveraging Cisco interfaces in your development projects. A separate service

Cisco VoiceXML Programmer’s Guide

xiv OL-11175-01
Preface
Obtaining Additional Publications and Information

agreement and subscription fee is required to participate in the Developer Services Program. For more
details on how to subscribe, go to Getting Started on the Program website at
http://www.cisco.com/go/developersupport.
The Developer Services Program provides formalized services for Cisco Systems interfaces to enable
developers, customers, and partners in the Cisco Technology Developer program to accelerate their
delivery of compatible solutions.
The Developer Services Engineers are an extension of the product technology engineering teams. They
have direct access to the resources necessary to provide expert support in a timely manner.
For additional information, refer to Frequently asked Questions about the Program and Support under
Q&A on the Developer Services Program website at www.cisco.com/go/developersupport/.

Obtaining Additional Publications and Information

Information about Cisco products, technologies, and network solutions is available from various online
and printed sources.
• The Cisco Online Subscription Center is the website where you can sign up for a variety of Cisco
e-mail newsletters and other communications. Create a profile and then select the subscriptions that
you would like to receive. To visit the Cisco Online Subscription Center, go to this URL:
http://www.cisco.com/offer/subscribe
• The Cisco Product Quick Reference Guide is a handy, compact reference tool that includes brief
product overviews, key features, sample part numbers, and abbreviated technical specifications for
many Cisco products that are sold through channel partners. It is updated twice a year and includes
the latest Cisco channel product offerings. To order and find out more about the Cisco Product Quick
Reference Guide, go to this URL:
http://www.cisco.com/go/guide
• Cisco Marketplace provides a variety of Cisco books, reference guides, documentation, and logo
merchandise. Visit Cisco Marketplace, the company store, at this URL:
http://www.cisco.com/go/marketplace/
• Cisco Press publishes a wide range of general networking, training, and certification titles. Both new
and experienced users will benefit from these publications. For current Cisco Press titles and other
information, go to Cisco Press at this URL:
http://www.ciscopress.com
• Internet Protocol Journal is a quarterly journal published by Cisco for engineering professionals
involved in designing, developing, and operating public and private internets and intranets. You can
access the Internet Protocol Journal at this URL:
http://www.cisco.com/ipj
• Networking products offered by Cisco, as well as customer support services, can be obtained at
this URL:
http://www.cisco.com/en/US/products/index.html
• Networking Professionals Connection is an interactive website where networking professionals
share questions, suggestions, and information about networking products and technologies with
Cisco experts and other networking professionals. Join a discussion at this URL:
http://www.cisco.com/discuss/networking

Cisco VoiceXML Programmer’s Guide

OL-11175-01 xv
 Preface
Obtaining Additional Publications and Information

• “What’s New in Cisco Documentation” is an online publication that provides information about the
latest documentation releases for Cisco products. Updated monthly, this online publication is
organized by product category to direct you quickly to the documentation for your products. You
can view the latest release of “What’s New in Cisco Documentation” at this URL:
http://www.cisco.com/univercd/cc/td/doc/abtunicd/136957.htm
• World-class networking training is available from Cisco. You can view current offerings at
this URL:
http://www.cisco.com/en/US/learning/index.html

Cisco VoiceXML Programmer’s Guide

xvi OL-11175-01
 CH A P T E R 1
Cisco VoiceXML Features

Revised: October 2, 2009, OL-11175-01

This 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:
• Audience, page 1-1
• Recommended Knowledge, page 1-2
• Prerequisites, page 1-2
• Overview of Cisco VoiceXML Features, page 1-3
• System Output, page 1-8
• User Input, page 1-22
• Control Flow and Scripting, page 1-43
• Environment and Resources, page 1-53
• Call Handoff, page 1-57
• Authentication and Authorization, page 1-60
• GTD Manipulation, Cisco IOS Release 12.2(11)T, page 1-72
• GTD Manipulation, Cisco IOS Release 12.3, page 1-99
• Hybrid Applications, page 1-114
• Limitations and Restrictions, page 1-117
• Additional References, page 1-118

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:
• Cisco IOS Tcl and VoiceXML Application Guide for your Cisco IOS release
• Tcl IVR Version 2.0 Programmer’s Guide
• VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005)

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-1
 Chapter 1 Cisco VoiceXML Features
Recommended Knowledge

Note Cisco IOS Release 12.4(11)T is based on the W3C VoiceXML Version 2.0 Specification, (W3C
Recommendation 16 March 2004). Cisco IOS Release 12.4(15)T adds support for Media Resource
Control Protocol version 2 (MRCP v2) servers and VoiceXML 2.1 W3C Candidate Recommendation
(June 13, 2005).

Recommended Knowledge
We recommend you have the following knowledge before using this guide:
• For setting up the VoiceXML application environment:
– Knowledge of VoiceXML
– Experience with web application administration
– Knowledge of languages and protocols such as HTML and HTTP
• For working with VoiceXML applications and writing VoiceXML documents:
– Knowledge of web page development
– Familiarity with the VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005)
– Knowledge of VoiceXML
• For configuring the Cisco VoiceXML-enabled gateway:
– Experience with the prerequisite configuration of the Cisco voice gateway
– Familiarity with Cisco IVR and VoIP functionality

Prerequisites
This section describes the prerequisites necessary to develop a VoiceXML application using
Cisco VoiceXML features:
• VoiceXML Document Development, page 1-2
• Cisco Voice Gateway Requirements, page 1-3

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.

Cisco VoiceXML Programmer’s Guide

1-2 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Overview of Cisco VoiceXML Features

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 Place all VoiceXML documents behind a firewall.

For more information, see the following resources:

• VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005)
• World Wide Web Consortium’s Voice Browser Activities
• Media Resource Control Protocol version 2 (MRCP v2) (draft-ietf-speechsc-mrcpv2-10) (June 9,
2006)

Note Cisco VoiceXML features in Cisco IOS Release 12.2(11)T through 12.4(11)T releases are based on
the VoiceXML Version 2.0 W3C Recommendation (March 16, 2004).

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:
• Nuance Communications
• Loquendo S.p.A. ASR and TTS products

Note The Cisco IOS VoiceXML gateway using MRCP v2 was qualified with
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.
• Voice Store and Forward Feature, page 1-5
• Volume and Rate Control Feature, page 1-6
• ASR and TTS Features, page 1-6
• Tcl IVR 2.0 and VoiceXML Integration (Hybrid Applications) Feature, page 1-7
• T.37 Store and Forward Fax Detection Feature, page 1-7

Note In Cisco IOS Release 12.4(15)T and later releases, VoiceXML 1.0 is not supported.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-3
 Chapter 1 Cisco VoiceXML Features
Overview of Cisco VoiceXML Features

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

MRCP v1 server
HTTP server
MRCP v2 server
SMTP server

IP
PSTN network TFTP server
V
VoiceXML-enabled
Cisco gateway

PSTN

170485
IP V
Cisco voice gateway
RTSP server

The following is an example of a call flow for a VoiceXML application:

Note In Cisco IOS Release 12.3, the recording feature is supported only on the Cisco AS5350XM and
Cisco AS5400XM.

1. The caller dials a number and is connected through the PSTN or the IP network to a Cisco voice
gateway that is configured as a VoiceXML-enabled gateway.
For instance, the caller could be connected to a business providing sport scores over the telephone.
2. The Cisco voice gateway uses the caller’s DNIS information and associates it with the appropriate
VoiceXML document, residing on a web server (for example, an HTTP server).
For example, this business uses a VoiceXML document on an HTTP server to provide baseball game
scores.
3. The voice gateway runs the VoiceXML document and responds to the caller’s input by playing the
appropriate audio content.

Cisco VoiceXML Programmer’s Guide

1-4 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Overview of Cisco VoiceXML Features

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. Cisco IOS VoiceXML could also transfer the caller to another party, perhaps customer service.
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. The caller dials a number and is connected through the PSTN or the IP network to a Cisco voice
gateway that is configured as a VoiceXML-enabled gateway.
2. The Cisco voice gateway uses the caller’s DNIS information and associates it with the appropriate
VoiceXML document, residing on a web server.
3. The voice gateway runs the VoiceXML document and responds to the caller’s input by playing the
appropriate prerecorded audio files.
4. The gateway executes the document, which prompts the user to record a voice message.
5. The message is recorded by the gateway and stored in local memory with the selected audio
encoding.
6. After the recording is completed, the user can review the message or submit it by either pressing a
specified key or hanging up the call.
7. When the user submits the voice mail message, the gateway's VoiceXML browser submits the voice
message in .au or .wav file format to a specified URL using the HTTP POST method.
8. After receiving the message, the web server stores the message in the appropriate mailbox.
9. After successfully storing the voice message, the application instructs the media stream process to
delete the local copy of the voice message.

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:
• Local memory—Intended for storing short-length speech clips, such as caller name or address, or a
short voice message. Recordings can be submitted to HTTP server using POST method.
• RTSP—Intended for storing indefinite-length audio recordings. Voice recording is directly streamed
to an external RTSP server using the recording URL specified by the user.
• HTTP—Recording is done by directly sending voice data to an HTTP server.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-5
 Chapter 1 Cisco VoiceXML Features
Overview of Cisco VoiceXML Features

• SMTP—Recording is done by directly sending voice recordings to the SMTP server as e-mail audio
attachments. This option supports the Mailto: URL.
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:
• On-ramp mode—Incoming calls are handled by a VoiceXML document that lets callers record voice
messages if the destination is busy or there is no answer. The on-ramp gateway saves all voice
recordings as audio clip files to internal memory if space is available, or onto an external HTTP or
RTSP server, or by directly streaming the voice message as an e-mail enclosure to an external
ESMTP server. The audio clips are then converted into outbound ESMTP e-mail messages.
• Off-ramp mode—The external mail server sends an e-mail notification to the off-ramp gateway. The
off-ramp gateway matches the DNIS in the e-mail header to a MMOIP dial peer, and places the call
to the PSTN or IP phone user. When the call is answered, the gateway executes the VoiceXML
application. The VoiceXML application is responsible for delivering the audio clip from the external
media server to the outbound PSTN or IP destination using media play functions. The gateway does
not support streaming the audio clip directly from the SMTP server.

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 on page 1-16 for details.

Note This feature is a nonstandard extension to VoiceXML and is subject to nonbackward compatible changes
in future versions.

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.

Cisco VoiceXML Programmer’s Guide

1-6 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Overview of Cisco VoiceXML Features

Note The Cisco IOS VoiceXML gateway using MRCP v2 was qualified with
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

ASR/TTS
VoiceXML
MRCP v2 server
MRCP v2/SIP audio

HTTP server
IP
PSTN network
V MRCP v1/RTSP
VoiceXML-enabled ASR/TTS server
Cisco gateway

170486
IP

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 Programmer’s Guide

OL-11175-01 1-7
 Chapter 1 Cisco VoiceXML Features
System Output

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

SMTP
mail server

MMoIP

POTS VoIP
PSTN IP network
V
Cisco voice gateway

555-0144 555-0122 PSTN

V
Cisco voice gateway

62180
Note In Cisco IOS Release 12.3, fax detection is supported only on the Cisco AS5350XM and
Cisco AS5400XM.

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:
• Inbound POTS dial peer, for incoming calls from the PSTN
• Outbound MMoIP dial peer for store-and-forward fax, to send fax transmissions to an e-mail server
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:
• Audio Playout, page 1-9
Describes the playout methods for audio prompts and the types of audio file formats and codecs
supported for a Cisco VoiceXML application.

Cisco VoiceXML Programmer’s Guide

1-8 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
System Output

• Volume and Rate Control, page 1-16

Describes how to control the volume and rate of audio playout.
• Type-ahead Support, page 1-20
Describes how a type-ahead buffer works in a VoiceXML application.

Audio Playout
Cisco VoiceXML supports the following types of prompts:
• Prerecorded Audio Playout
• Synthesized Audio Playout

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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-9
 Chapter 1 Cisco VoiceXML Features
System Output

Note In Cisco IOS Release 12.4(11)T and later releases, if the <audio> element is under the <prompt> tag and
if the <prompt> tag specifies a base URL, then the relative URL in the src attribute of the <audio>
element will use the base attribute of the <prompt> tag to form a complete URI.

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 not hear an audio playout if you load all the audio files into a single <prompt>. For best results,
separate the audio files into multiple <prompt> tags. The number of audio files in a single <prompt> tag
depends on the number of audio files and their individual sizes.
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"/>

Cisco VoiceXML Programmer’s Guide

1-10 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
System Output

</prompt>

The playback will be:

“You have <silence...> 3 <silence...> emails”, which is inappropriate.

Tip Use multiple sources in a single <prompt> tag only for concatenated prompts. For different codec types,
embed each audio file within a single <prompt> for successful playout.

Note In Cisco IOS Release 12.4(11)T and later releases, no error event will be thrown if the audio file cannot
be loaded or played if you enter the vxml version 2.0 command.

Dynamic Prompts Playout

Note In Cisco IOS Release 12.4(11)T and later releases, only the xml:lang attribute of the <prompt> element
in a VoiceXML document can be set to select a specifc language.

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 on page 1-13.

Text-to-Speech Prompts

A third-party external media server is required to play TTS prompts. Playout of TTS prompts is
dependent on the languages supported on the external media server. A speech synthesis markup language
(SSML) is used to allow the development of synthetic speech in web applications. SSML allows
VoiceXML document writers to control aspects of speech output, such as emphasis, pitch, and volume.
The media server receives the speech synthesis markup specified in the VoiceXML document, converts

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-11
 Chapter 1 Cisco VoiceXML Features
System Output

it to audio, and streams it to the user through the Cisco voice gateway. SSML support is dependent on
the media server. For example, the media server may not be able to support some audio URIs such as
TFTP, RTSP, and flash.
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:

• The media server is required to support HTTP clients only. This requirement imposes a limitation
on the data contained in a <prompt> element.
• If the <prompt> element contains a W3C speech markup, then the entire markup in that <prompt>
element uses an external media server for a TTS operation, and, a single G.711 u-law codec for the
entire audio stream. This <prompt> element can only contain an HTTP type URI. The codec of the
audio stream is limited to G.711 u-law because the media server cannot switch codecs.
• If the <prompt> element contains <audio src> elements instead of a W3C speech markup, these
<audio src> elements can contain individual Flash, TFTP, FTP, and RTSP URIs, or a mix of any of
them. These URIs are played using streaming mechanisms available on Cisco voice gateways. The
audio files can have different codecs and the system plays them out in sequence subject to the
following limitations:
– The digital signal processor (DSP) supports the specified codecs on the telephony side.
– On the IP side, interactive voice response supports the specified codecs. See the Cisco IOS Tcl
IVR and VoiceXML Application Guide for your Cisco IOS release for details.

Cisco VoiceXML Programmer’s Guide

1-12 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
System Output

• A URI in the <audio src> element can point to a block of speech markup data, but such support is
dependent on, and conditional to the vendor’s decision of where the <audio src> element can point.

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 In Cisco IOS Release 12.4(11)T and later releases, the error.noresource event is thrown if an external
ASR or TTS server fails to operate. The old event com.cisco.media.resource.unavailable is supported for
backward compatibility.

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.vxml
This 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 the
execution 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"/>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-13
 Chapter 1 Cisco VoiceXML Features
System Output

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

Cisco VoiceXML Programmer’s Guide

1-14 OL-11175-01
Chapter 1 Cisco VoiceXML Features
System Output

<!-- 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">
<?php
if($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\"/>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-15
 Chapter 1 Cisco VoiceXML Features
System Output

<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

Cisco VoiceXML Programmer’s Guide

1-16 OL-11175-01
Chapter 1 Cisco VoiceXML Features
System Output

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 Appendix B, “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 on page 1-25.

Note Rate control is not supported for prompts containing TTS or RTSP audio files.

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:
• For the Cisco AS5300, the step values range from -14 to +16 dB, where each step represents 1dB.
• For the Cisco AS5350 and the Cisco AS5400, the step values range from -14 to 14 dB, where each
step represents 1 dB.
• For the Cisco AS5350XM and the Cisco AS5400XM, the step values range from -14 to 14 dB, where
each step represents 1 dB.
• N or + N indicates an increase in volume by N steps.
• -N indicates a decrease in volume by N steps.
• 0 indicates a reset to the configured normal (default) volume.

Note • If you specify a step value that is out of range, the value chosen will be the maximum or minimum
volume within the allowed range, depending on the value specified by you.
• Characters, expressions, and variables are not allowed for a step value.
• Volume control is not supported on the Cisco 3660 router.

• The step value is relative to the default volume configured for the applicable port. The volume for a
port is configured as output attenuation using the output attenuation command. To configure
output attenuation, see the Cisco IOS Voice Configuration Library and Cisco IOS Voice Command
Reference for details.
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" >

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-17
 Chapter 1 Cisco VoiceXML Features
System Output

<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:
• Range of step value is from -4 to +4.
• N or + N indicates fast-forward by N steps.
• -N indicates a slowdown by N steps.
• 0 indicates a reset to normal (default) speed.

Note • If you specify a step value that is out of range, the value chosen will be the maximum or minimum
speed within the allowed range, depending on the value specified by you. For example, if you
specify the value +6, the value chosen will be +4. If you specify the value -5, the value chosen will
be -4.
• Characters, expressions, and variables are not allowed for a step value.

Table 1-1 indicates step values for rate control.

Table 1-1 Step Values for Rate Control

Step Values for Rate Control Description

Rate = 1 6 packets sent
1 packet dropped
Rate = 2 4 packets sent
1 packet dropped
Rate = 3 3 packets sent
1 packet dropped

Cisco VoiceXML Programmer’s Guide

1-18 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
System Output

Table 1-1 Step Values for Rate Control (continued)

Step Values for Rate Control Description

Rate = 4 Fastest rate
2 packets sent
1 packet dropped
Rate = -1 6 packets sent
1 packet duplicated
Rate = -2 4 packets sent
1 packet duplicated
Rate = -3 3 packets sent
1 packet duplicated
Rate = -4 Slowest rate
2 packets sent
1 packet duplicated

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 on page 1-48.
Information on timing for the last prompt is set to the application.com.cisco.lastprompt$ variable when:
• The correct input is collected,
or
• A nomatch event is thrown,
or
• A noinput event is thrown,
or
• Media play fails.

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.

• The lastprompt$ variable resets to “undefined” and does not target prompt B, if <goto> transitions
to a different application.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-19
 Chapter 1 Cisco VoiceXML Features
System Output

• The lastprompt$ variable targets prompt B, if <goto> transitions to the same application with a new
VoiceXML document in the same application, and if no prompts are available for input collection
for the new VoiceXML document.
• The lastprompt$ variable does not target prompt B if <goto> transitions to the same application, and
prompts are available for input collection for the next VoiceXML document within the application.
<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.

Cisco VoiceXML Programmer’s Guide

1-20 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
System Output

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 on page 1-9 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>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-21
 Chapter 1 Cisco VoiceXML Features
User Input

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 The regex grammar used for DTMF input is a Cisco grammar and is not supported by vendors on their
media servers.

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 If you use the external media server and a Cisco voice gateway to collect input in the same application,
the VoiceXML interpreter throws an error.badfetch event.

Cisco VoiceXML Programmer’s Guide

1-22 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
User Input

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 If you use both grammars in the same application, the VoiceXML interpreter throws an error.badfetch
event.

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:
• The external media server only supports HTTP clients. Because of this restriction, the src attribute
only contains an HTTP URI for referencing external grammar.
• TFTP, FTP, flash, or other types of URI are not supported.
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:
• It supports inline grammar only.
• It cannot be used as a form grammar.
• It cannot be given a document scope when used as a menu grammar.
Cisco DTMF grammar supports the following metacharacters:

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-23
 Chapter 1 Cisco VoiceXML Features
User Input

Metacharacter Description

. Matches any single character.

For example, Cisco DTMF grammar with a regular expression <grammar
type= “application/grammar+regex”>1408.......</grammar> matches a seven digit
phone number with the leading area code 1408.

\ The quoting character. It removes any special meaning from the following character
and treats it as an ordinary character.
For example, <grammar type= “application/grammar+regex”>\*</grammar>
matches a literal asterisk (star) key, not the asterisk repetition operator.

Repetition Operators

? Matches zero or one occurrence of the character or regular expression immediately

preceding.
For example, <grammar type= “application/grammar+regex”>408?</grammar>
matches 40, 4088, 40888, 408123, 4083456. The match occurs for 408, 4088, 40888
and also for 408 followed by other extra digits that occur after 408.

+ Matches one or more occurrences of the character or regular expression immediately

preceding.
For example, <grammar type= “application/grammar+regex”>408+</grammar>
matches 408, 4088, 40888, 408123, 408883456. The match occurs not only for 408,
4088, 40888 but also for 408 followed by other extra digits that occur after 408.

* Matches zero or more occurrences of the character immediately preceding.

For example, <grammar type= “application/grammar+regex”>408*</grammar>
matches 40, 4088, 40888, 408123, 4083456. The match occurs not only for 408, 4088,
40888 but also for 408 followed by other extra digits that occur after 408.

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:
• To join \* and .+ use an empty space instead of the operator |. See the following example:
<grammar type= “application/grammar+regex”>\* .+</grammar>
The <field> builtin types digits and number accept any nondigit input. A nomatch event is not generated.

Cisco VoiceXML Programmer’s Guide

1-24 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
User Input

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
Appendix B, “Cisco VoiceXML Elements: Reference Table” and the “Volume and Rate Control” section
on page 1-16. In-line DTMF grammar is used. External and ASR grammar is not supported.

Note The dtmf attribute of <cisco-vcrcontrol> does not take a regular expression. It takes only a single digit.

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. Grammar for the form item
2. Grammar for the form
3. Grammar for the document
4. Grammar for the root document
The grammar closest to the applicable item is activated.
Some dependencies for the scope of volume and rate control grammar are:
• Volume and rate control grammars for a form item are always scoped to its form item.
• Volume and rate control grammars for form are assigned a dialog scope by default. This enables the
grammars to be active only when the user is in the form.
• Volume and rate control grammars assigned to a document scope are active when the user is in the
document and in the applicable leaf documents.
• Volume and rate control grammars for menu are assigned a dialog scope by default, and are active
only when the user is in the document and in the applicable leaf documents.
• For prompts in the event handler, the scope of the original event applies to volume and rate control
grammar.
• For prompts in the <filled> element:
– The scope of the field item applies to volume and rate control grammar if the <filled> element
is inside a field item.
– The scope of the form applies to volume and rate control grammar if the <filled> element is
inside a form.

Recording Support
This section contains the following information about recording support:
• Using cisco-dest, page 1-26
• Shadow Variables, page 1-28
• RAM Recording, page 1-28
• Exception Handling, page 1-29

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-25
 Chapter 1 Cisco VoiceXML Features
User Input

• Properties for <record>, page 1-30

• Typical Call Flow Using Recording, page 1-31
For recording, the following four recording destinations are supported:
• HTTP
• RAM
• RTSP
• SMTP
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 In Cisco IOS Release 12.4(11)T and later releases, use the <audio> element to play back the recorded
input. The <value> element is supported for backward compatibility.

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 In Cisco IOS Release 12.3, a VoiceXML application can submit a RAM recording to an HTTP server
using the POST method with an enctype of “audiobasic.” Later releases of Cisco IOS software, however,
only support the “multipart/form-data” type for <submit>. A VoiceXML document written to support the
“audiobasic” MIME type for <submit> in Cisco IOS Release 12.3 is not supported in later releases.

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: <record cisco-dest = “http://”>
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>.
• RTSP recording: <record cisco-dest = “rtsp://”>
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, page 1-28).
• SMTP recording: <record cisco-dest = “mailto://”>

Cisco VoiceXML Programmer’s Guide

1-26 OL-11175-01
Chapter 1 Cisco VoiceXML Features
User Input

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:
• The user presses any DTMF key, or
• Final silence is detected, or
• There is a match in record grammar, or
• The maximum recording time or size is reached.
Table 1-2 gives information on Cisco-specific applications of the attributes for <record>:
Table 1-2 <record> Attributes

Attribute Use
name Variable name of RAM recording.
beep Not supported.
Note In Cisco IOS Release 12.4(15)T and later releases, the beep attribute is
supported if the vxml version 2.0 command is entered. There is no codec
limitation on the PSTN call leg. The G.711 u-law, G.711 a-law, G.729r8,
G.723r53, and G.723r63 codecs only are supported on the VoIP call leg.
maxtime Maximum time in seconds for recording duration. The recording is cut to maxtime
if it exceeds the maxtime specified. If this attribute is missing, the default is
30 seconds.
finalsilence Allows a gateway to terminate a recording after a defined length of silence. The
gateway waits for a few seconds before terminating the recording. The final
silence feature is disabled by default. It is also disabled for a value of zero. Final
silence is enabled by using the finalsilence attribute. Final silence is not supported
for RTSP recording.
Note Voice activation detection (VAD) must be enabled on the VoIP dial peer
when final silence detection is needed to terminate a voice recording. See
the Cisco IOS Tcl and VoiceXML Application Guide for details.
type MIME type of recording which describes the audio file format and codec type.
Codec type is specified as a parameter in name=value format based on RFC1341
“Content-Type.” File format only supports audio/basic. If this attribute is missing,
the default is “audio/basic; codec=G.711ulaw”.
Note In Cisco IOS Release 12.4(11)T and later releases, the supported file
formats are audio/basic, audio/x-alaw-basic, and audio/x-wav.
dtmfterm “true” or “false”; if true, detection of any DTMF key terminates the recording. If
this attribute is missing, the default value is “true.”
cisco-dest Recording URL: HTTP, RTSP, SMTP or “mailto.” If missing, the default is RAM.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-27
 Chapter 1 Cisco VoiceXML Features
User Input

Table 1-2 <record> Attributes (continued)

Attribute Use
cisco-codec Codec type of recording. If this attribute is missing, the default is “G.711 ulaw.”
cisco-recordbeep “true” or “false”. When the value is set to “true,” a beep sound is sent back to the
user every x seconds during recording. The number of seconds between beeps is
specified in the cisco-recordbeepinterval attribute.
Note In Cisco IOS Release 12.4(15)T and later releases, all codecs are
supported on the PSTN call leg. The G.711 u-law, G.711 a-law, G.729r8,
G.723r53, and G.723r63 codecs only are supported on the VoIP call leg.
cisco-recordbeepi Time in seconds to specify the interval between beeps for the cisco-recordbeep
nterval attribute. The default value is 3 seconds; the minimum value is 2 seconds. If a
value smaller than the minimum is specified, it will be changed to the minimum
value.
Note This attribute is supported in Cisco IOS Release 12.4(15)T and later
releases.

Shadow Variables
Standard shadow variables from VoiceXML 2.1 are supported, including the following:
• name$.duration: Duration of the recording in milliseconds
• name$.size: Size of the recording in bytes
• name$.termchar: If dtmfterm is true, this shadow variable holds the pressed key.
• name$.maxtime: Boolean which is true if the recording was terminated because the maxtime
duration was reached
• name$.recording: Reference to the recording, or undefined if no audio is collected
• name$.recordingsize: Size of the recording in bytes, or undefined if no audio is collected
• name$.recordingduration: Duration of the recording in milliseconds, or undefined if no audio is
collected.

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 In versions earlier than VoiceXML 2.0, RAM recording can be played using <prompt> and <value
expr=“nnn”/> only. In VoiceXML 2.0 and later versions, use <prompt> and <audio expr=“nnn”/> to play
RAM recordings.

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>

Cisco VoiceXML Programmer’s Guide

1-28 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
User Input

</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:
• error.badfetch.rtsp.nnn
This event is thrown when a RTSP server communication error is generated; nnn is the
corresponding protocol error code.
• error.unsupported.format
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-29
 Chapter 1 Cisco VoiceXML Features
User Input

Note In Cisco IOS Release 12.4(11)T and later releases, the following error events are supported:
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
on page 1-55 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:
• com.cisco.mta.send.mdn_request
Setting com.cisco.mta.send.mdn_request to TRUE sends the MDN request.
• com.cisco.mta.send.mdn_hostname and com.cisco.mta.send.mdn_username
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:
• com.cisco.mta.send.dsn_delay
• com.cisco.mta.send.dsn_success
• com.cisco.mta.send.dsn_failure
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:
• com.cisco.mta.send.from_username
• com.cisco.mta.send.from_hostname
• com.cisco.mta.send.server
• com.cisco.mta.send.origin_prefix

Note • The properties used to specify MDN and DSN have equivalent Cisco IOS commands. If the specific
Cisco VoiceXML properties and their equivalent Cisco IOS commands are specified simultaneously,
the VoiceXML properties take precedence over the CLI.
• For MDN, the username and the hostname must be specified to form a valid e-mail address.
• The scope of each property conforms to the VoiceXML Version 2.0. Each property can be defined
at the application root document level, document <vxml> level, dialog<form> or <menu> level, or
the form item <record> level.

Cisco VoiceXML Programmer’s Guide

1-30 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
User Input

Typical Call Flow Using Recording

The following call flow illustrates recording:
1. The voice gateway receives a setup indication and hands the call to a generic VoiceXML document.
2. The generic VoiceXML document requests a customized VoiceXML document from the VoiceXML
server based on incoming call information (ANI, DNSI, RDN, and so on).
3. The VoiceXML server creates a customized VoiceXML document based on the call information
provided a nd sends it to the gateway.
4. The gateway executes the document, which prompts the user to record a voice message.
5. The gateway records the message and stores it in local RAM with G.723.1 and G.711 u-law
encoding.
6. When recording is complete, the user is prompted to review the message, or to submit the message
to the VoiceXML server. It is also possible that the user can simply hang up.
7. When the user submits the voice mail message, the gateway’s VoiceXML browser submits the voice
message as an .au file to a specified URL using the HTTP POST method.
The VoiceXML application must be able to handle the case the user hanging up before choosing to
submit the voice message.
8. When the VoiceXML server receives the message, it stores the message in the appropriate mailbox.
9. When the voice message is successfully stored, the application instructs the media stream process
to delete the local copy of the voice message.
10. The VoiceXML document disconnects the call.

<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:
• Busy tone,
or
• No response from the called party,
or if the call disconnects because of:
• Connection hangup,
or
• Maxtime limitation.
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-31
 Chapter 1 Cisco VoiceXML Features
User Input

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 • Headers from HTTP responses are not available to a VoiceXML script.
• The <cisco-data> element supports only text messages. It fetches strings from a server and does not
handle binary data. If binary or null data is encountered in a response, the information returned to
the VoiceXML interpreter is truncated. For example, “My data is <binary data> received on
Tuesday” is truncated to “My data is.”
• Data received is truncated if it exceeds 20 KB.

The attributes of <cisco-data> are:

• src
The URI specifying the location of data.
• name
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.
• expr
The URI specifying the location of the data. The URI is dynamically determined.
• method
Similar to the method attribute of the <submit> element in the VoiceXML 2.0 specification.
• namelist
Similar to the namelist attribute of the <submit> element in the VoiceXML 2.0 specification.
• enctype
Similar to the enctype attribute of the <submit> element in the VoiceXML 2.0 specification.
• fetchhint
Similar to the fetchhint attribute of the <submit> element in the VoiceXML 2.0 specification.
• fetchtimeout
Similar to the fetchtimeout attribute of the <submit> element in the VoiceXML 2.0 specification.
• fetchaudio
Similar to the fetchaudio attribute of the <submit> element in the VoiceXML 2.0 specification.
• maxage
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.

Cisco VoiceXML Programmer’s Guide

1-32 OL-11175-01
Chapter 1 Cisco VoiceXML Features
User Input

• maxstale
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-data
src %uri #IMPLIED
name NMTOKEN #IMPLIED
expr %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:
• Variables a and b are assigned values. The variables and values are sent as avpairs in the body of the
HTTP message.
• The HTTP server that receives the data sent to it is identified by the src attribute.
• The namelist attribute identifies the list of variables that are sent to the HTTP server.
• The HTTP method is the POST method.
• The received data is the body of the message received in the response from the server, and is stored
in the MyData variable.
• The HTTP server does not support multipart data. In the <cisco-data> element, the data assigned to
the variable name can be submitted back to the server for processing. However, Cisco IOS release
12.3T only supports the “multipart/form-data” type for <submit>. The enctype must be enctype=
“multipart/form-data” if <cisco-data> is to be submitted back to the server.
<vxml version="2.0">
<form>
<var name="a" expr="123"/>
<var name="b" expr="456"/>
<block>
<cisco-data
src="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>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-33
 Chapter 1 Cisco VoiceXML Features
User Input

Transfer Support

Note In Cisco IOS Release 12.4(11)T and later releases, if the vxml version 2.0 command is entered, the
behavior of blind transfer conforms with VoiceXML 2.0 specifications and does not behave like
consultation transfer.

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 If an invalid number is used for a transfer element, the interpreter throws an
error.connection.baddestination event.

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 In releases earlier than Cisco IOS Release 12.4(15)T, any <grammar> inside a <transfer> element is
ignored.

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:
• You need to identify the different calls that were made when reconciling your billing records,
or
• If two back-to-back calls are made to the same terminating gateway. In this case, if the same GUID
is used for two back-to-back calls, and if the terminating gateway receives a request for setting up
the second call before it finishes tearing down the first call, the duplicate GUID causes the
terminating gateway to reject the second call.
The cisco-newguid attribute resolves to a boolean value with a default value of false.

Cisco VoiceXML Programmer’s Guide

1-34 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
User Input

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 Only a blind transfer and setting the bridge attribute to false (bridge=”FALSE'') allows the VoiceXML
document to send the fax through T.37 Store and Forward.

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:
• DNIS
• RDNIS
• A combination of DNIS and RDNIS
• A number generated during the session (for example, dtmf entry) for direct calling by the document.
• A string that represents a valid e-mail address.
The VoiceXML document defines an e-mail address through the cisco-mailtoaddress variable in the
<transfer> element.

Note Make sure that you do not pass @domain again in the cisco-mailtoaddress attribute in the VoiceXML
script if it is already configured in sessiontarget mailto in MMoIP dial peer.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-35
 Chapter 1 Cisco VoiceXML Features
User Input

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:
• user@domain.com
• user
• 1234@domain.com (where 1234 is DNIS)
• 5678@domain.com (where 5678 is RDNIS)
• 12345678@domain.com (where 12345678 is DNIS+RDNIS)
• user1!domain1@domain2.com
• FAX= 12345678@domain.com (T.33 subaddressing strings are also accepted.)

Note If $e$ is not specified in the session target mailto command, and the cisco-mailtoaddress attribute is
specified in the transfer element of the fax detection document, then whatever is specified in the MMoIP
dial peer takes precedence; the cisco-mailtoaddress attribute is ignored.

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

Cisco VoiceXML Programmer’s Guide

1-36 OL-11175-01
Chapter 1 Cisco VoiceXML Features
User Input

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-37
 Chapter 1 Cisco VoiceXML Features
User Input

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

Table 1-3 Cisco Telephony Attributes for <transfer>

Cisco Attribute Description

cisco-username RADIUS username. It can have a maximum string
length of 32 characters. Longer strings are
truncated. If cisco-username is missing, the
calling number attribute is used.
cisco-ani Calling (caller’s) number. The telephone number
format is tel: <E.164 number>, where <E.164
number> can have a maximum string length of 32
digits. For example:
cisco-ani= “tel: 5550134”
cisco-aniexpr Calling number with subfield expr.
cisco-anitype Calling number with subfield type.
cisco-aniplan Calling number with subfield plan.
cisco-anipi Calling number with subfield pi.
cisco-anisi Calling number with subfield si.
cisco-carrierid-source The source carrier ID for an outgoing call.
cisco-carrierid-target The target carrier ID for an outgoing call.
cisco-desttype Called number with subfield type.
cisco-destplan Called number with subfield plan.
cisco-rdn Redirecting number. The telephone number
format is: “tel: <E.164 number>”. The <E.164
number> can have a maximum string length of 32
digits. For example:
cisco-ani= “tel: 5550134”
cisco-rdnexpr Redirecting number with subfield expr
cisco-rdntype Redirecting number with subfield type
cisco-rdnplan Redirecting number with subfield plan
cisco-rdnpi Redirecting number with subfield pi
cisco-rdnsi Redirecting number with subfield si

Cisco VoiceXML Programmer’s Guide

1-38 OL-11175-01
Chapter 1 Cisco VoiceXML Features
User Input

Table 1-3 Cisco Telephony Attributes for <transfer> (continued)

Cisco Attribute Description

cisco-redirectreason Reason for call redirection
cisco-mailtoaddress Destination e-mail ID
long-# Cisco Longpound Attribute

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.

Table 1-4 Cisco <transfer> Attributes Mapped to VoiceXML Session Variables

Cisco Attribute VoiceXML Session Variable

cisco-ani session.telephone.ani
cisco-aniexpr session.telephone.ani
cisco-rdn session.telephone.rdnis
cisco-rdnexpr session.telephone.rdnis
cisco-redirectreason session.telephone.redirect_reason
cisco-anitype com.cisco.ani_noa
cisco-aniplan com.cisco.ani_npi
cisco-anipi com.cisco.ani_pi
cisco-anisi com.cisco.ani_pi
cisco-rdntype com.cisco.rgn_noa
cisco-rdnplan com.cisco.rgn_npi
cisco-rdnpi com.cisco.rgn_pi
cisco-rdnsi com.cisco.rgn_si
cisco-desttype com.cisco.dnis_noa
cisco-destplan com.cisco.dnis_npi

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 VoiceXML Programmer’s Guide

OL-11175-01 1-39
 Chapter 1 Cisco VoiceXML Features
User Input

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 and
mycall$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 • Subfields must be present with their associated Q.931 information element (IE). If the subfields
are present without their associated IE, an error event error.semantic is thrown.
• IE subfields do not propogate from the originating to the terminating gateway for calls over SIP.
• IEs and their subfields do not propogate over CAS because of limitations in R2 signaling.

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

Cisco VoiceXML Programmer’s Guide

1-40 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
User Input

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
Field values 0 = Unknown
1 = Call forwarding busy or call DTE busy
2 = Call forwarding no reply
4 = Call deflection
9 = Called DTE out of order
10 = Call forwarding by the called DTE
15 = Call forwarding unconditional or systematic redirection

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:
• cisco-ani represents any one attribute of the cisco-ani and cisco-aniexpr attribute pair. Only one of
the two attributes can be present at a time.
• cisco-rdn represents any one attribute of the cisco-rdn and cisco-rdnexpr attribute pair. Only one of
the two attributes can be present at a time.

RADIUS Username
If the RADIUS username is present, use its value cisco-username. If it is not present, use cisco-ani.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-41
 Chapter 1 Cisco VoiceXML Features
User Input

Calling Number

If the calling number is present, use these values: The resultant values are:
cisco-ani with subfields • cisco-ani with subfields.
• cisco-anipi and cisco-anisi as a pair1.
cisco-ani without subfields cisco-ani
subfield = incoming leg
subfields 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

If the called number is present, use these values: The resultant values are:
dest with subfields dest with subfields
dest without subfields dest subfields = incoming leg
None Call is not transferred.

Redirecting Number

If the redirecting number is present, use these

values: The resultant values are:
cisco-rdn with subfields • cisco-rdn with subfields.
• cisco-rdntype and cisco-rdnplan as a pair.1
• cisco-rdnpi and cisco-rdnsi as a pair with
cisco-rdntype and cisco-rdnplan.2
cisco-rdn without subfields cisco-rdn
subfield = incoming leg
subfields without cisco-rdn An error event error.semantic is thrown.
None—With RDNIS information in the first call Redirecting number = incoming leg
leg. subfield = incoming leg
None—Without RDNIS information in the first • Redirecting number= incoming leg called
call leg. number.
• cisco-rdntype = cisco-desttype
• cisco-rdnplan = cisco-destplan
• redirectreason = 10 (originating gateway
only)
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.

Cisco VoiceXML Programmer’s Guide

1-42 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

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, page 1-43
• Event Handling, page 1-49
• JavaScript Support, page 1-53

Variables
VoiceXML 2.0 defines a set of standard JavaScript variables under the following groups:
• Supported Session Variables: Available to an entire VoiceXML session
• Application Variables: Available throughout a particular application within a session
• Dialog Variables: Available in a particular dialog within an application
• Event Variables: Available only in event handlers

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.

Table 1-5 Cisco Extended Session Variables

Variable Description
session.telephone.nas_port_id Network universal gateway port number
session.telephone.rdnis Redirect dialed number identification services
session.telephone.redirect_reason Redirect reason
session.handoff_string Handoff string from the previous application
session.mail.to Holds the TO: header of the mail
session.mail.from Holds the FROM: header of the mail
session.mail.subject SUBJECT: header of the mail
session.mail.messageid Message-Id: header of the mail
session.mail.headerinfo All of the remaining SMTP headers, such as reply-to,
if specified
com.cisco.fax.cng CNG detection event

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-43
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

Table 1-5 Cisco Extended Session Variables (continued)

com.cisco.params Used in a hybrid application, it is a session variable of

the form com.cisco.params.xxxx, that is used by the
VoiceXML session to access parameters passed from
the Tcl script to the VoiceXML dialog. A Tcl array
containing these parameters is passed from the calling
Tcl application to the VoiceXML dialog. xxxx is the
index in the array. See the leg vxmldialog verb in the
Tcl IVR Version 2.0 Programmer’s Guide.

Example:
Consider an array called paramarray, containing a
parameter list, in the form of a string of variables,
which is passed by the Tcl script to the VoiceXML
dialog. When the VoiceXML dialog starts execution,
the VoiceXML session can access com.cisco.params
after it is initialized.
• If paramarray contains:
• paramarray(message) = “Hello World”
• paramarray(totalusers) = 4
• paramarray(callingpartyname) =
“ram://callingpartyname”
com.cisco.params is initialized to contain:
• com.cisco.params.message = “Hello World”
• com.cisco.params.totalusers = 4
• com.cisco.params.callingpartyname = (an audio
file object referring to “ram://callingpartyname”)
com.cisco.ani_pi Calling party number presentation indicator
com.cisco.ani_si Calling party number screening indicator
com.cisco.ani_noa Calling party number nature of address
com.cisco.ani_npi Calling party number numbering plan indicator
com.cisco.carrierid.source Defines the source ID for an incoming call.
com.cisco.carrierid.target Defines the target carrier ID for an incoming call.
com.cisco.dnis_noa Called party number nature of address
com.cisco.dnis_npi Called party number numbering plan indicator
com.cisco.carrierid.source Defines the source carrier ID for an incoming call.
com.cisco.carrierid.target Defines the target carrier ID for an incoming call.
session.telephone.com.cisco.handoff.dnis Returns the DNIS that is set by the inbound
application in the <transfer> element (leg setup). The
handoff attribute is always returned to the specific
outbound application that receives the handoff call
from the inbound application.

Cisco VoiceXML Programmer’s Guide

1-44 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

Table 1-5 Cisco Extended Session Variables (continued)

session.telephone.com.cisco.handoff.ani Returns the ANI set by the inbound application in the

<transfer> element (leg setup). The handoff attribute
is always returned to the specific outbound
application that receives the handoff call from the
inbound application.
session.telephone.com.cisco.handoff.argstring Replaces the existing variable
“session.telephone.com.cisco.handoff_string”
session.telephone.com.cisco.handoff.proto_headers Returns the value of the requested header that is
[‘<attribute-name>’] handed off to an outbound application.
session.telephone.com.cisco.callid Contains the call ID of the incoming call leg which
can be reused for later calls. It is displayed in the
output debug message.
Only one call ID value exists for each VoiceXML
document. When a call is connected during a
<transfer> operation, the outbound call leg has a
separate call ID which is not accessible to the
VoiceXML script.
session.telephone.com.cisco.guid Contains the globally unique ID of the call. It is
unique between multiple gateways and is displayed in
the output debug message.
session.connection.protocol.name Identifies the connection protocol used.
session.connection.protocol.version Identifies the version of the connection protocol used.
session.connection.aai Provides application-to-application information
passed during connection setup.
session.connection.redirect This variable is an array representing the connection
redirection paths. The first element is the original
called number, the last element is the last redirected
number. Each element of the array contains a URI, PI
(presentation information), SI (screening
information), and reason property. The reason
property can be:
• unknown
• user busy
• no reply
• deflection during alerting
• deflection immediate response
• mobile subscriber not reachable
session.connection.originator This variable directly references either the local or
remote property.

For more information on signaling protocols applicable to the use of session variables, see the following
documents:
• E.164: Telephone Network and ISDN Operation, Numbering, Routing, and Mobile Service

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-45
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

• Q.931: Digital Subscriber Signaling System No.1 (DSS 1)— ISDN user-network interface layer 3
specification for basic call control
• H.323: Packet based Multimedia Communication Systems
• SIP: Session Initiation Protocol
The session variables have the following values:
The session.telephone.ani_pi values are:
• Presentation allowed
• Presentation restricted
• Number lost because of networking
• Reserved value
The session.telephone.ani_si values are:
• USR provided unscreened
• USR provided screening passed
• USR provided screening failed
• Network provided
The session.telephone.ani_plan values are:
• Unknown
• ISDN telephony E.164
• Data X.121
• Telex F.69
• National
• Private
• Reserved value
The session.telephone.ani_type values are:
• Unknown
• International
• National
• Network specific
• Subscriber
• Abbreviated
• Reserved value
The session.telephone.rdnis_pi values are:
• Presentation allowed
• Presentation restricted
• Number lost because of networking
• Reserved value
The session.telephone.rdnis_si values are:
• USR provided screening passed

Cisco VoiceXML Programmer’s Guide

1-46 OL-11175-01
Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

• USR provided screening failed

• Network provided
The session.telephone.rdnis_type values are:
• Unknown
• International
• National
• Network specific
• Subscriber
• Abbreviated
• Reserved value
The session.telephone.rdnis_plan values are:
• Unknown
• ISDN telephony E.164
• Data X.121
• Telex F.69
• National
• Private
• Reserved value
The session.telephone.dnis_type values are:
• Unknown
• International
• National
• Network specific
• Subscriber
• Abbreviated
• Reserved value
The session.telephone.dnis_plan values are:
• Unknown
• ISDN telephony E.164
• Data X.121
• Telex F.69
• National
• Private
• Reserved value
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:

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-47
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

• FXO—FXO, followed by the port name

• FXS—FXS, followed by the port name
• E&M—ENM, followed by the port name
• ISDN—ISDN, followed by the port name
For example, a value for an ISDN interface is ISDN 7/1:D.
The session.telephone.iidigits values are:
• Unknown
• ISDN telephony E.164
• Data X.121
• Telex F.69
• National
• Private
• Reserved value

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.

Table 1-6 Specific Cisco Application Variables

Variable Description
application.com.cisco.lastprompt$.duration • Playout duration of the last prompt before it is interrupted by a
bargein. It uses the application scoped Cisco specific variable
com.cisco.lastprompt$ to keep the information of the prompt played
last.
• The duration, in milliseconds, is from the start of the entire set of
audio files being played within the <prompt> element.
Note If the prompt is played in its entirety without a bargein, the
duration of playout should be equal to the duration of playout for
the entire prompt.

• For a prompt that contains TTS or RTSP audio files, the duration of
playout is unknown and the value of the variable is -1.
• In Cisco IOS Release 15.0(1)M and later releases, for a prompt that
contains RTSP audio files, the duration of playout is determined by
the value of the cisco-maxtime attribute of the <prompt> element. If
cisco-maxtime is zero or has no value set, the RTSP stream is played
indefinitely.

Cisco VoiceXML Programmer’s Guide

1-48 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

Table 1-6 Specific Cisco Application Variables

Variable Description
application.com.cisco.lastprompt$.lastrate • Playout rate of the last prompt.
• The rate is an absolute value in the range from +4 to -4.
• If rate control is not supported for a prompt, the value of the variable
is 0.
• The value of this variable is set to undefined when an application root
document is loaded.

Dialog Variables
In VoiceXML 2.0, all dialog variables are represented as shadow variables.
Cisco VoiceXML supports all standard shadow variables including:
• name$.duration: Duration of the recording in milliseconds
• name$.size: Size of the recording in bytes
• name$.termchar: If dtmfterm is true, this shadow variable holds the pressed key.
• name$.maxtime: Boolean which is true if the recording was terminated because the maxtime
duration was reached
• name$.recording: Reference to the recording, or undefined if no audio is collected
• name$.recordingsize: Size of the recording in bytes, or undefined if no audio is collected
• name$.recordingduration: Duration of the recording in milliseconds, or undefined if no audio is
collected

Event Variables
Cisco VoiceXML does not support standard event variables.

Event Handling
This section discusses:
• The Fax Event Handler— A catch event handler to process the fax detection event.
• Events and Errors— A list of events thrown by the platform.

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-49
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

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

Table 1-7 Events and Errors Supported by Cisco VoiceXML

Error Event Description

error.unsupported If you use regex grammar with a version 2.0
VoiceXML document or, if you specify DTMF
grammar without specifying the DTMF option and
do not configure the ASR server, then the
interpreter throws an error.unsupported event.
When a platform does not support a specific
sequence of audio URI or codecs, or prompt
elements, the interpreter throws an
error.unsupported event.
Note A VoiceXML document throws an
error.unsupported event even if you have
pure DTMF grammar.
error.condition.baddestination When an invalid number is used for a transfer
element, the interpreter throws an
error.condition.baddestination event.
error.badfetch When a media server cannot reach or fetch a URI
that is specified in the speech markup or in the
grammar, the interpreter throws an error.badfetch
event.
error.unsupported.language If the media server is configured but does not
support the requested language, then the platform
throws an error.unsupported.language event.
error.unsupported.format If the media server is configured but cannot
process the grammar or speech format that is used
by the document, an error.unsupported.format
event is generated.

Cisco VoiceXML Programmer’s Guide

1-50 OL-11175-01
Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

Table 1-7 Events and Errors Supported by Cisco VoiceXML (continued)

Error Event Description

disconnect.com.cisco.handoff If the destination application does not return the
call leg but disconnects it, the VoiceXML
interpreter throws a disconnect.com.cisco.handoff
event to the VoiceXML application and the call is
handed off to another application using the
<object> element.
If the return flag is FALSE, indicating a
nonreturnable handoff, then the VoiceXML
interpreter throws a disconnect.com.cisco.handoff
event to the VoiceXML application.
error.com.cisco.handoff.failure If there is a failure in handing off an application;
for example if the application is not preconfigured
or built-in, or if it cannot be loaded, then the
interpreter throws an
error.com.cisco.handoff.failure event to the
VoiceXML application.
error.unsupported.object If the platform specific function
com.cisco.callhandoff is not supported, the
interpreter throws an error.unsupported.object
event to the VoiceXML application.
Note In VoiceXML 2.0 and later versions, this
event is replaced by
error.unsupported.objectname.
error.com.cisco.aaa.authenticate.failure This error event is generated if there are server
errors, for example, when the RADIUS server is
unreachable.
error.com.cisco.aaa.authorize.failure This error event is generated if there are server
errors, for example, when the RADIUS server is
unreachable.
error.noauthorization This error event is generated when the application
tries to perform an operation that is not authorized
by the platform.
error.noresource This error event is generated when a run-time error
occurred because a requested platform resource
was not available during execution and when
playing prerecorded files from the router fails.
In versions earlier than VoiceXML 2.0, the
equivalent events are
error.com.cisco.media.resource.unavailable,
error.com.cisco.resource.failure.asr,
error.com.cisco.resource.failure.tts, and
error.badfetch (for failure playing prerecorded
files from the router). These events are supported
for backward compatibility.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-51
 Chapter 1 Cisco VoiceXML Features
Control Flow and Scripting

Table 1-7 Events and Errors Supported by Cisco VoiceXML (continued)

Error Event Description

error.unsupported.objectname This error event is generated when the platform
does not support the object.
Note In versions earlier than VoiceXML 2.0, the
equivalent event is
error.unsupported.object, which is
supported for backward compatibility.
connection.disconnect.hangup This event is generated when the user hangs up.
In versions earlier than VoiceXML 2.0, the
equivalent event is telephone.disconnect.hangup,
which is supported for backward compatibility.
connection.disconnect.transfer This event is generated when the user is transferred
unconditionally to another line and will not return.
In versions earlier than VoiceXML 2.0, the
equivalent event is telephone.disconnect.transfer,
which is supported for backward compatibility.

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 For event types using default event handlers, no audio is provided.

Table 1-8 Event Types Using Default Event Handlers

Event Type Action

cancel Does not reprompt
error Exits interpreter
error.noauthorization Exits interpreter
exit Exits interpreter
help Reprompts
noinput Reprompts
nomatch Reprompts
telephone.disconnect Exits interpreter
All others Exits interpreter

Note If the behavior of a catch handler is specified as an error event in a VoiceXML document, the VoiceXML
interpreter does not exit after executing the catch handler; it allows the developer to use another
VoiceXML document. For example, you can play a different prompt on a different server instead of
exiting the interpreter.

Cisco VoiceXML Programmer’s Guide

1-52 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Environment and Resources

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:
• Built-in type: buffer
• The following function properties of the math object: acos(), asin(), atan(), atan2(), cos(), exp(),
log(), sin(), sqrt(), tan(), toExponential(), toFixed(), toPrecision().
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:
• MIN_VALUE = 5e-32
• MAX_VALUE = 1.7976931348623157e+31
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, page 1-53
• Property, page 1-55
• Default Values and Ranges, page 1-57

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:
• VoiceXML documents
• Prerecorded audio files
• JavaScript scripts
• Speech and DTMF grammars
Cisco VoiceXML supports the following attributes that govern fetching of content associated with a URI:
• The fetchtimeout attribute specifies the waiting time for a fetch.
• The fetchhint attribute defines the time when the interpreter retrieves content from the server.
• The fetchaudio attribute specifies the URI of the audio to be played while the document is being
fetched.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-53
 Chapter 1 Cisco VoiceXML Features
Environment and Resources

Note Cisco VoiceXML does not support the fetchhint properties.

The protocols supported for fetching are:

• Hypertext Transfer Protocol (HTTP)
• Real-Time Streaming Protocol (RTSP)
• Trivial File Transfer Protocol (TFTP)

Caching
Cisco VoiceXML does not have its own caching mechanism. It relies on the HTTP protocol to provide
caching.

Note Only the HTTP protocol has caching capabilities.

Cisco VoiceXML does not allow the user to control caching.

Cisco VoiceXML Programmer’s Guide

1-54 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Environment and Resources

Property
Cisco <property> extensions are listed in Table 1-9:

Table 1-9 Cisco < property> Extensions

Property Description
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:
• An entire application or document at the <vxml> level,
• A specific dialog at the form or menu level, or
• A specific form item.
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:
• ivr tts-server and ivr asr-server commands—Media server sessions are created
for each call to IVR applications, regardless of whether an application needs to talk
to the media server.
• com.cisco.tt-server and com.cisco.asr-server <property> extensions—Media
server sessions are created for each call to that application. If only a small number
of applications require TTS/ASR media sessions, you should use the <property>
extensions within those applications to define the external media server URL in the
VoiceXML script.
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-55
 Chapter 1 Cisco VoiceXML Features
Environment and Resources

Table 1-9 Cisco < property> Extensions (continued)

Property Description
com.cisco.media-logging-id • Allows the document to specify a unique ID for that specific instance of the
application. This ID is passed on to the external media server to allow it to
associate session logs generated for TTS and ASR operations with that ID.
• If this property is not set, the Cisco voice gateway automatically generates this ID
for that specific call or instance of the VoiceXML interpreter and uses it for the
length of the call or session.
• If a document chooses to override this ID with a new one, the new ID applies to the
rest of the session or until the time when another document chooses to set a new 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 VoiceXML 2.1 and later versions, the recordutterance property is not
supported for the <transfer> and <record> elements.

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.

Cisco VoiceXML Programmer’s Guide

1-56 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Call Handoff

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.

Table 1-10 VoiceXML Timeouts

VoiceXML Timeout Description

fetchtimeout The fetch timeout for loading a file. For this
timeout, 0 or the default means ten seconds. The
default can be reset through the CLI.
timeout The initial timeout for collecting digits. For this
timeout, 0 or the default means ten seconds.
incompletetimeout The required length of silence following user
speech after which a recognizer finalizes a result.
Note The behavior of the completetimeout
property is not supported. However, the
value of the completetimeout property is
parsed. The larger of the completetimeout
and incompletetimeout values is used as
the value of incompletetimeout.
interdigittimeout The maximum interval between digits. For this
timeout, 0 or the default means ten seconds. If
interdigittimeout is not specified, the port
configuration value is used.
connecttimeout The timeout for connecting a call. For this
timeout, 0 or the default can be a maximum of
sixty eight years.
maxtime The maximum call duration. For this timeout, 0 or
the default can be a maximum value of sixty eight
years.

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-57
 Chapter 1 Cisco VoiceXML Features
Call Handoff

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 on page 1-114.
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:
<object
name= "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:
• Handoff application— A one way handoff where the invoking VoiceXML session hands off the call
leg to the destination application without the call leg returning to it. To enable this one way handoff,
the parameter “return” is set to false.
<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.
• Handoff call application— In a handoff call application, the invoking VoiceXML session hands off
the specified call leg to the destination application, and waits for the call leg to be returned to it. To
allow the call leg to return, the parameter name “return” is set to true.
<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

Cisco VoiceXML Programmer’s Guide

1-58 OL-11175-01
Chapter 1 Cisco VoiceXML Features
Call Handoff

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.
• ResultVariableName.status is filled with the handoff status value of true for a successful handoff and
return operation, and false for a failure. ResultVariableName.argstring is filled with the argument
string returned by the target application. arg-string is an optional parameter name that is used to pass
parameters to the target application during a handoff. The target application instance has access to
the argument string when it starts up. A VoiceXML application can access the handoff arg-string
that is passed from the source of a handoff operation as a session variable
session.telephone.handoff_string.
• A return value of false indicates a nonreturnable handoff. If no return value is written into the script,
the default value is false.
Table 1-11 lists the attributes and parameters for the call handoff script shown above.

Table 1-11 Attributes and Parameters for Call Handoff

Attribute or Parameter Description

name (attribute) A field item variable name that contains the
results of the handoff operation. It contains the
subelement ResultVariableName.argstring in the
form of a string that is returned to the initiating
application.
classid (attribute) An attribute that specifies the platform object to
be invoked to initiate the handoff operation. It also
invokes the RADIUS authorization command.
return (parameter) • An optional parameter in the form of a
boolean value of true or false.
• If the value is true, the initiating application
waits for the call leg to be returned to it by the
destination application.
• If the value is false, the handoff is
nonreturnable.
• If the value is not specified, the default is
false, where the handoff is nonreturnable.
app-uri (parameter) A mandatory parameter, it is a URI that specifies
the destination application. The URI is of the form
builtin://appname, where appname is the name of
the destination application.
arg-string (parameter) An optional parameter that specifies a string or
list of strings to be passed to the destination
application.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-59
 Chapter 1 Cisco VoiceXML Features
Authentication and Authorization

Events and Errors in Call Handoff

• telephone.disconnect.com.cisco.callhandoff
– This event is thrown in a handoff application indicating a nonreturnable handoff.
– This event is thrown in a handoff call application, if the destination application disconnects the
call leg instead of returning it.
• error.com.cisco.callhandoff.failure
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.
• error.unsupported.object
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:
• Authentication validates the identity of the user.
• Authorization authorizes what the user can do.
• Authentication is valid without authorization.
• Authorization is not valid without authentication.
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.

Cisco VoiceXML Programmer’s Guide

1-60 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Authentication and Authorization

Authentication
In Cisco VoiceXML:
• An authentication request containing the account number and password is first sent to the RADIUS
server through the <object> element. The attribute classid specifies authentication through the Cisco
extension com.cisco.aaa.authenticate and is of the form:
classid="builtin://com.cisco.aaa.authenticate"

• Vendor specific attributes (VSAs) may also be sent by the application to the RADIUS server. These
VSAs are represented as parameters in the script with a valuetype “com.cisco.datatype.list.” For a
list of VSAs and how to use them, see the Vendor Specific Attributes Voice Implementation Guide.
• The RADIUS server sends the results of the authentication and applicable VSAs back to the voice
gateway in the form of a field item variable name:
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.
• To choose a specific RADIUS server group for authentication, use the server-tag to identify that
server group. The name of that group corresponds to the server group name configured through the
CLI.
• The VoiceXML interpreter is blocked until authentication is complete.
Table 1-12 summarizes the attributes and parameters of the authentication object.
The authentication object is accessed as follows:
<object
name="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>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-61
 Chapter 1 Cisco VoiceXML Features
Authentication and Authorization

Table 1-12 Attribute and Parameter Descriptions for the Authentication Object

Attribute or Parameter Description

name (attribute) It is a field item variable name that contains two subobjects:
• ResultVariableName.result— It contains the results of the authentication
operation as a pass or fail.
• ResultVariableName.attributes— It contains vendor specific attributes
(VSAs) that are returned by the RADIUS server as part of the
authentication response. The attributes object is a two dimensional array
indexed by the VSA name and an instance number. For example, if the
RADIUS server returns the VSA “h323-credit-amount” with a value of
282.25, the object [h323-credit-amount][0] contains the value 282.25.
• If the VoiceXML script accesses VSAs that are not returned in the
authentication operation, the variable returns undefined.
For more information on VSAs, see the RADIUS Vendor Specific Attributes
Voice Implementation Guide.
classid (attribute) It specifies the authentication operation through the Cisco extension
com.cisco.aaa.authenticate.
account (parameter) A mandatory parameter that specifies the account number for authentication.
password (parameter) A mandatory parameter that specifies the password for the account.
server-tag (parameter) • An optional parameter that specifies the RADIUS server group to be used
for authentication.
• The name of that group corresponds to the server group name configured
through the CLI.
key 1 to key N: VSA • These optional parameters are VSAs that are sent to the RADIUS server
name (parameter) as a part of the authentication request. These VSA parameters are
recognized as their valuetype attribute com.cisco.datatype.list. These
VSAs are sent in the authentication and authorization messages.
For a list of VSAs and how to use them, see the RADIUS Vendor Specific
Attributes Voice Implementation Guide.
• A VSA can occur multiple times if there is a need to send multiple
instances of the same VSA to the RADIUS server.

Events and Errors in Authentication

• error.com.cisco.aaa.authenticate.failure
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.
• error.unsupported.object
This error event is thrown if the specific platform function com.cisco.authentication is not
supported.

Cisco VoiceXML Programmer’s Guide

1-62 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Authentication and Authorization

Authorization
In Cisco VoiceXML:
• An authorization request containing the account number and password is first sent to the RADIUS
server through the <object> element. The attribute classid specifies authorization through the
specific Cisco extension com.cisco.aaa.authorize. It is of the form:
classid="builtin://com.cisco.aaa.authorize"

• The ANI and the DNIS of the call being authorized is included in the authorization command sent
to the RADIUS server.
• Vendor specific attributes (VSAs) may also be sent by the application to the RADIUS server. These
VSAs are represented as parameters in the script with a valuetype “com.cisco.datatype.list.” For a
list of VSAs , see the Vendor Specific Attributes Voice Implementation Guide.
• The RADIUS server sends the results of the authorization back to the voice gateway in the form of
a field item variable name:
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.
• To choose a specific RADIUS server group for authorization, use the server-tag to identify that
server group. The name of that group corresponds to the server group name configured through the
CLI.
• The VoiceXML interpreter is blocked until authorization is complete.
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-63
 Chapter 1 Cisco VoiceXML Features
Authentication and Authorization

Table 1-13 Attribute and Parameter Descriptions for the Authorization Object

Attribute or Parameter Description

name (attribute) It is a field item variable name that contains two subobjects:
• ResultVariableName.result— It returns the results of the authorization
operation as a pass or fail.
• ResultVariableName.attributes— It contains vendor specific attributes
(VSAs) that are sent by the billing server as part of the authorization
response.
For example, if the RADIUS server returns the VSA
“h323-credit-amount” with a value of 282.25, the object
[h323-credit-amount][0] contains the value 282.25.
• If the VoiceXML script accesses VSAs that are not returned in the
authorization operation, the variable returns undefined.
For more information on VSAs, see the RADIUS Vendor Specific Attributes
Voice Implementation Guide.

classid (attribute) It specifies the authorization operation through the specific Cisco extension
com.cisco.aaa.authorize.
account (parameter) A mandatory parameter that specifies the account number for authorization.
password (parameter) A mandatory parameter that specifies the password for the account.
ani (parameter) A mandatory parameter that specifies the ANI of the call being authorized.
dnis (parameter) A mandatory parameter that specifies the DNIS of the call being authorized.
server-tag (parameter) • An optional parameter that specifies the RADIUS server group to be
used for authorization.
• The name of that group corresponds to the server group name configured
through the CLI.
key 1 to key N: VSA • These optional parameters are VSAs that are sent to the RADIUS server
name (parameter) as a part of the authorization request. They have a valuetype of
“com.cisco.datatype.list.”
For a list of VSAs, see the RADIUS Vendor Specific Attributes Voice
Implementation Guide.
• A VSA can occur multiple times if there is a need to send multiple
instances of the same VSA to the RADIUS server.

Events and Errors in Authorization

• error.com.cisco.aaa.authorize.failure
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.
• error.unsupported.object
This error event is thrown if the specific platform function com.cisco.aaa.authorization is not
supported.

Cisco VoiceXML Programmer’s Guide

1-64 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
SIP and H.323 Support

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:
• Cisco IOS Tcl and VoiceXML Application Guide
• SIP Header/URL Support and Subscribe/Notify for External Triggers

Limitations
Limitations of SIP and TEL URL Support in Cisco VoiceXML are:
• The destination URI string length cannot exceed 1024 bytes. The VoiceXML application throws an
error if the document places a call to a URI whose string length exceeds 1024 bytes.
• For a call going out on an H.323 network, the destination URI has a maximum string length of
512 bytes.
• Headers in abbreviated formats are always converted to their full formats before being stored and
are not received by the VoiceXML application. For example, an application requesting the session
variable session.com.cisco.proto_headers[‘t’] does not receive the value of the “To:” header field.
• Restricted SIP headers for outbound calls: The following SIP headers cannot be overwritten:
– Call-ID
– Supported
– Require
– Min-SE
– Session-Expires
– Max-Forward
– CSeq
Excluding this list of headers, a VoiceXML application is allowed to pass any header, including
extended and nonstandard headers.
• Limitations for passing protocol headers are:
– 20 KB is the maximum memory allocation for a call passing headers.
– Each header avpair has a maximum limit of 256 characters. The application throws an error if
a VoiceXML document passes a header avpair exceeding 256 characters, or if the memory
exceeds 20 KB bytes.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-65
 Chapter 1 Cisco VoiceXML Features
SIP and H.323 Support

Reserved Characters

Character Escape Sequence

& &amp;
< &lt;
> &gt
‘ &apos;
“ &quot;

For example, sip:joe@big.com?Subject=Hello&ampPriority=Urgent must be rewritten as:

sip:joe@big.com?Subject=Hello&amp;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 &amp. Headers embedded
in TEL URLs are separated by a semicolon (;).

Note The URL in TEL:URL can only be an E.164 number. For example, tel:5550123 or tel:+1-408-555-1023.

Example
In this SIP:URL, “sip:joe@big.com?Subject=Car
Rental&ampPriority=urgent&ampAccount=1234567890” the header Subject=Car
Rental&ampPriority=urgent&ampAccount=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 ; .

Cisco VoiceXML Programmer’s Guide

1-66 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
SIP and H.323 Support

Headers in Outbound Calls

Cisco VoiceXML allows access to headers in only the following messages:
• SIP INVITE
• Subscribe
• Notify
• H.323 Setup

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&ampPriority=urgent&amp
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.0
Via: SIP/2.0/UDP 192.168.6.121:5060
From: 4085550134@192.168.6.121
To: joe@big.com
Call-ID: c2943000-e0563-2a1ce-2e323931@192.168.6.21
Subject: Hotel Reservation
Priority: urgent
X-ReferenceNumber: 1234567890

Note If the outbound call leg is not SIP or H.323, all headers that are transferred out from the VoiceXML
application are ignored.

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&ampPriority=urgent&ampAccount='+callerID"
bridge="true” connecttimeout="15s" maxtime="180s" cisco-longpound ="true"
cisco-handoffexpr="'my handoff string goes here'"
...
</transfer>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-67
 Chapter 1 Cisco VoiceXML Features
SIP and H.323 Support

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

• Outbound calls to a SIP:URL destination cannot be routed to a PSTN leg.

• Outbound calls to a TEL:URL can be routed to a PSTN leg. The number is extracted from the URL
and used as the destination number. The rest of the URL is ignored.
• Outbound header information in the future-extension field of a TEL:URL is ignored by a PSTN leg.

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:
• A standard SIP header name such as To, From, Subject.
• Any ASCII string limited to 256 characters.
• The predefined string name, request-URI; request-URI is the requested URI in a SIP message.

Examples
1. com.cisco.proto_headers[‘request-URI’]
Returns the request-URI in the incoming INVITE message.
2. com.cisco.proto_headers[‘To’]
Returns the “To” header value in the incoming INVITE message.

Cisco VoiceXML Programmer’s Guide

1-68 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
SIP and H.323 Support

3. com.cisco.proto_headers
Returns all headers concatenated into a single string with an ‘&’ to separate each header avpair. For
example “To=Joe@big.com&ampSubject=Hotel Reservation&amp...”.
If the DNIS or ANI includes a SIP URI, information is returned in the following session variables:
• session.telephone.dnis
Returns the requested URI received in the INVITE message which may or may not be an E.164
number.
• session.telephone.ani
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&amp \
session.com.cisco.proto_headers['From']=4085550134@192.168.6.121&amp \
session.com.cisco.proto_headers['Subject']=HotelReservation&amp \
sesion.com.cisco.proto_headers['X-ReferenceNumber']=1234567890

If 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:
• The ability to place a call from an application to a destination SIP URL.
• Passing protocol headers between applications.
See the Cisco IOS Tcl and VoiceXML Application Guide for the originating gateway (OGW) call flow
and Cisco IOS configuration.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-69
 Chapter 1 Cisco VoiceXML Features
SIP and H.323 Support

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>

Cisco VoiceXML Programmer’s Guide

1-70 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
SIP and H.323 Support

<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:
• The ability to place a call from an application to a destination TEL URL.
• Passing protocol headers between applications.

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>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-71
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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:
• A Tcl or VoiceXML script is used on the terminating gateway.
• The Tcl script plays the account number received from the OGW and the prompt “The number is.”
Other headers received are displayed in debug messages such as debug voip ivr script.
• 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.
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 If you are using Cisco IOS Release 12.3 or a later release, go to the “GTD Manipulation, Cisco IOS
Release 12.3” section on page 1-99.

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.

Table 1-14 GTD Parameters

GTD Parameter Name Description

RGN Redirecting number The number of the endpoint from which the call is
re-directed.
RNI Redirection information Sent in the forward direction. Includes redirecting
indicator, redirect reason, and redirect count.

Cisco VoiceXML Programmer’s Guide

1-72 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

Table 1-14 GTD Parameters (continued)

GTD Parameter Name Description

OCN Original called number In the case of multiple redirections it contains the
number of the endpoint at which the first
redirection occured.
RNN Redirection number The number of the endpoint to which the call is
redirected.
RNR Redirection number Indicates whether the redirection number may be
restriction presented by the caller.
CDI Call diversion Sent in the backward direction. Indicates the reason
information for the diversion.
GNO Generic notification Indicates call status for supplementary services.
indicator
CNN Connected number Final connected number
GEA Generic address Contains additional addresses indentified by
qualifier.
CPC Calling party category Type of caller: subscriber, operator, payphone, etc.
OLI Origination line Type of caller for North American networks: For
information example, subscriber, operator, payphone.
CID Carrier ID Identifies a transit carrier in North American
networks.
TNS Transit network Identifies the transit carrier.
selection
PCI Parameter compatibility Contains ISUP variant specific parameter that is
information not defined in GTD.
FDC Field compatibility Contains an ISUP variant specific parameter that is
information not defined in GTD.
TMR Transmission medium Bearer capacity
required
BCI Backward call Information sent from the called party to the calling
indicators party.
CHN Charge number Additional number used for charging.

Table 1-15 GTD Parameters and Fields Mapped to VoiceXML Variables

NI2C Message GTD Message GTD Parameter. Field Cisco VoiceXML Variable
Setup IAM RGN.noa com.cisco.rgn_noa
Setup IAM RGN.npi com.cisco.rgn_npi
Setup IAM RGN.pi com.cisco.rgn_pi
Setup IAM RGN.# com.cisco.rgn_num
Setup IAM RNI.ri com.cisco.rni_ri
Setup IAM RNI.orr com.cisco.rni_orr

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-73
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

Table 1-15 GTD Parameters and Fields Mapped to VoiceXML Variables (continued)

NI2C Message GTD Message GTD Parameter. Field Cisco VoiceXML Variable
Setup IAM RNI.rc com.cisco.rni_rc
Setup IAM RNI.rr com.cisco.rni_rr
Setup IAM OCN.noa com.cisco.ocn_noa
Setup IAM OCN.npi com.cisco.ocn_npi
Setup IAM OCN.pi com.cisco.ocn_pi
Setup IAM OCN.num com.cisco.ocn_num
Setup IAM CHN.npi com.cisco.chn_npi
Setup IAM CHN.# com.cisco.chn_num
Setup IAM CHN.noa com.cisco.chn_noa
Setup IAM GEA.type com.cisco.gea_type
Setup IAM GEA.noa com.cisco.gea_noa
Setup IAM GEA.npi com.cisco.gea_npi
Setup IAM GEA.cni com.cisco.gea_cni
Setup IAM GEA.pi com.cisco.gea_pi
Setup IAM GEA.# com.cisco.gea_num
Setup IAM GEA.si com.cisco.gea_si
Setup IAM CPC.cpc com.cisco.cpc
Setup IAM OLI.oli com.cisco.oli
Setup IAM CID.ton com.cisco.cid_ton
Setup IAM CID.cid com.cisco.cid_cid
Setup IAM TNS.nip com.cisco.tns_nip
Setup IAM TNS.cc com.cisco.tns_cc
Setup IAM TNS.tns com.cisco.tns_tns
Setup IAM TNS.ton com.cisco.tns_ton
Setup, Alert, Progress, Connect IAM, ACM, PCI.instr com.cisco.pci_instr
CPG, ANM
Setup, Alert, Progress, Connect IAM, ACM, PCI.tri com.cisco.pci_tri
CPG, ANM
Setup, Alert, Progress, Connect IAM, ACM, PCI.dat com.cisco.pci_dat
CPG, ANM
Setup, Alert, Progress, Connect IAM, ACM, FDC.parm com.cisco.fdc_parm
CPG, ANM
Setup, Alert, Progress, Connect IAM, ACM, FDC.fname com.cisco.fdc_fname
CPG, ANM
Setup, Alert, Progress, Connect IAM, ACM, FDC.instr com.cisco.fdc_instr
CPG, ANM
Setup, Alert, Progress, Connect IAM, ACM, FDC.dat com.cisco.fdc_dat
CPG, ANM

Cisco VoiceXML Programmer’s Guide

1-74 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

The section below describes the Cisco VoiceXML variables that are mapped to the GTD parameters in
Table 1-15.

Note All field values are case sensitive and use the seven bit US ASCII character set.

The Cisco VoiceXML variables providing GTD parameters are:

• com.cisco.rgn_noa, page 1-76
• com.cisco.rgn_npi, page 1-77
• com.cisco.rgn_pi, page 1-77
• com.cisco.rgn_num, page 1-77
• com.cisco.rni_ri, page 1-77
• com.cisco.rni_orr, page 1-77
• com.cisco.rni_rc, page 1-78
• com.cisco.rni_rr, page 1-78
• com.cisco.ocn_noa, page 1-78
• com.cisco.ocn_npi, page 1-79
• com.cisco.ocn_pi, page 1-80
• com.cisco.ocn_num, page 1-80
• com.cisco.chn_noa, page 1-80
• com.cisco.chn_npi, page 1-80
• com.cisco.chn_num, page 1-81
• com.cisco.gea_type, page 1-81
• com.cisco.gea_noa, page 1-81
• com.cisco.gea_npi, page 1-82
• com.cisco.gea_cni, page 1-83
• com.cisco.gea_pi, page 1-83
• com.cisco.gea_si, page 1-83
• com.cisco.gea_num, page 1-83
• com.cisco.cpc, page 1-83
• com.cisco.oli, page 1-84
• com.cisco.cid_ton, page 1-85
• com.cisco.cid_cid, page 1-85
• com.cisco.tns_ton, page 1-86
• com.cisco.tns_nip, page 1-86
• com.cisco.tns_cc, page 1-86
• com.cisco.tns_tns, page 1-86
• com.cisco.pci_instr, page 1-86
• com.cisco.pci_tri, page 1-87

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-75
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

• com.cisco.pci_dat, page 1-87

• com.cisco.fdc_parm, page 1-87
• com.cisco.fdc_fname, page 1-87
• com.cisco.fdc_instr, page 1-88
• com.cisco.fdc_dat, page 1-88

com.cisco.rgn_noa
Syntax com.cisco.rgn_noa
GTD parameter Redirecting number (RGN)
Field noa— Nature of address
Field values 00—Unknown, number present
01—Unknown, number absent, presentation restricted
02—Unique subscriber number
03—Nonunique subscriber number
04—Unique national (significant) number
05—Nonunique national number
06—Unique international number
07—Nonunique international number
08—Network specific number
09—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

Cisco VoiceXML Programmer’s Guide

1-76 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

com.cisco.rgn_npi
Syntax com.cisco.rgn_npi
GTD parameter Redirecting number (RGN)
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.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)

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-77
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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
1
Syntax com.cisco.rni_rc
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_noa 1
GTD parameter Original called number (OCN)

Cisco VoiceXML Programmer’s Guide

1-78 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-79
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

Cisco VoiceXML Programmer’s Guide

1-80 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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)

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-81
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

Cisco VoiceXML Programmer’s Guide

1-82 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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
1
Syntax com.cisco.gea_pi
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
1
Syntax com.cisco.gea_si
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)

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-83
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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)

Cisco VoiceXML Programmer’s Guide

1-84 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-85
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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_ns 1
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)

Cisco VoiceXML Programmer’s Guide

1-86 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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)

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-87
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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.

Cisco VoiceXML Programmer’s Guide

1-88 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

GTD parameter Redirecting number (RGN)

Field noa— Nature of address
Field values 00—unknown, number present
01—unknown, number absent, presentation restricted
02—unique subscriber number
03—nonunique subscriber number
04—unique national (significant) number
05—nonunique national number
06—unique international number
07—nonunique international number
08—network specific number
09—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

GTD parameter Redirecting number (RGN)

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-89
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

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

GTD parameter Redirection information (RNI)

Field rc— Redirection counter
Field values Valid values are in the range of 1–15.

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

GTD parameter Original called number (OCN)

Cisco VoiceXML Programmer’s Guide

1-90 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-91
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

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

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

Cisco VoiceXML Programmer’s Guide

1-92 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-93
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

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

Cisco VoiceXML Programmer’s Guide

1-94 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

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 Calling party category (CPC)

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-95
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

Cisco VoiceXML Programmer’s Guide

1-96 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-97
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.2(11)T

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

GTD parameter Parameter compatibility (PCI)

Field tri— Transit at intermediate exchange indicator
Field values 0—No transit
1—Yes transit

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.

GTD parameter Known field compatibility information (FDC)

Field parm— Parameter name
Field values A string of three ASCII characters.

Cisco VoiceXML Programmer’s Guide

1-98 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

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.

GTD parameter Known field compatibility information (FDC)

Field instr— Instruction
Field values 1—Release call if not understood, regardless of the ability to forward
2—Use the default value if not understood regardless of the ability to forward;
no notification required, but continue call
3—Use the default value if not understood regardless of the ability to forward;
send notification (in Confusion), but continue 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

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-99
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

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 A GTD parameter can be sent or received in any GTD message.

Table 1-16 GTD Parameters

GTD Parameter Name Description

RGN Redirecting Number The number of the endpoint from which the call is
re-directed.
RNI Redirection Information Sent in the forward direction. Includes redirecting
indicator, redirect reason, and redirect count.
OCN Original Called Number In the case of multiple redirections it contains the
number of the endpoint at which the first
redirection occured.
RNN Redirection Number The number of the endpoint to which the call is
redirected.
RNR Redirection Number Indicates whether the redirection number may be
Restriction presented by the caller.
CDI Call Diversion Sent in the backward direction. Indicates the reason
Information for the diversion.
GNO Generic Notification Indicates call status for supplementary services.
Indicator
CNN Connected number Final connected number
GEA Generic address Contains additional addresses indentified by
qualifier.
CPC Calling party category Type of caller: subscriber, operator, payphone, etc.
OLI Origination line Type of caller for North American networks: For
information example, subscriber, operator, payphone.
CID Carrier ID Identifies a transit carrier in North American
networks.
TNS Transit network Identifies the transit carrier.
selection

Cisco VoiceXML Programmer’s Guide

1-100 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

Table 1-16 GTD Parameters (continued)

GTD Parameter Name Description

PCI Parameter compatibility Contains ISUP variant specific parameter that is
information not defined in GTD.
FDC Field compatibility Contains an ISUP variant specific parameter that is
information not defined in GTD.
TMR Transmission medium Bearer capacity
required
BCI Backward call Information sent from the called party to the calling
indicators party.
CHN Charge number Additional number used for charging.
CAI Cause indicator CCITT and ANSI cause codes.
CPN Called party number Same as DNIS. It provides additional parameters
such as nature of address and numbering plan
indicator.
RDC Redirect capability Indicates the point at which redirection is possible
in a call setup.
UUS User-to-user —
information

Table 1-17 GTD Parameters and Fields

GTD Parameter. Field

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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-101
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

Table 1-17 GTD Parameters and Fields (continued)

GTD Parameter. Field

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

Cisco VoiceXML Programmer’s Guide

1-102 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

Table 1-17 GTD Parameters and Fields (continued)

GTD Parameter. Field

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:
• com.cisco.objclass.gtd
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 IAM is used only as an example.

• com.cisco.signal.gtdlist
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-103
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

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.
• <transfer-name>$.com.cisco.signal.gtdlist
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:
– alert_indication
– connect_indication
– disconnect_indication
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"/>

Cisco VoiceXML Programmer’s Guide

1-104 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

<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 If VoiceXML and JavaScript do not accept some special characters such as #, -, or + for field names,
those field names must be provided within square brackets ([]). For example, to access the number (#)
field of the first instance of the RGN parameter using JavaScript, it is specified as var rgn_num=
my_gtd.RGN[0][‘#’].

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. <var name= “my_gtd” expr= “new
com.cisco.objclass.gtd(com.cisco.signal.gtdlist[‘setup_indication’])”/>
This example creates a copy of the GTD message that came with the Setup Ind event on the incoming
leg.
2. <var name= “out_gtd” expr= “new
com.cisco.objclass.gtd(gtd_xfer$.com.cisco.signal.gtdlist[‘alert_indication’])”/>
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-105
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

3. <var name= “my_gtd” expr= “new

com.cisco.objclass.gtd(com.cisco.signal.gtdlist[‘setup_indication’])”/>
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 parameter
var pci_data= my_pci.dat
my_pci.dat= pci_data+5;
<script/>
The following modifications of a GTD parameter or field are supported:
• Replace
• Append
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:
• The VoiceXML script specifies <assign name= “my_gtd[2].dat” expr= “‘ABCDEF0123’”/>, the
GTD parameter is appended.
• The VoiceXML script specifies <assign name= “my_gtd[1].dat” expr= “‘ABCDEF0123’”/>, the
GTD parameter is replaced.
• The VoiceXML script specifies <assign name= “my_gtd[4].dat” expr= “‘ABCDEF0123’”/>, an
exception error error.com.cisco.invalid.gtd.instance is thrown because in this case only the instance
numbers of 0 to 2 are valid, 0 and 1 for replace and 2 for append.

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]['#']"/>

Cisco VoiceXML Programmer’s Guide

1-106 OL-11175-01
Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

<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' &amp;&amp; y != '9876543210' &amp;&amp; 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'"/>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-107
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

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

Cisco VoiceXML Programmer’s Guide

1-108 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

</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:
• Invalid GTD parameter or field name
• Invalid value of a GTD field
• Invalid instance that results from modifying a GTD parameter or field
• Invalid GTD message type
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-109
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

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
• Two B Channel Transfer: Redirecting Calls for ISDN

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:
• Rotary— Gateway places a rotary call for outgoing call leg and hairpins the two calls together.
• Redirect_at_Connect—Call legs are connected by PSTN switch after the outgoing call leg is in
Connect state.
• Redirect_Rotary—PSTN switch tries to directly connect the two call legs (redirect), otherwise, if
that fails, call is hairpinned on the gateway (rotary).
• Redirect—PSTN switch directly connects the two call legs.

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>

Cisco VoiceXML Programmer’s Guide

1-110 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

<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:
• Cisco VoiceXML root document property com.cisco.transfer.mode is enabled for the following
transfer modes:
– Redirect_Rotary
– Redirect_at_XX , where XX represents connect or alert.
• The selected DS0s are within the same PRI line that has enabled TBCT, or the two PRI lines are
configured for TBCT under the same trunk group.
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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-111
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

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:

redirect Gateway redirects the call leg to the redirected destination number.

redirect-at-alert Gateway places a new call to the redirected destination number and initiates
a call transfer when the outgoing call leg is in the alerting state. If the call
transfer is successful, the two call legs are disconnected on the gateway. If
the transfer fails, the gateway bridges the two call legs. Supports TBCT.

redirect-at-connect Gateway places a new call to the redirected destination number and initiates
a call transfer when the outgoing call leg is in the connect state. If the call
transfer is successful, the two call legs are disconnected on the gateway. If
the transfer fails, the gateway bridges the two call legs. Supports TBCT.

redirect-rotary Gateway redirects the call leg to the redirected destination number. If
redirection fails, the gateway places a rotary call to the redirected
destination number and hairpins the two call legs. For TBCT, this mode is
the same as redirect-at-connect.

rotary Gateway places a rotary call for the outgoing call leg and hairpins the two
call legs. Call redirection is not invoked. This is the default.

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:
• Configure the source carrier ID
• Configure the outbound dial peer. The target carrier ID is the same as the source carrier ID.
• Set the carrier ID in the VoiceXML script.
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
• com.cisco.carrierid.source —Defines the source ID for an incoming call.
• com.cisco.carrierid.target—Defines the target ID for an incoming call.

<transfer> attributes
• cisco-carrierid-source—Sets the source carrier ID for an outgoing call.
• cisco-carrierid-target—Sets the target carrier ID for an outgoing call.

Cisco VoiceXML Programmer’s Guide

1-112 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
GTD Manipulation, Cisco IOS Release 12.3

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.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-113
 Chapter 1 Cisco VoiceXML Features
Hybrid Applications

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 • If the GTD object specified in cisco-gtd is invalid or null, it will be ignored and no exceptions are
thrown.
• If the cause code results in an integer, or if it is null or invalid (for example, an unknown variable),
an error.semantic error event is thrown.
• The cause value can be specified in the cause code and the GTD object but they must both be
consistent.

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

Cisco VoiceXML Programmer’s Guide

1-114 OL-11175-01
Chapter 1 Cisco VoiceXML Features
Hybrid Applications

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 reason for receiving an ev_vxmldialog_done event or an ev_vxmldialog_event event is generated
in a VoiceXML specific event name vxml.* in the form of a string. These events are accessed through
the evt_vxmlevent information tag in Tcl IVR 2.0. The string vxml.* indicates an event name which
can come from the VoiceXML interpreter environment (vxml.session.*) or from the dialog executing
in the interpreter (vxml.dialog.*). Some of the messages coming from the VoiceXML interpreter
environment are vxml.session.complete indicating normal completion of a dialog, or
vxml.session.transfer indicating that the document tried to execute the <transfer> element which is
not supported in hybrid mode.
The evt_vxmlevent information tag contains a vxml.dialog.* string, if:
– The VoiceXML document throws an error.badfetch which is not caught, allowing the dialog to
complete its execution, or
– If the document uses the <object> element to send an explicit message to the Tcl script.
• A parameter array of information which is accessible through the evt_vxmlevent_params
information tag.
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

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-115
 Chapter 1 Cisco VoiceXML Features
Hybrid Applications

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:
• A vxml.session.transfer event is sent by the VoiceXML environment to the Tcl script.
• The VoiceXML environment throws an error.unsupported.transfer event at the VoiceXML session
which can be caught. If the event is not caught, the default handler causes the VoiceXML dialog to
terminate, resulting in an ev_vxmldialog_done event thrown to the Tcl script.

Events and Errors

• error.unsupported.transfer
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>

Cisco VoiceXML Programmer’s Guide

1-116 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Limitations and Restrictions

Table 1-18 Attributes and Parameters for the <sendevent> Object

Attribute or Parameter Description

name (attribute) The field item variable name that is filled with the
results of the sendevent operation. It is an
ECMAScript object containing the subobject
ResultVariableName.status.
ResultVariableName.status returns the status of
the sendevent operation as a PASS or FAIL.
Note For Cisco IOS Release 12.(2)11T, the
status of the sendevent operation is always
a PASS.
classid (attribute) It invokes the
“builtin://com.cisco.ivrscript.sendevent”
command object resulting in an event being sent
to the parent Tcl IVR script if the VoiceXML
module is invoked as a subhandler by the Tcl IVR
script.
eventname (parameter) A mandatory parameter that specifies the name of
the subevent sent to the Tcl IVR application. The
subevent name is retrieved from the script using
the evt_event_name infotag.
key 1 to key N (parameters) • A set of optional parameters that allow the
VoiceXML application to send parameters
and the event to the Tcl IVR script.
• The value of the attribute name in these
parameters is available to the Tcl script
through the evt_vxmlevent_params infotag.
• The values of the attribute names become the
indices of the Tcl array that contains the
evt_vxmlevent_params infotag.
• The group of attributes is recognized by the
type attribute “array: com.cisco.aaa.vsa.”
• If an attribute name occurs multiple times, the
indices available to the Tcl IVR script are of
the form (Name, 0), (Name, 1), (Name,2),
until the last applicable index.

Limitations and Restrictions

For limitations and restrictions on using Cisco VoiceXML, see the Cisco IOS Tcl IVR and VoiceXML
Application Guide.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-117
 Chapter 1 Cisco VoiceXML Features
Additional References

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
Related Topic Document Title
Tcl and IVR Cisco IOS Tcl IVR and VoiceXML Application Guide
Tcl IVR API Version 2.0 Programmer’s Guide
Enhanced Multi-Language Support for Cisco IOS Interactive Voice
Response
Voice Cisco IOS Voice Configuration Library
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
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

Cisco VoiceXML Programmer’s Guide

1-118 OL-11175-01
 Chapter 1 Cisco VoiceXML Features
Additional References

Standards
Standard Title
ECMA-262 ECMAScript Specification 3.0 (Standard ECMA-262, ECMAScript
Language Specification, 3rd edition, August 1998

RFCs
RFC Title
RFC 2298 An Extensible Message Format for Message Dispostion Notification
RFC 1894 An Extensible Message Format for Delivery Status Notifications

Technical Assistance
Description Link
The Cisco Technical Support & Documentation http://www.cisco.com/techsupport
website contains thousands of pages of searchable
technical content, including links to products,
technologies, solutions, technical tips, tools, and
technical documentation. Registered Cisco.com users
can log in from this page to access even more content.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 1-119
 Chapter 1 Cisco VoiceXML Features
Additional References

Cisco VoiceXML Programmer’s Guide

1-120 OL-11175-01
 CH A P T E R 2
Cisco VoiceXML Troubleshooting

Revised: June 20, 2007, OL-11175-01

This chapter describes some of the troubleshooting techniques for the Cisco VoiceXML features. For a
list of the latest troubleshooting FAQs, go to the developer support website at
www.cisco.com/go/developersupport/.

Debugging Cisco VoiceXML Applications

To debug Cisco VoiceXML applications at the gateway level, refer to the Cisco IOS Tcl IVR and
VoiceXML Application Guide for your Cisco IOS Release.
This section describes troubleshooting at the script level. To troubleshoot Cisco VoiceXML scripts,
enable the debug vxml error and debug vxml puts commands on the gateway. debug vxml error
displays all errors on the console, and debug vxml puts prints debugging statements used with the <log>
element in the VoiceXML document.

<cisco-puts>
<cisco-puts> is a specific Cisco debugging element that is similar to the <log> element in the
VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005). The output from both elements is a
log or debug message that may contain a combination of text and <value> elements.

Note In Cisco IOS Release 12.4(11)T and later releases, the <cisco-puts> and <cisco-putvar> elements are
obsolete. Use the <log> and <value expr> elements for logging and debugging in these releases.

debug vxml puts

Note Use the debug vxml or debug vxml puts commands to debug Cisco VoiceXML scripts that use
the <log> element.

Examples
1. This is an example of debug vxml puts to provide the output for <log>.
<log> AccountInfo is <value expr="session.c

Cisco VoiceXML Programmer’s Guide

OL-11175-01 2-1
 Chapter 2 Cisco VoiceXML Troubleshooting
Debugging Cisco VoiceXML Applications

om.cisco.proto_headers['AccountInfo']"/>
</log>

<log>DEBUG: The ASR server matches the user voice input successfully
</log>

2. Here is a sample script for <cisco-data>:

<vxml version="2.0">

<form>
<var name="output" expr="123"/>

<block>
<cisco-data src="http://server1/cgi-bin/ciscodata.tcl" name="MyData"
method="post" namelist="output"/>

<log> The data sent is as follows:

<value expr="MyData"/>
</log>
</block>
</form>
</vxml>

The output from debug vxml puts is a string that is specified by <log> in the script and the output is
shown below:
Mar 1 03:17:22.551: The data sent is as follows:

Hi Ray!
You just received data through cisco-data element.
Have a nice day..............

<cisco-debug>
Use <cisco-debug> to debug only a specific application. To disable debugging messages for all
VoiceXML applications except the specific VoiceXML application you wish to debug, use the
<cisco-debug> element in the VoiceXML document in conjunction with the debug condition
application voice command.
See the Cisco IOS cl IVR and VoiceXML Application Guide for information on debug commands.

Note Add <cisco-debug> to the VoiceXML document for the application you want to debug, before you use
Cisco IOS debug commands to debug that specific application.

For example:

Step 1 Turn on global debug for the areas you want to debug. For example:
debug vxml application
debug vxml trace

Note If you do not proceed with step 2 and end your task with step 1, you will see system messages
for all the applications regardless of conditional debug being turned on or off.

Cisco VoiceXML Programmer’s Guide

2-2 OL-11175-01
 Chapter 2 Cisco VoiceXML Troubleshooting
Debugging Cisco VoiceXML Applications

Note The debug condition application voice command filters debugging output for only the debug
vxml and debug http client commands. However, it does not filter ouptput for the debug vxml
error, debug vxml background, debug http client error, or debug http client background
commands.

Step 2 Add the <cisco-debug enabled = “true”/> and <cisco-debug enabled = “false”/> elements around the
specific part of the VoiceXML document where you want to see debugging messages. For example:
<?xml version="1.0"?>
<vxml version="1.0" application="root.vxml">
<form>
<block>
<cisco-debug enabled = "true"/>
<prompt>
<audio src="welcome.au" caching="fast"/>
</prompt>
<cisco-debug enabled = "false"/>
<goto next="getExtension.vxml?"/>
</block>
</form>
</vxml>

Step 3 Add conditional debugging to the specific application you want to debug. For example:
Three applications named myapp1, myapp2, and myapp3, all of which can be loaded by using the call
application voice command, are shown below:
call application voice myapp1 http://server1/vxml/test1.vxml
call application voice myapp2 http://server2/vxml/test2.vxml
call application voice myapp3 http://server3/vxml/test3.vxml

To debug only one of the applications, for example myapp1, use the debug condition application voice
command to disable debug messages for the applications myapp2 and myapp3.
debug condition application voice myapp1

Note Debugging for myapp1 is performed for only those debug areas that have been enabled in step 1.
Debugging for the specific session must be enabled through the <cisco-debug> tag as shown in
step 2.

CallID and GUID in Debug Messages

The output debug messages are of the form //<callid>/<guid>/. If the information in these messages is
not available at certain times, for example during call setup, the output debug messages are displayed as
//-1/xxxxxxxxx/ or //-1//. Use the voice call debug full-guid Cisco IOS command to display guid in short
or long format.

Note CallID and GUID values are still retained after the incoming call leg ceases.

Example
<log> callid is <value expr="session.telephone.com.cisco.callid"/>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 2-3
 Chapter 2 Cisco VoiceXML Troubleshooting
Error Events

</log>

<if cond="session.telephone.com.cisco.callid == ''">

<log> CALLID WAS NOT RECEIVED</log>
<assign name="testResult" expr="'failed'"/>
</if>

<log> guid is <value expr="session.telephone.com.cisco.guid"/>

</log>

The output is:

*Mar 1 04:42:07.558: callid is 15

*Mar 1 04:42:07.558: guid is C44404A9-151A-11CC-8066-B2BF937DE628

Error Events
Enabling the debug vxml error command displays a list of possible error events on the console. For a
list of error events, see the Events and Errors section.
Some of the possible errors generated with the debug vxml error command enabled are:

error.badfetch

Possible Causes Suggested Actions

• The VoiceXML interpreter throws this event • Verify that the external documents, audio
when there is a failure in retrieving external prompts, or grammar files are available at the
components in the application. These specified location mentioned in the URL.
external components can be VoiceXML
• If the external components are stored on a
documents, prerecorded files, or grammar
HTTP server, enable the debug http client
files.
error command.
• A badfetch error usually occurs when there is
• If the external components are stored on a
an error in fetching an external document.
RTSP server, search for
error.badfetch.rtsp.xxx, where xxx is a RTSP
response code. For values of RTSP response
codes, see RFC 2326 available on the IETF
website.

error.semantic

Possible Causes Suggested Actions

Logical errors such as referencing an undefined Verify that all variables referenced in the script
variable. are defined and valid.
Defining different grammar types in the same Verify that only one grammar type is used at the
scope in the VoiceXML application. time of recognizing user input.
Failure to define mandatory parameters in Cisco Verify that all mandatory parameters are defined
objects. For example, failure to define the account in Cisco objects used in the script.
parameter in the authorize object will result in a
semantic error.

Cisco VoiceXML Programmer’s Guide

2-4 OL-11175-01
Chapter 2 Cisco VoiceXML Troubleshooting
JavaScript/ECMA Script

error.unsupported.format

Possible Causes Suggested Actions

A resource format is not supported by the Verify that all formats used in the script are
platform. supported by the specific platforms being used.

JavaScript/ECMA Script
When the <script> element or ECMA expression is used in a VoiceXML document, enable the debug
java command for debugging.
debug java ?
apm2- JavaScript APM2 Utility Debugging
error- JavaScript Error Debugging
interpreter- JavaScript Interpreter Debugging

Cisco VoiceXML Programmer’s Guide

OL-11175-01 2-5
 Chapter 2 Cisco VoiceXML Troubleshooting
JavaScript/ECMA Script

Cisco VoiceXML Programmer’s Guide

2-6 OL-11175-01
 CH A P T E R 3
Cisco VoiceXML Applications

Revised: June 20, 2007, OL-11175-01

For the latest version of the scripts described in this chapter, go to the developer support website at
http://www.cisco.com/cgi-bin/dev_support/access_level/products.cgi?product=VOICE_XML_GATEW
AY.
This chapter describes applications using Cisco VoiceXML features, and consists of the following
sections:
• Hybrid Application
• Speech Enabled Banking Application
• ASR and TTS Application
• Multi-Language Application
• Recording Application

Hybrid Application
The TCL and VoiceXML hybrid script in this example is a call screening application. This script is
invoked, when the user calls into the gateway. The user is prompted to record their name which is
recorded in a VoiceXML dialog and embedded in the TCL script. After the name is recorded, the
destination number is collected and the script places a call. When the called party answers the call, the
recorded name is played. The called party is prompted to enter the digit one to accept the call or two to
reject it. If the called party chooses to accept the call, the incoming and outgoing legs are bridged. If the
called party rejects the call, an audio prompt is played to the calling party indicating that the call has
been rejected and the call is then disconnected.

Procedure init
#The init procedure defines the initial parameters of the digit collection. The first set of parameters,
param1 allows the users to enter digits before a prompt playout is complete. It also defines the asterisk
key to terminate the digit collection process and the pound key to indicate the end of digit collection.
The collected digit is matched with a dialplan configured on a dial-peer. The second set of parameters,
param2 has the same definition except that the collected digits are not matched with a dialplan.
#

proc init { } {
global param1
global param2

set param1(interruptPrompt) true

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-1
 Chapter 3 Cisco VoiceXML Applications
Hybrid Application

set param1(abortKey) *
set param1(terminationKey) #
set param1(dialPlan) true

set param2(interruptPrompt) true

set param2(abortKey) *
set param2(terminationKey) #

Procedure init_perCallVars
In this procedure, the global variables are initialized.

proc init_perCallVars { } {
global ani
global dnis
global dest

set dest ""

set ani [infotag get leg_ani]

set dnis [infotag get leg_dnis]

Procedure act_RecordGreeting
This procedure is executed when the application receives an ev_setup_indication event. A setup
acknowledgement and a signal level connect message is sent to the incoming call leg. The VoiceXML
dialog is invoked and the VoiceXML dialog prompts the user to record the name. The recording codec
is g729r8 and the recording terminates after 6 seconds or if the user enters a Pound key. The recorded
audio is stored in the record field, myrecord.
#

proc act_RecordGreeting { } {
global param1
set baseURI http://WEB-SERVER/
set vxmlScript {
<vxml version="2.0">
<form>
<catch event="error">
<audio src="technicalProblem.au"/>
</catch>

<var name="mydur"/>
<var name="mysiz"/>

<block>
<prompt><audio src="record.au"/></prompt>
</block>
<record name="myrecord" maxtime="6s" finalsilence="3s" beep="true"
type="audio/basic;codec=g729r8" dtmfterm="true">
<filled>
<assign name="mydur" expr="myrecord$.duration"/>
<assign name="mysiz" expr="myrecord$.size"/>

<log>DTMF Termintation key is <value

expr="myrecord$.termchar"/> </log>

Cisco VoiceXML Programmer’s Guide

3-2 OL-11175-01
Chapter 3 Cisco VoiceXML Applications
Hybrid Application

<log>Duration of recording is <value

expr="myrecord$.duration"/> </log>
<log>Size of recorded audio file is <value
expr="myrecord$.size"/> </log>
<prompt><value expr="myrecord"/></prompt>

<exit namelist="myrecord"/>
</filled>
</record>
</form>
</vxml> }

init_perCallVars

leg setupack leg_incoming

leg proceeding leg_incoming
leg connect leg_incoming

leg vxmldialog leg_incoming -u $baseURI -v $vxmlScript

}

Procedure act_GetDest
This procedure is called when the application receives the vxml_dialog_done event. It checks for the
recorded audio file and plays it to the incoming leg. It then prompts and collects the destination number.
#

proc act_GetDest { } {
global param1
global param
global recordedName

# check the sub-event name

set exp_ev vxml.session.complete
set ev [infotag get evt_vxmlevent]
if {$ev != $exp_ev} {
puts "DEBUGGING: expected event $exp_ev, got $ev"
puts "VXML Dialog not complete"
call close
return
}

# check the dialog status

set status [infotag get evt_status]
if {$status != "vd_000"} {
puts "DEBUGGING: VXML Dialog status, expected vd_000, got $status"
puts "VXML Dialog not successful"
call close
return
}

# get the audio variable

infotag get evt_vxmlevent_params param
if !{[info exists param(myrecord)]} {
puts "DEBUGGING: myrecord does not exist"
call close
return
}

set recordedName $param(myrecord)

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-3
 Chapter 3 Cisco VoiceXML Applications
Hybrid Application

media play leg_incoming $param(myrecord)

puts "DEBUGGING: leaving act_GetDest"

media play leg_incoming tftp://TFTP-SERVER/_enter_dest.au
leg collectdigits leg_incoming param1

Procedure act_GetDestDone
This procedure is excecuted when the application receives a ev_collectdigits_done event. It then collects
a password from the user.
#

proc act_GetDestDone { } {
global dest
global param1
global param2
global passwd

set status [infotag get evt_status]

puts "DEBUGGING : act_GetDestDOne status is $status"

if {$status == "cd_004"} {
set dest [infotag get evt_dcdigits]
set pattern(passwd) .+

leg collectdigits leg_incoming param2 pattern

media play leg_incoming tftp://TFTP-SERVER_enter_pin.au
} else {
media play leg_incoming tftp://TFTP-SERVER/_invalid_dest.au
leg collectdigits leg_incoming param1
fsm setstate same_state
}

Procedure act_GetPasswdDone
When the password is collected, the application places an outbound call with the destination number it
has collected. The password information is set in the callInfo field.
#

proc act_GetPasswdDone { } {
global passwd
global dest

set status [infotag get evt_status]

puts "DEBUGGING : act_PasswdDone status is $status"

if {$status == "cd_005"} {
set passwd [infotag get evt_dcdigits]
set callInfo(pinNum) $passwd

leg setup $dest callInfo leg_incoming

} else {
media play leg_incoming tftp://TFTP-SERVER/_invalid_pin.au
set pattern(passwd) .+

Cisco VoiceXML Programmer’s Guide

3-4 OL-11175-01
Chapter 3 Cisco VoiceXML Applications
Hybrid Application

leg collectdigits leg_incoming param2 pattern

fsm setstate same_state
}
}

proc act_CallSetupDone { } {
global dest

set status [infotag get evt_status]

puts "DEBUGGING : act_CallSetupDone status is $status"
if { [infotag get evt_status] == "ls_000" } {
connection destroy con_all
} else {
# call setup fail
puts "DEBUGGING : Call Setup Failed, incoming disconnected "
call close
}
}

Procedure act_Playout
When the connection between the incoming and outgoing call legs is destroyed. The recording of the
calling party's name is played to the called party.
#

proc act_Playout {} {
global param

puts "DEBUGGING: In proc goto_Playout"

media play leg_outgoing $param(myrecord)
return
}

Procedure act_AnswerCall
The user is prompted to enter 1 to accept the call or 2 to reject the call.
#

proc act_AnswerCall { } {
global param4

set param4(maxDigits) 1
leg collectdigits leg_outgoing param4
media play leg_outgoing tftp://TFTP-SERVER/answercall.au
set event [infotag get evt_event]
puts "\n EVENT in act_AnswerCall is $event"
fsm setstate ACCEPTCALL

Procedure act_ApproveCall
This procedure handles the called party's decision to accept or reject the call. If the called party selects
1 (accepts the call), the state is set to CALLAPPROVED. If the called party selects 2 (reject the call),
the script will play a prompt to the calling party.
#

proc act_ApproveCall { } {

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-5
 Chapter 3 Cisco VoiceXML Applications
Hybrid Application

set event [infotag get evt_event]

puts "\n EVENT in act_ApproveCall is $event"
set status [infotag get evt_status]

#Collect Success ...matched pattern

if {$status == "cd_005"} {
set answer_call [infotag get evt_dcdigits]

if {$answer_call == 1} {
puts "USER ACCEPTS THE CALL"
fsm setstate CALLAPPROVED
} elseif {$answer_call == 2} {
media play leg_incoming tftp://TFTP-SERVER/reject_call.au
fsm setstate REJECTCALL
} else {
media play leg_outgoing tftp://TFTP-SERVER/wrong_selection.au
fsm setstate WRONGSELECTION
}
}
}

Procedure act_Bridge
This procedure connects (bridges) the incoming and outgoing call legs if the called party accepts the call.
#
proc act_Bridge { } {

puts "DEBUGGING: in act_Bridge"

set ev [infotag get evt_event]
puts "DEBUGGING: in act_Bridge event is $ev"

set status [infotag get evt_status]

puts "DEBUGGING: in act_Bridge status is $status"

connection create leg_incoming leg_outgoing

set connectionID [infotag get con_ofleg leg_outgoing]
puts "\n connectionID in act_Bridge:$connectionID"
fsm setstate CONF_BRIDGING

proc act_Nothing { } {

proc act_Bridged { } {

Procedure act_UnBridge
This procedure destroys the connection between the incoming and outgoing call legs if the called party
rejects the call.

proc act_UnBridge { } {
connection destroy con_all
}

proc act_Ignore { } {
# Dummy
puts "Event Capture"

Cisco VoiceXML Programmer’s Guide

3-6 OL-11175-01
 Chapter 3 Cisco VoiceXML Applications
Speech Enabled Banking Application

proc act_Cleanup { } {

puts "DEBUGGING: in act_Cleanup"

call close
}

requiredversion 2.0
init

#----------------------------------
# State Machine
#----------------------------------
set fsm(any_state,ev_disconnected) "act_Cleanup same_state"
set fsm(CALL_INIT,ev_setup_indication) "act_RecordGreeting RECORD"
set fsm(RECORD,ev_vxmldialog_done) "act_GetDest GETDEST"
set fsm(GETDEST,ev_collectdigits_done) "act_GetDestDone GETPASSWD"
set fsm(GETDEST,ev_media_done) "act_Nothing same_state"
set fsm(GETPASSWD,ev_media_done) "act_Nothing same_state"
set fsm(GETPASSWD,ev_collectdigits_done) "act_GetPasswdDone PLACECALL"
set fsm(PLACECALL,ev_media_done) "act_Nothing same_state"
set fsm(PLACECALL,ev_setup_done) "act_CallSetupDone CONF_BREAKING"
set fsm(CONF_BREAKING,ev_destroy_done) "act_Playout PLAYOUT"
set fsm(PLAYOUT,ev_media_done) "act_AnswerCall COLLECTANSWER"
set fsm(REJECTCALL,ev_media_done) "act_Cleanup same_state"
set fsm(WRONGSELECTION,ev_media_done) "act_AnswerCall COLLECTANSWER"
set fsm(ACCEPTCALL,ev_collectdigits_done) "act_ApproveCall CALLAPPROVED"
set fsm(CALLAPPROVED,ev_media_done) "act_Bridge CONF_BRIDGING"
set fsm(CONF_BRIDGING,ev_create_done) "act_Bridged CALLACTIVE"
set fsm(CALLACTIVE,ev_disconnected) "act_Cleanup same_state"
set fsm(CALLDISCONNECT,ev_media_done) "act_Cleanup same_state"
set fsm(CALLDISCONNECT,ev_disconnect_done) "act_Cleanup same_state"
set fsm(CALLDISCONNECT,ev_leg_timer) "act_Cleanup same_state"

fsm define fsm CALL_INIT

Speech Enabled Banking Application

The speech enabled banking application demonstrates the ability to check balances, deposit, withdraw,
and transfer funds using speech input. User authenticate, when you first launch the application you will
hear a prompt that says, “ please enter your account number.” After it collects your spoken input, it asks
for your pin number. After collecting your pin and account number, the application requests an
authorization from the RADIUS server.

User Authentication

The userauthenticate.vxml script collects your account and pin numbers, and authorizes you to perform
transactions.
<?xml version="1.0"?>
<vxml version="2.0" application="root.vxml">

<catch event="error.com.cisco.aaa.authorize.failure">
#Denotes an authorization failure.
<prompt> Radius Server error. </prompt>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-7
 Chapter 3 Cisco VoiceXML Applications
Speech Enabled Banking Application

</catch>

<form id="userAuthentication" scope="document">

<property name="timeout" value="10s"/>

<field name="accountNumber" type="digits?length=6">

<prompt> Please enter or say your account number </prompt>
<filled>
<log> Account is <value expr="accountNumber"/></log>
<log>Confidence: <value expr="accountNumber$.confidence"/> </log>
<log>Utterance: <value expr="accountNumber$.utterance"/> </log>
<log>Inputmode: <value expr="accountNumber$.inputmode"/> </log>
</filled>
</field>

<field name="pinNumber" type="digits?length=4">

<prompt> Please enter or say your pin number </prompt>
<filled>
<log> Pin is <value expr="pinNumber"/></log>
</filled>
</field>

<!--filled mode="all" namelist="accountNumber pinNumber ">

<prompt> it works </prompt>
</filled-->
<object
name="authorize"
classid="builtin://com.cisco.aaa.authorize">
#The aaa authorize command implemented through <object>, sends a RADIUS authentication or
authorization request, and allows the script to retrieve information that the RADIUS
server includes in its response.
<param name="account" expr="'accountNumber'"/>
<param name="password" expr="'pinNumber'"/>
</object>

<filled>
<log>DEBUG: got authorize result as <value expr="authorize.result"/> </log>
<if cond="authorize.result=='fail'">
<log>DEBUG: Authentication failed due to <value
expr="authorize.attributes.h323_return_code"/></log>
<prompt> Your account and pin did not match. </prompt>
<clear namelist="accountNumber pinNumber"/>
<goto nextitem="userAuthentication"/>
<else/>
<goto next="menu.vxml"/>
</if>
</filled>

</form>
</vxml>

Menu

The menu.vxml script provides a menu of transaction options.

<?xml version="1.0"?>
<vxml version="2.0" application="root.vxml">

<catch count="1" event="nomatch">

<prompt>Please speak clearly. Select Deposit, Withdrawal, Check Balance, Transfer
Funds or Repeat Menu </prompt>
</catch>

Cisco VoiceXML Programmer’s Guide

3-8 OL-11175-01
 Chapter 3 Cisco VoiceXML Applications
Speech Enabled Banking Application

<catch count="1" event="noinput">

<prompt>You must make a selection </prompt>
</catch>

<help> If you would like to deposit, say deposit. For withdrawal, say withdrawal. To
transfer funds, say transfer funds. To check balance, say check balance. </help>

<catch count="3" event="nomatch noinput">

<prompt> Sorry, please try again later </prompt>
<exit/>
</catch>

<var name="transaction"/>
<menu id="transactionMenu" dtmf="true">
<prompt bargein="true" timeout="10ms">
Welcome to the AJAX Banking Application. Please choose from the following
choices. <enumerate/></prompt>

<choice caching="safe" next="deposit.vxml"> Deposit </choice>

<choice caching="safe" next="withdrawal.vxml"> Withdrawal </choice>
<choice caching="safe" next="checkBalance.vxml"> Check Balance </choice>
<choice caching="safe" next="transferFunds.vxml"> Transfer Funds </choice>
<choice caching="safe" next="menu.vxml"> Repeat Menu </choice>

</menu>
</vxml>

Withdrawal

The withdrawal.vxml script selects the account from which you want to withdraw, and allows you to
enter the withdrawal amount.
<?xml version="1.0"?>
<vxml version="2.0" application="root.vxml">

<form id="withdrawal_info" scope="document">

<field name="acctType">
<prompt>Please select the account you want to withdra from. Select one of the
following. <enumerate/> </prompt>
<option value="SAVINGS">Savings</option>
<option value="CHECKING">Checking</option>
<filled>
<log> ACCOUNT TO WITHDRAW FROM IS : <value expr="acctType"/></log>
<goto nextitem="withdrawalAmt"/>
</filled>
</field>

<field name="withdrawalAmt" type="currency" expr="0">

<prompt> Please say or enter the amount you want to withdraw </prompt>
<filled>
<if cond="withdrawalAmt == "0">
<prompt>Withdrawal amount cannot be zero. Please enter the amount you
want to withdrawal</prompt>
<clear namelist="withdrawalAmt"/>
<else/>
<log> DEPOSIT AMOUNTT IS <value expr="withdrawalAmt"/></log>
<prompt> withdrawal amount is <value expr="withdrawalAmt"/> </prompt>
<!--submit expr="webServer+'withdrawal'" method="get"
namelist="acctType withdrawalAmt"/-->
</if>
</filled>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-9
 Chapter 3 Cisco VoiceXML Applications
Speech Enabled Banking Application

</field>
</form>
</vxml>

Deposit

The deposit.vxml script selects the account to which you want to deposit, and allows you to enter the
deposit amount.
<?xml version="1.0"?>
<vxml version="2.0" application="root.vxml">

<form id="deposit_info" scope="document">

<field name="acctType">
<prompt>Please select Savings or checking account <enumerate/></prompt>
</prompt>
<option value="SAVINGS">Savings</option>
<option value="CHECKING">Checking</option>
<filled>
<log> ACCOUNT TO DEPOSIT TO IS <value expr="acctType"/></log>
<goto nextitem="depositAmt"/>
</filled>
</field>

<field name="depositAmt" type="number" expr="0">

<prompt>Please enter the amount you want to deposit </prompt>
<filled>
<if cond="depositAmt == '0'">
<prompt> Depositamount cannot be zero. Please enter the amount you want to
withdrawal</prompt>
<clear namelist="depositAmt"/> <else/>
<log> DEPOSIT AMOUNT is <value expr="depositAmt"/></log>
<else/>
<prompt> Deposit amount is <value expr="depositAmt"/> </prompt>
<!--submit expr="webServer+'deposit'" method="get" namelist="acctType
depositAmt"/-->
</if>
</filled>
</field>
</form>
</vxml>

Transfer of Funds

The transfer.vxml script allows you to transfer funds between accounts.

<?xml version="1.0"?>
<vxml version="2.0" application="root.vxml">

<form id="transfer_info" scope="document">

<field name="transType">
<prompt> Please say one of the following options <enumerate/><prompt>
<option value="SAVINGS_TO_CHECKING">Savings To Checking</option>
<option value="CHECKING_TO_SAVINGS">Checking To Savings</option>
<filled>
<log> TRANSFER FUNDS FROM : <value expr="transType"/></log>
<goto nextitem="transferAmt"/>
</filled>
</field>

<field name="transferAmt" type="number" expr="0">

Cisco VoiceXML Programmer’s Guide

3-10 OL-11175-01
 Chapter 3 Cisco VoiceXML Applications
Speech Enabled Banking Application

<prompt> Please say or enter the amount you want to deposit</ prompt>
<filled>
<if cond="transferAmt == '0'">
<prommpt>Transfer amount cannot be zero. Please enter the amount you
want to transfer</prompt>
<clear namelist="transferAmt"/>
<else/>
<log> TRANSFER AMOUNTT IS <value expr="transferAmt"/></log>
<!--submit expr="webServer+'transfer'" method="get"
namelist="transType transferAmt"/-->
<prompt> Transfer amount is <value expr="transferAmt"/> </prompt>
</if>
</filled>
</field>
</form>
</vxml>

Checking Balances

The checkbalance.vxml script allows you to check your account balances.

<?xml version="1.0"?>
<vxml version="2.0" application="root.vxml">

<form id="check_balance_info" scope="document">

<field name="acctType">
<prompt> Please select Savings account or Checking account </prompt>
<option value="SAVINGS">Savings</option>
<option value="CHECKING">Checking</option>
<filled>
<log> ACCOUNT TYPE IS <value expr="acctType"/></log>
<submit expr="webServer+'balance'" method="get" namelist="acctType"/>
</filled>
</field>
</form>
</vxml>

Root Document

The root.vxml script defines default application properties, error handlers, and link elements.
<?xml version="1.0"?>
<vxml version="2.0">
<meta http-equiv="Expires" content="Monday ,Dec 31 2002"/>

<property name="caching" value="safe"/>

<property name="fetchtimeout" value="5s"/>
<property name="timeout" value="3s"/>
<property name="interdigittimeout" value="2s"/>
<property name="termchar" value="#"/>
<property name="bargein" value="true"/>
<!--property name="inputmodes" value="dtmf"/-->

<var name="webServer" expr="'http://171.71.16.68:8081/vxml/servlet/'"/>

<catch event="error">
<prompt>We are having technical difficulties. </prompt> <reprompt/>
</catch>

<catch event="nomatch ">

<prompt>No Match </prompt><reprompt/>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-11
 Chapter 3 Cisco VoiceXML Applications
ASR and TTS Application

</catch>

<catch event ="noinput">

<prompt>No Input </prompt><reprompt/>
</catch>

<catch event ="noinput nomatch error" count="3">

<goto next="exit.vxml#finalExit"/>
</catch>

<link next="menu.vxml" dtmf="9"></link>

</vxml>

ASR and TTS Application

The script below is a sample application that illustrates automatic speech recognition (ASR) ,
text-to-speech (TTS) synthesis, and an outbound call using the the <transfer> element. It also verifies
configurations for the ASR and TTS servers and, inbound and outbound dial-peers.
When you dial into a Cisco AS5300 access server, a menu prompt plays, asking you to select 1 for the
phone demonstration and 2 for the music demonstration. You can make your selection by entering a
DTMF or voice input.
The phone demonstration prompts you to speak a person’s name. After matching your input to the
grammar specified in the form, the application dials a phone number associated with the matched name.
The music demonstration prompts you to speak an artist’s name. After matching your input, the
application plays an audio file.
To run this application, follow these steps:

Note For information on Cisco IOS configuration required for this application, refer to the Cisco IOS Tcl IVR
and VoiceXML Application Guide.

1. Load the VoiceXML script, sample.vxml into flash on the Cisco AS5300 access server.
2. Configure the Cisco AS5300.
3. Configure the ASR and TTS servers.
4. Configure the application.
5. Configure the inbound and outbound dial-peers for the call to be placed.

The application is triggered when you dial the access number to the Cisco AS5300.
<?xml version="1.0"?>
<vxml version="2.0">

<catch event="error">
<prompt> We are having technical difficulties, please try again later </prompt>
</catch>

<catch event="nomatch ">

Cisco VoiceXML Programmer’s Guide

3-12 OL-11175-01
Chapter 3 Cisco VoiceXML Applications
ASR and TTS Application

<prompt> That is an invalid selection. Please try again </prompt>

</catch>

<catch event ="noinput">

<prompt> We did not get your input. Please try again.</prompt>
</catch>

<catch event ="noinput nomatch error" count="3">

<prompt> Sorry, please try again later</prompt>
<exit/>
</catch>

<menu id="demo" dtmf="true">

<prompt> Please select 1 for Phone demo, select 2 for Music demo. </prompt>
<choice caching="safe" next="#phone"> one </choice>
<choice caching="safe" next="#music"> two </choice>
</menu>

<form id="phone">
<var name="phoneNum"/>
<var name="mydur"/>

<catch event="nomatch ">

<prompt> Please say another name</prompt>
</catch>

<catch event ="noinput">

<prompt> We did not get your input. Please say the name of the person you wish to
call</prompt>
</catch>

<field name="callee">
<prompt bargein="true"> Please say the name of the person you wish to call, Peter,
Jane or Jacob </prompt>

<grammar version="1.0" xml:lang="en-us" root="place">

<rule id="place" scope="public">
<one-of>
<item> peter </item>
<item> jane </item>
<item> jacob </item>
</one-of>
</rule>
</grammar>

<filled>
<if cond="callee=='peter'">
<assign name="phoneNum" expr="'5241111'"/>
<elseif cond="callee=='jane'"/>
<assign name="phoneNum" expr="'5243333'"/>
<elseif cond="callee=='jacob'"/>
<assign name="phoneNum" expr="'5245555'"/>
</if>
<prompt> Calling <value expr="callee"/>now</prompt>
</filled>
</field>

<transfer name="mycall" destexpr="'phone://'+ phoneNum" bridge="true"

connecttimeout="15s" maxtime="180s" cisco-longpound ="true">
<filled>
<assign name="mydur" expr="mycall$.duration"/>
<if cond = "mycall == 'busy'">

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-13
 Chapter 3 Cisco VoiceXML Applications
ASR and TTS Application

<prompt> Called party is busy </prompt>

<log>Status of transfer is BUSY</log>
<elseif cond = "mycall == 'noanswer'"/>
<prompt> Called party is is not answering </prompt>
<log>Status of transfer is NO_ANSWER</log>
<elseif cond = "mycall == 'near_end_disconnect'"/>
<log>Status of transfer is NEAR_END_DISCONNECT</log>
<elseif cond = "mycall == 'far_end_disconnect'"/>
<prompt> Called party disconnected </prompt>
<log>Status of transfer is FAR_END_DISCONNECT</log>
<elseif cond = "mycall == 'unknown'"/>
<prompt> Called transfer failed </prompt>
</if>

<log>The value in mycall is <value expr="mycall"/></log>

<log>Duration of call is <value expr="mydur"/></log>
</filled>
</transfer>
</form>

<form id="music">
<catch event="nomatch ">
<prompt> Please say another artist's name</prompt>
</catch>

<catch event ="noinput">

<prompt> We did not get your input. Please say the name of the artist </prompt>
</catch>
<field name="performer">
<prompt bargein="false">Please say the name of the artist Madonna, Bon Jovi or
Aqua </prompt>

<grammar version="1.0" xml:lang="en-us" root="place">

<rule id="place" scope="public">
<one-of>
<item> madonna </item>
<item> aqua </item>
<item> bon jovi</item>
</one-of>
</rule>
</grammar>

<filled>
<if cond="performer=='madonna'">
<prompt><audio src="audio/crazy.au"/></prompt>
<elseif cond="performer=='aqua'"/>
<prompt><audio src="audio/barbie.au"/></prompt>
<elseif cond="performer=='bon jovi'"/>
<prompt><audio src="audio/itsMyLife.au"/></prompt>
</if>
</filled>
</field>
</form>
</vxml>

Cisco VoiceXML Programmer’s Guide

3-14 OL-11175-01
Chapter 3 Cisco VoiceXML Applications
Multi-Language Application

Multi-Language Application
The following multi-language sample scripts are French and Mandarin.

French:
<?xml version="1.0"?>
<vxml version="2.0" xml:lang="fr" base="http://nuance-asr/recognizer">
<var name="number"/>
<form id="places">
<nomatch> Did not match </nomatch>
<property name="bargein" value="true"/>
<property name="timeout" value="10s"/>

<field name="name">
<prompt xml:lang="en-US"> Good Morning, Do you speak English? </prompt>
<prompt xml:lang="fr"> Bonjour, S'il vous plaît choisissez anglais ou
français</prompt>
<grammar version="1.0" root="name-choice" xml:lang="fr">
<rule id="name-choice" scope="public">
<one-of>
<item xml:lang="fr">bonjour</item>
<item xml:lang="en-US">welcome</item>
</one-of>
</rule>

</grammar>
<filled>

<prompt> You chose <value expr="name"/></prompt>

<if cond="name=='bonjour'">
<prompt xml:lang="fr"> Merci</prompt>
<elseif cond="name=='welcome'"/>
<prompt xml:lang="fr"> vous avez choisi l' anglais </prompt>

</if>
</filled>
</field>
</form>
</vxml>

Mandarin
<?xml version="1.0"?>
<vxml version="2.0" xml:lang="en-US" base="http://nuance-asr/recognizer">
<var name="number"/>
<form id="places">
<nomatch> Did not match </nomatch>
<property name="bargein" value="true"/>
<property name="timeout" value="10s"/>
<field name="name">
<grammar version="1.0" root="name-choice" xml:lang="ch">
<rule id="name-choice" scope="public">
<one-of>
<item xml:lang="ch">nv3 xue2</item>
<item xml:lang="ch">jue2 yuan2</item>
</one-of>
</rule>
</grammar>
<filled>
<prompt> You chose <value expr="name"/>
</prompt>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-15
 Chapter 3 Cisco VoiceXML Applications
Recording Application

</filled>
</field>
</form>
</vxml>

Recording Application
The recording application demonstrates recording of audio messages to different destination servers.

Note • When a user hangs up during recording, the recording terminates and a telephone.disconnect.hangup
event is thrown. The user must catch the disconnect event to continue playing prompts and
submitting recordings.
• For a RAM recording, the recording is accessible through the recording variable.
• For a streamed recording (such as HTTP, RTSP, SMTP) the recording is streamed directly to the
external server until the user hangs up. The recording terminates and a telephone.disconnect.hangup
event is thrown.

RAM Recording

The ram_rec.vxml prompts the user to record an audio message. The message is recorded to RAM on
the Cisco AS5300 universal access server. The recorded audio is played back and the user is prompted
to record another message.
<?xml version="1.0"?>
<vxml version="1.0">

<form id="record_to_ram">
<record name="myrec"
beep="true"
maxtime="10s"
dtmfterm="true"
finalsilence="10ms"
type="audio/basic;codec=g711ulaw">
<prompt><audio src="record.au"/></prompt>

<filled namelist="myrec">
<prompt><value expr="myrec"/></prompt>
<clear namelist="myrec"/>
</filled>
</record>
</form>
</vxml>

HTTP Recording

The http_rec.vxml script prompts the user to record an audio message to an HTTP server. To process the
recorded audio, the server-side script is specified in the cisco-dest attribute.
Modify the following to point to your server-side script:
cisco-dest= “http://myServer/record.php”
To playback the recorded audio, use the <audio> tag to specify the location of the recorded audio.

Cisco VoiceXML Programmer’s Guide

3-16 OL-11175-01
 Chapter 3 Cisco VoiceXML Applications
Recording Application

<?xml version="1.0"?>
<vxml version="1.0">

<form id="record_to_http">

<record name="myrec"
beep="true"
maxtime="15s"
finalsilence="10s"
dtmfterm="true"
type="audio/basic;codec=g711ulaw"
cisco-dest="http://myServer/saveRecording.php">
<prompt> <audio src="record.au"/></prompt>
</record>

<block>
<log> DURATION: <value expr="myrec$.duration"/></log>
<log> SIZE: <value expr="myrec$.size"/></log>
<log> CHAR: <value expr="myrec$.termchar"/></log>
</block>
</form>
</vxml>

SMTP Recording

The smtp_rec.vxml script prompts the user to record to an SMTP server. The location of the SMTP server
is specified in the cisco-dest attribute.
Modify the following to point to your SMTP server:
cisco-dest= “mailto:test@myserver”
The recorded audio is stored on the SMTP server.

Note Configure the mail transfer agent (MTA) prior to using this script. For information on configuring the
MTA, refer to the Cisco IOS Tcl IVR and VoiceXML Application Guide.

<?xml version="1.0"?>
<vxml version="1.0">

<form id="record_to_smtp">

<record name="myrec"
beep="true"
maxtime="15s"
dtmfterm="true"
type="audio/basic;
codec=g711ulaw"
cisco-dest="mailto:test@myserver">
#cisco-dest points to a URL specifying a recording destination.
<prompt><audio src="record.au"/></prompt>
</record>

<block>
<log> DURATION: <value expr="myrec$.duration"/> </log>
<log> SIZE: <value expr="myrec$.size"/> </log>
<log> CHAR: <value expr="myrec$.termchar"/> </log>
</block>
</form>
</vxml>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 3-17
 Chapter 3 Cisco VoiceXML Applications
Recording Application

Cisco VoiceXML Programmer’s Guide

3-18 OL-11175-01
 A P P E N D I X A
Cisco VoiceXML DTD

Revised: June 20, 2007, OL-11175-01

Cisco VoiceXML DTD

<!--
VoiceXML 2.1 DTD (20060322)

Copyright 1998-2006 W3C (MIT, ERCIM, Keio), All Rights Reserved.

Permission to use, copy, modify and distribute the VoiceXML DTD and
its accompanying documentation for any purpose and without fee is
hereby granted in perpetuity, provided that the above copyright
notice and this paragraph appear in all copies.

The copyright holders make no representation about the suitability

of the DTD for any purpose. It is provided "as is" without expressed
or implied warranty.
-->

<!ENTITY % audio "#PCDATA | audio | enumerate | value">

<!ENTITY % bargeintype "( speech | hotword )">
<!ENTITY % boolean "(true|false)">
<!ENTITY % content.type "CDATA">
<!ENTITY % duration "CDATA">
<!ENTITY % event.handler "catch | help | noinput | nomatch | error">
<!ENTITY % event.name "NMTOKEN">
<!ENTITY % event.names "NMTOKENS">
<!ENTITY % executable.content "%audio; | assign | clear | data | disconnect |
exit | foreach |goto | if | log | prompt |
reprompt | return | script | submit | throw | var | cisco-data | cisco-typeaheadflush
| cisco-debug ">
<!ENTITY % expression "CDATA">
<!ENTITY % restrictedvariable.name "CDATA">
<!ENTITY % variable.name "CDATA">
<!ENTITY % restrictedvariable.names "CDATA">
<!ENTITY % variable.names "CDATA">
<!ENTITY % integer "CDATA">
<!ENTITY % item.attrs "name %restrictedvariable.name; #IMPLIED
cond %expression; #IMPLIED
expr %expression; #IMPLIED ">
<!ENTITY % uri "CDATA">
<!ENTITY % cache.attrs "fetchhint (prefetch|safe) #IMPLIED
fetchtimeout %duration; #IMPLIED
maxage %integer; #IMPLIED
maxstale %integer; #IMPLIED">
<!ENTITY % next.attrs "next %uri; #IMPLIED

Cisco VoiceXML Programmer’s Guide

OL-11175-01 A-1
 Appendix A Cisco VoiceXML DTD

expr %expression; #IMPLIED ">

<!ENTITY % submit.attrs "method (get|post) 'get'
enctype %content.type; 'application/x-www-form-urlencoded'
namelist %variable.names; #IMPLIED">
<!ENTITY % throw.attrs "event %event.name; #IMPLIED
eventexpr %expression; #IMPLIED
message CDATA #IMPLIED
messageexpr %expression; #IMPLIED">
<!ENTITY % variable "block | data | field | var">
<!--================================= Root ================================-->
<!ELEMENT vxml (%event.handler; | data | form | link | menu | meta | metadata |
property | script | var | cisco-data)+>
<!ATTLIST vxml
application %uri; #IMPLIED
xml:base %uri; #IMPLIED
xml:lang NMTOKEN #IMPLIED
xmlns CDATA #FIXED 'http://www.w3.org/2001/vxml'
xmlns:xsi CDATA #IMPLIED
xsi:schemaLocation CDATA #IMPLIED
version CDATA #REQUIRED
>
<!ELEMENT meta EMPTY>
<!ATTLIST meta
name NMTOKEN #IMPLIED
content CDATA #REQUIRED
http-equiv NMTOKEN #IMPLIED
>

<!ELEMENT metadata ANY>

<!--================================ Prompts ==============================-->

<!-- definitions adapted from SSML 1.0 DTD -->
<!ENTITY % structure "p | s">
<!ENTITY % sentence-elements "break | emphasis | mark | phoneme | prosody |
say-as | voice | sub">
<!-- addition of enumerate and value elements as 'allowed-within-sentence'
audio elements -->
<!ENTITY % allowed-within-sentence " %audio; | %sentence-elements; ">

<!-- Prompt is modelled on SSML 1.0 DTD speak element:

- addition of 'bargein', 'bargeintype', 'cond', 'count' and 'timeout' attributes
- removal of xmlns, xmlns:xsi, and xsi:schemaLocation attributes
- version attribute fixed as "1.0"
-->
<!ELEMENT prompt (%allowed-within-sentence; | foreach | %structure; | lexicon
| metadata | meta )*>
<!ATTLIST prompt
bargein %boolean; #IMPLIED
bargeintype %bargeintype; #IMPLIED
cond %expression; #IMPLIED
count %integer; #IMPLIED
xml:lang NMTOKEN #IMPLIED
cisco-vcrprompt %boolean; #IMPLIED
cisco-rate %integer; #IMPLIED
cisco-typeaheadflush %boolean; false

timeout %duration; #IMPLIED

xml:base %uri; #IMPLIED
version CDATA #FIXED "1.0"
>
<!ELEMENT enumerate (%allowed-within-sentence; | %structure;)*>
<!ELEMENT reprompt EMPTY>

<!--================================= Dialogs =============================-->

Cisco VoiceXML Programmer’s Guide

A-2 OL-11175-01
Appendix A Cisco VoiceXML DTD

<!ENTITY % input "grammar">

<!ENTITY % scope "(document | dialog)">
<!ELEMENT form (%input; | %event.handler; | filled | initial | object | link |
property | record | script | subdialog | transfer | %variable |
cisco-vcrcontrol | cisco-data;)*>
<!ATTLIST form
id ID #IMPLIED
scope %scope; "dialog"
>
<!ENTITY % accept.attrs "accept (exact | approximate) 'exact'">
<!ELEMENT menu (%audio; | choice | %event.handler; | prompt | property |
cisco-vcrcontrol)*>
<!ATTLIST menu
id ID #IMPLIED
scope %scope; "dialog"
%accept.attrs;
dtmf %boolean; "false"
>
<!ELEMENT choice ( #PCDATA | %input; )*>
<!ATTLIST choice
%cache.attrs;
accept (exact | approximate) #IMPLIED
dtmf CDATA #IMPLIED
%throw.attrs;
fetchaudio %uri; #IMPLIED
%next.attrs;
>
<!--================================ Audio Output ==============================-->
<!-- definitions adapted from SSML 1.0 DTD -->
<!ELEMENT p (%allowed-within-sentence; | s)*>
<!ATTLIST p
xml:lang NMTOKEN #IMPLIED
>
<!ELEMENT s (%allowed-within-sentence;)*>
<!ATTLIST s
xml:lang NMTOKEN #IMPLIED
>
<!ELEMENT voice (%allowed-within-sentence; | %structure;)*>
<!ATTLIST voice
xml:lang NMTOKEN #IMPLIED
gender (male | female | neutral) #IMPLIED
age %integer; #IMPLIED
variant %integer; #IMPLIED
name CDATA #IMPLIED
>
<!ELEMENT prosody (%allowed-within-sentence; | %structure;)*>
<!ATTLIST prosody
pitch CDATA #IMPLIED
contour CDATA #IMPLIED
range CDATA #IMPLIED
rate CDATA #IMPLIED
duration %duration; #IMPLIED
volume CDATA #IMPLIED
>
<!-- Changes to SSML 1.0 DTD audio element:
- src not obligatory, addition of 'expr' and caching attributes
-->
<!ELEMENT audio (%allowed-within-sentence; | %structure; | desc)*>
<!ATTLIST audio
src %uri; #IMPLIED
expr %expression; #IMPLIED
%cache.attrs;
>
<!ELEMENT desc (#PCDATA)>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 A-3
 Appendix A Cisco VoiceXML DTD

<!ATTLIST desc
xml:lang NMTOKEN #IMPLIED
>
<!ELEMENT emphasis (%allowed-within-sentence;)*>
<!ATTLIST emphasis
level (strong | moderate | none | reduced) "moderate"
>
<!-- Changes to SSML 1.0 DTD say-as element:
- allows value element as child
-->
<!ELEMENT say-as (#PCDATA | value )*>
<!ATTLIST say-as
interpret-as NMTOKEN #REQUIRED
format NMTOKEN #IMPLIED
detail NMTOKEN #IMPLIED
>
<!ELEMENT sub (#PCDATA)>
<!ATTLIST sub
alias CDATA #REQUIRED
>
<!ELEMENT phoneme (#PCDATA)>
<!ATTLIST phoneme
ph CDATA #REQUIRED
alphabet CDATA #IMPLIED
>
<!ELEMENT break EMPTY>
<!ATTLIST break
time CDATA #IMPLIED
strength (none | x-weak | weak | medium | strong | x-strong) "medium"
>
<!ELEMENT mark EMPTY>
<!ATTLIST mark
name ID #IMPLIED
nameexpr %expression; #IMPLIED
>

<!--"cisco-vcrcontrol" can be in <form>, <menu> and form item (including <block>).-->

<!ELEMENT cisco-vcrcontrol EMPTY>
<!ATTLIST cisco-vcrcontrol
dtmf CDATA #IMPLIED
action (rate|volume) #REQUIRED
scope %scope; #IMPLIED
step %integer; #REQUIRED>

<!--================================ Fields ===============================-->

<!ELEMENT field (%audio; | %event.handler; | filled | %input; | link | option |
prompt | property | cisco-vcrcontrol)*>
<!ATTLIST field
%item.attrs;
type CDATA #IMPLIED
slot NMTOKEN #IMPLIED
modal %boolean; "false"
>
<!ELEMENT option (#PCDATA)>
<!ATTLIST option
%accept.attrs;
dtmf CDATA #IMPLIED
value CDATA #IMPLIED
>
<!ELEMENT var EMPTY>
<!ATTLIST var
name %restrictedvariable.name; #REQUIRED
expr %expression; #IMPLIED
>

Cisco VoiceXML Programmer’s Guide

A-4 OL-11175-01
Appendix A Cisco VoiceXML DTD

<!ELEMENT initial (%audio; | %event.handler; | link | prompt | property |

cisco-vcrcontrol)*>
<!ATTLIST initial
%item.attrs;
>
<!ELEMENT block (%executable.content; | cisco-vcrcontrol)*>
<!ATTLIST block
%item.attrs;
>
<!ELEMENT assign EMPTY>
<!ATTLIST assign
name %variable.name; #REQUIRED
expr %expression; #REQUIRED
>
<!ELEMENT clear EMPTY>
<!ATTLIST clear
namelist %variable.names; #IMPLIED
>
<!ELEMENT value EMPTY>
<!ATTLIST value
expr %expression; #REQUIRED
>
<!--================================== Events =============================-->
<!ENTITY % event.handler.attrs "count %integer; #IMPLIED
cond %expression; #IMPLIED">
<!ELEMENT catch (%executable.content;)*>
<!ATTLIST catch
event %event.names; #IMPLIED
%event.handler.attrs;
>
<!ELEMENT error (%executable.content;)*>
<!ATTLIST error
%event.handler.attrs;
>
<!ELEMENT help (%executable.content;)*>
<!ATTLIST help
%event.handler.attrs;
>
<!ELEMENT link (%input;)*>
<!ATTLIST link
%cache.attrs;
%next.attrs;
fetchaudio %uri; #IMPLIED
dtmf CDATA #IMPLIED
%throw.attrs;
>
<!ELEMENT noinput (%executable.content;)*>
<!ATTLIST noinput
%event.handler.attrs;
>
<!ELEMENT nomatch (%executable.content;)*>
<!ATTLIST nomatch
%event.handler.attrs;
>
<!ELEMENT throw EMPTY>
<!ATTLIST throw
%throw.attrs;
>
<!--============================= Grammar Input =============================-->
<!-- definitions adapted from SRGS 1.0 DTD -->
<!ENTITY % rule-expansion "#PCDATA | token | ruleref
| item | one-of | tag ">
<!ELEMENT ruleref EMPTY>
<!ATTLIST ruleref

Cisco VoiceXML Programmer’s Guide

OL-11175-01 A-5
 Appendix A Cisco VoiceXML DTD

uri %uri; #IMPLIED

type CDATA #IMPLIED
special (NULL | VOID | GARBAGE) #IMPLIED
>
<!ELEMENT token (#PCDATA)>
<!ATTLIST token
xml:lang NMTOKEN #IMPLIED
>
<!ELEMENT tag (#PCDATA)>
<!ELEMENT one-of (item)+>
<!ATTLIST one-of
xml:lang NMTOKEN #IMPLIED
>
<!ELEMENT item (%rule-expansion;)*>
<!ATTLIST item
repeat NMTOKEN #IMPLIED
repeat-prob NMTOKEN #IMPLIED
weight NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
>
<!ELEMENT rule (%rule-expansion; | example)*>
<!ATTLIST rule
id ID #REQUIRED
scope (private | public) "private"
>
<!ELEMENT example (#PCDATA)>
<!ELEMENT lexicon EMPTY>
<!ATTLIST lexicon
uri %uri; #REQUIRED
type CDATA #IMPLIED
>
<!-- Changes to SRGS 1.0 DTD grammar element:
- mixed, unordered content model
- addition of 'scope', 'src', 'type', 'weight' and caching attributes
- 'version' attribute is optional
- removal of xmlns, xmlns:xsi, and xsi:schemaLocation attributes
-->
<!ELEMENT grammar (#PCDATA | meta | metadata | lexicon | rule | tag)*>
<!ATTLIST grammar
scope %scope; #IMPLIED
src %uri; #IMPLIED
srcexpr %expression; #IMPLIED
type CDATA #IMPLIED
weight CDATA #IMPLIED
%cache.attrs;
tag-format %uri; #IMPLIED
xml:base %uri; #IMPLIED
version NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
root IDREF #IMPLIED
mode (voice | dtmf) "voice"
>
<!--============================= Audio Input =============================-->
<!ELEMENT record (%audio; | %event.handler; | filled | %input; | prompt |
Property | cisco-vcrcontrol)*>
<!ATTLIST record
%item.attrs;
type CDATA #IMPLIED
beep %boolean; "false"
maxtime %duration; #IMPLIED
modal %boolean; "true"
finalsilence %duration; #IMPLIED
dtmfterm %boolean; "true"
cisco-recordbeep %boolean; "false"

Cisco VoiceXML Programmer’s Guide

A-6 OL-11175-01
Appendix A Cisco VoiceXML DTD

cisco-recordbeepinterval %duration; #IMPLIED

cisco-dest %uri; #IMPLIED
cisco-destexpr %expression; #IMPLIED

>
<!--============================ Call Control ============================-->
<!ELEMENT disconnect EMPTY>
<!ATTLIST disconnect
namelist %variable.names; #IMPLIED
cisco-gtd expression; #IMPLIED
cisco-disc_cause expression; #IMPLIED

>

<!ELEMENT transfer (%audio; | %event.handler; | filled | %input; | prompt |

Property | cisco-vcrcontrol)*>
<!ATTLIST transfer
%item.attrs;
dest %uri; #IMPLIED
destexpr %expression; #IMPLIED
bridge %boolean; #IMPLIED
type NMTOKEN #IMPLIED
connecttimeout %duration; #IMPLIED
maxtime %duration; #IMPLIED
transferaudio %uri; #IMPLIED
aai CDATA #IMPLIED
aaiexpr %expression; #IMPLIED
cisco-longpound %boolean; 'true'
cisco-newguid %expression; #IMPLIED
cisco-mailtoaddress %expression; #IMPLIED
cisco-username %expression; #IMPLIED
cisco-destplan %integer; #IMPLIED
cisco-desttype %integer; #IMPLIED
cisco-ani %uri; #IMPLIED
cisco-aniexpr %expression; #IMPLIED
cisco-anitype %integer; #IMPLIED
cisco-aniplan %integer; #IMPLIED
cisco-anipi %integer; #IMPLIED
cisco-anisi %integer; #IMPLIED
cisco-rdn %uri; #IMPLIED
cisco-rdnexpr %expression; #IMPLIED
cisco-rdntype %integer; #IMPLIED
cisco-rdnplan %integer; #IMPLIED
cisco-rdnpi %integer; #IMPLIED
cisco-rdnsi %integer; #IMPLIED
cisco-redirectreason %integer; #IMPLIED
cisco-handoffexpr %expression; #IMPLIED
cisco-gtd %expression; #IMPLIED
cisco-carrierid-source %expression; #IMPLIED
cisco-carrierid-target %expression; #IMPLIED

>
<!--============================ Control Flow ============================-->
<!ENTITY % if.attrs "cond %expression; #REQUIRED">
<!ELEMENT if (%executable.content; | elseif | else)*>
<!ATTLIST if
%if.attrs;
>
<!ELEMENT elseif EMPTY>
<!ATTLIST elseif
%if.attrs;
>
<!ELEMENT else EMPTY>
<!ELEMENT exit EMPTY>

Cisco VoiceXML Programmer’s Guide

OL-11175-01 A-7
 Appendix A Cisco VoiceXML DTD

<!ATTLIST exit
expr %expression; #IMPLIED
namelist %variable.names; #IMPLIED
>
<!ELEMENT filled (%executable.content;)*>
<!ATTLIST filled
mode (any | all) #IMPLIED
namelist %restrictedvariable.names; #IMPLIED
>

<!-- executable content + contents of prompt -->

<!ELEMENT foreach (%executable.content; | %sentence-elements; |
%structure; | cisco-vcrcontrol )*
>
<!ATTLIST foreach
item %restrictedvariable.name; #REQUIRED
array CDATA #REQUIRED
>

<!ELEMENT goto EMPTY>

<!ATTLIST goto
%cache.attrs;
%next.attrs;
fetchaudio %uri; #IMPLIED
expritem %expression; #IMPLIED
nextitem %restrictedvariable.name; #IMPLIED
>
<!ELEMENT param EMPTY>
<!ATTLIST param
name NMTOKEN #REQUIRED
expr %expression; #IMPLIED
value CDATA #IMPLIED
valuetype (data | ref) "data"
type CDATA #IMPLIED
>
<!ELEMENT return EMPTY>
<!ATTLIST return
namelist %variable.names; #IMPLIED
%throw.attrs;
>
<!ELEMENT subdialog (%audio; | %event.handler; | filled | param | prompt |
Property | cisco-vcrcontrol)*>
<!ATTLIST subdialog
%item.attrs;
src %uri; #IMPLIED
srcexpr %expression; #IMPLIED
%cache.attrs;
fetchaudio %uri; #IMPLIED
%submit.attrs;
>
<!ELEMENT submit EMPTY>
<!ATTLIST submit
%cache.attrs;
%next.attrs;
fetchaudio %uri; #IMPLIED
%submit.attrs;
>
<!--========================== Miscellaneous ==============================-->
<!ELEMENT data EMPTY>
<!ATTLIST data
name %restrictedvariable.name; #IMPLIED
src %uri; #IMPLIED
srcexpr %expression; #IMPLIED
fetchaudio %uri; #IMPLIED

Cisco VoiceXML Programmer’s Guide

A-8 OL-11175-01
Appendix A Cisco VoiceXML DTD

%submit.attrs;
%cache.attrs;
>

<!ELEMENT log (#PCDATA | value)*>

<!ATTLIST log
label CDATA #IMPLIED
expr %expression; #IMPLIED
>
<!ELEMENT object (%audio; | %event.handler; | filled | param | prompt |
Property | cisco-vcrcontrol)*>
<!ATTLIST object
%item.attrs;
%cache.attrs;
classid %uri; #IMPLIED
codebase %uri; #IMPLIED
data %uri; #IMPLIED
type CDATA #IMPLIED
codetype CDATA #IMPLIED
archive %uri; #IMPLIED
>
<!ELEMENT property EMPTY>
<!ATTLIST property
name NMTOKEN #REQUIRED
value CDATA #REQUIRED
>
<!ELEMENT script (#PCDATA)>
<!ATTLIST script
src %uri; #IMPLIED
srcexpr %expression; #IMPLIED
charset CDATA #IMPLIED
%cache.attrs;
>

<!ELEMENT cisco-data EMPTY>

<!ATTRLIST cisco-data
src %uri #IMPLIED
name %restrictedvariable.name; #REQUIRED
expr %expression; #IMPLIED
srcexpr %expression; #IMPLIED
fetchaudio %uri; #IMPLIED
%cache.attrs;
%submit.attrs; >

< !ELEMENT cisco-debug EMPTY >

< !ATTLIST cisco-debug
enabled %boolean; #REQUIRED >

< !ELEMENT cisco-typeaheadflush EMPTY >

Cisco VoiceXML Programmer’s Guide

OL-11175-01 A-9
 Appendix A Cisco VoiceXML DTD

Cisco VoiceXML Programmer’s Guide

A-10 OL-11175-01
 A P P E N D I X B
Cisco VoiceXML Elements: Reference Table

Revised: October 2, 2009, OL-11175-01

This appendix contains Table B-1, the VoiceXML elements used by Cisco VoiceXML, and summarizes
the elements and their attributes, and their corresponding parent and children elements in the
VoiceXML 2.1 W3C Candidate Recommendation (June 13, 2005) in alphabetical order.

Note If an unsupported element is used in a VoiceXML document, an error event is generated. However, there
is a subset of unsupported elements which are ignored and for which error events are generated.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-1
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table

Element Attributes Parents Children Notes

<assign> name block No children Supported by Cisco VoiceXML.
expr catch
error
filled
help
if
noinput
nomatch
<audio> src block audio • Audio file formats supported are
fetchtimeout catch break audio/basic and audio/wav.
fetchhint choice emphasis • A uniform resource identifier (URI) in
maxage emphasis enumerate the <audio src> element can point to a
maxstale error mark block of speech markup data, but such
expr field p support is dependent on, and
filled paragraph conditional to the vendor’s decision of
help phoneme where the <audio src> element can
if prosody point.
initial s
menu say-as • The following codecs are supported
noinput sentence for each file format:
nomatch value – g711alaw
object voice
p #pcdata – g711ulaw
paragraph – g726r32
prosody
– g726r24
record
s – g726r16
sentence – g728
subdialog
transfer – g729r8
voice – g729abr8
– g729ar8
– g729br8
– g723r63
– g723ar63
– g723r53
– g723ar53
The default codec is g729ar8.

Cisco VoiceXML Programmer’s Guide

B-2 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<block> name form pcdata Supported by Cisco VoiceXML.
expr assign
cond audio
cisco-typeaheadflush
clear
disconnect
enumerate
exit
goto
if
log
prompt
reprompt
return
script
submit
throw
var
value
#pcdata
<catch> event field assign Supported by Cisco VoiceXML.
count form audio
cond initial cisco-typeaheadflush
menu clear
object disconnect
record enumerate
subdialog exit
transfer goto
vxml if
log
prompt
reprompt
return
script
submit
throw
var
value
#pcdata

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-3
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<choice> dtmf menu audio Supported by Cisco VoiceXML.
accept break
next emphasis
expr enumerate
fetchaudio grammar
fetchhint mark
fetchtimeout p
maxage paragraph
maxstale phoneme
prosody
s
say-as
sentence
value
voice
#pcdata

Cisco VoiceXML Programmer’s Guide

B-4 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<cisco-vcrcontrol> action — — • <cisco-vcrcontrol> is used to control
dtmf the volume and rate of audio playback.
step • Grammar support is only for in-line
scope DTMF grammar. External and ASR
grammar is not supported. If <prompt>
is the executable content, <cisco-
vcrcontrol> grammar can be activated
even if the input grammar is not
activated.
• TTS is not supported.
• If the input accepted is not for
<cisco-vcrcontrol>, the DTMF digits
are are saved to a typeahead buffer.
• The value for the attribute scope is
document or dialog. If scope is set to
document, <cisco-vcrcontrol> is
active in all dialogs of the current
document and the applicable leaf
document. If scope is set to dialog,
<cisco-vcrcontrol> is active
throughout the current form. If the
value for scope is omitted, the attribute
scope is resolved by the parent
element.
• Scope of <vcrcontrol> is applicable
instead of scope of the grammar.
• The attribute dtmf specifies the DTMF
sequence for <cisco-vcrcontrol>. It
does not take a regular expression. The
value for dtmf is a single digit.
• The value for the attribute action is
rate or volume.
• The attribute step changes the playout
rate for rate control, and and the
playout volume for volume control.
<clear> namelist block — Supported by Cisco VoiceXML.
catch
error
filled
help
if
noinput
nomatch

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-5
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<data> src block — W3C Document Object Model (DOM) is
name catch not supported. If the name attribute is set,
srcexpr error an error.unsupported.data.name event is
method filled thrown.
namelist foreach
enctype form
fetchaudio help
fetchint if
fetchtimeout noinput
maxage nomatch
maxstale vxml
<disconnect> cisco-gtd block — Supported by Cisco VoiceXML. For more
namelist catch information on the attribute cisco-gtd, see
error the “Using <transfer> and <disconnect>
filled for GTD Manipulation” section on
help page 1-109 in Chapter 1, “Cisco
if VoiceXML Features.”
noinput
nomatch
<else> no attributes if — Supported by Cisco VoiceXML.
<elseif> cond if — Supported by Cisco VoiceXML.
<enumerate> no attributes block audio Supported by Cisco VoiceXML.
catch break
choice emphasis
emphasis enumerate
error mark
field p
filled paragraph
help phoneme
if prosody
initial s
menu say-as
noinput sentence
nomatch value
object voice
p #pcdata
paragraph
prosody
record
s
sentence
subdialog
transfer
voice

Cisco VoiceXML Programmer’s Guide

B-6 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<error> count field exit Supported by Cisco VoiceXML.
cond form goto
initial if
menu log
object prompt
record reprompt
subdialog return
transfer script
vxml submit
throw
var
value
#pcdata
<exit> expr block — Supported by Cisco VoiceXML.
namelist catch
error
filled
help
if
noinput
nomatch
<field> name form audio Supported by Cisco VoiceXML.
expr catch
cond enumerate
type error
slot filled
modal grammar
help
link
noinput
nomatch
option
prompt
property
value
#pcdata

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-7
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<filled> mode field assign Supported by Cisco VoiceXML.
namelist form cisco-typeaheadflush
clear
disconnect
enumerate
exit
goto
if
log
object
prompt
record
reprompt
return
script
subdialog
submit
throw
transfer
var
value
#pcdata

Cisco VoiceXML Programmer’s Guide

B-8 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<foreach> array block audio Supported by Cisco VoiceXML.
item catch assign
error clear
filled data
help disconnect
if exit
noinput foreach
nomatch goto
prompt if
log
metadata
prompt
reprompt
return
script
submit
throw
var
p
s
break
emphasis
mark
phoneme
prosody
say-as
voice
sub
<form> id vxml block Supported by Cisco VoiceXML.
scope catch
error
field
filled
grammar
help
initial
link
noinput
nomatch
object
property
record
script
subdialog
transfer
var

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-9
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<goto> next block — Supported by Cisco VoiceXML.
expr catch
nextitem error
expritem filled
fetchaudio help
fetchhint if
fetchtimeout noinput
maxage nomatch
maxstale
<grammar> xml:lang choice import • The attribute weight is ignored.
src field metadata
• Cisco supports XML and regular
scope form rule
expression (regex) grammars.
type link #pcdata
mode record – Cisco supports Nuance extensions
root transfer for XML grammar.
version – Cisco supports regex grammar for
weight DTMF input. See the “Grammar
fetchhint Support” section on page 1-23 in
maxage Chapter 1, “Cisco VoiceXML
maxstale Features” for details.
ruleref
tag-format • The attribute xml:base declares the
xml:base base URI from which relative URIs in
srcexpr the <grammar> element are resolved.
This base declaration has precedence
over the <vxml> base URI declaration.
If a local declaration is omitted, the
value is inherited down the document
hierarchy.
<help> count field audio Supported by Cisco VoiceXML.
cond form asign
initial cisco-typeaheadflush
menu clear
object disconnect
record enumerate
subdialog exit
transfer goto
vxml if
log
prompt
reprompt
return
script
submit
throw
var
value
#pcdata

Cisco VoiceXML Programmer’s Guide

B-10 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<if> cond block assign Supported by Cisco VoiceXML.
catch audio
error cisco-typeaheadflush
filled clear
help disconnect
noinput else
nomatch elseif
enumerate
exit
goto
if
prompt
reprompt
return
script
submit
throw
value
var
#pcdata
<initial> name form audio Supported by Cisco VoiceXML.
expr catch
cond enumerate
error
help
link
noinput
nomatch
prompt
property
value
#pcdata
<link> next field grammar Supported by Cisco VoiceXML.
expr form
event initial
dtmf vxml
fetchaudio
fetchhint
fetchtimeout
maxage
maxstale

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-11
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<log> label block value Supported by Cisco VoiceXML.
expr catch #pcdata
error
filled
help
if
noinput
nomatch
<mark> nameexpr — — Supported by Cisco VoiceXML.
<menu> id vxml audio Supported by Cisco VoiceXML.
scope catch
dtmf choice
accept data
enumerate
error
help
noinput
nomatch
prompt
property
value
#pcdata
<meta> name vxml — Supported by Cisco VoiceXML.
content
http-equiv
<metadata> foreach any element Supported by Cisco VoiceXML.
grammar
prompt
vxml
<noinput> count field audio Supported by Cisco VoiceXML.
cond form assign
initial cisco-typeaheadflush
menu clear
object disconnect
record enumerate
subdialog exit
transfer goto
vxml if
log
prompt
reprompt
return
script
submit
throw
var
value
#pcdata

Cisco VoiceXML Programmer’s Guide

B-12 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<nomatch> count field audio Supported by Cisco VoiceXML.
cond form assign
initial cisco-typeaheadflush
menu clear
object disconnect
record enumerate
subdialog exit
transfer goto
vxml if
log
prompt
reprompt
return
script
submit
throw
var
value
#pcdata
<object> name form audio • Supported by Cisco VoiceXML.
expr catch
• Cisco objects are:
cond enumerate
classid error – Authorization
codebase filled – Authentication
codetype help
data noinput – Handoff
type nomatch – Sentevent
archive param
fetchhint prompt
fetchtimeout property
maxage value
maxstale #pcdata
<option> dtmf field #pcdata Supported by Cisco VoiceXML.
value
accept
<param> name object — Supported by Cisco VoiceXML.
expr subdialog
value
vlauetype
type

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-13
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<prompt> bargein block audio • The hotword value of the bargeintype
bargeintype catch break attribute is only supported through
cond error emphasis Media Resource Control Protocol
cont field enumerate version 2 (MRCP v2) which is
timeout filled foreach supported in Cisco IOS Release
xml:lang help mark 12.4(15)T and later releases.
cisco-vcrprompt if metadata • SSML elements are supported by the
cisco-rate initial p ASR and TTS servers.
xml:base menu paragraph
cisco-maxtime noinput phoneme • The attribute cisco-vcrprompt must be
nomatch prosody set to TRUE before using the
object s <cisco-vcrcontrol> element to control
record say-as the volume and rate of audio playback.
subdialog sentence The default value is FALSE.
transfer value • The attribute cisco-rate is the playout
voice rate. The absolute value ranges from -4
#pcdata to +4.
• The attribute cisco-maxtime is the
playout time for Real-Time Streaming
Protocol (RTSP) live streaming in
seconds. Values range from 0 to
43200. Live streaming stops when
cisco-maxtime expires or bargein
occurs. If cisco-maxtime is zero or no
value is set, live streaming plays
indefinitely.

Cisco VoiceXML Programmer’s Guide

B-14 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<property> name field — • The following properties are not
value form supported:
initial – maxspeechtimeout
menu
object – bargeintype
record – audiofetchhint
subdialog
transfer – documentfetchhint
vxml – grammarfetchhint
– grammarmaxage
– grammarmaxstale
– objectfetchhint
– objectmaxage
– objectmaxstale
– scriptfetchhint
• The following specific Cisco
properties are supported:
– com.cisco.tts-server
– com.cisco.asr-server
– com.cisco.asr-builtin-grammar
– com.cisco.media-logging-id
– com.cisco.record_maxtime
– com.cisco.record_type
– com.cisco.record_finalsilence
– com.cisco.mta.send.mdn_username
– com.cisco.mta.send.mdn_hostname
– com.cisco.mta.send.from_username
– com.cisco.mta.send.from_hostname
– com.cisco.mta.send.server
– com.cisco.mta.send.subject
– com.cisco.mta.send.origin_prefix
– com.cisco.mta.send.dsn_delay
– com.cisco.mta.send.dsn_failure
– com.cisco.mta.send.dsn_success

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-15
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

• The recordutterance property is not
supported for <record> and
<transfer>. The recordutterance
property requires an HTTP server on
your automatic speech recognition
(ASR) server. You must install and start
your HTTP server before the
recordutterance property can be
supported

Cisco VoiceXML Programmer’s Guide

B-16 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<record> name form audio • Cisco extension is cisco-destexpr.
expr catch • The finalsilence attribute specifies the
cond enumerate waiting time in seconds for the
modal error gateway before terminating the
beep filled recording. A non-zero value of final
maxtime grammar silence, which is the default value,
finalsilence help indicates no silence detection.
dtmfterm noinput
type nomatch Note Voice activation detection (VAD)
dest prompt must be enabled on the VoIP dial
cisco-recordbeep property peer when final silence detection is
cisco-recordbeepinterval value needed to terminate a voice
#pcdata recording. See the Cisco IOS TCL
and VoiceXML Application Guide
for your Cisco IOS software
release for details.

• The name$.dest shadow variable is not

supported.
• Voice recording supports the following
codecs:
– g711 u-law
– g723.1
• The attribute cisco-recordbeep is a
boolean variable. When the value is set
to “true,” a beep sound is sent back to
the user every x seconds during
recording. The number of seconds
between beeps is specified in the
cisco-recordbeep interval attribute.
Note All codecs are supported on the
PSTN call leg. The G.711 u-law,
G.711 a-law, G.729r8, G.723r53,
and G.723r63 codecs only are
supported on the VoIP call leg.

• The attribute cisco-recordbeepinterval

is the time in seconds to specify the
interval between beeps for
cisco-recordbeep attribute. The default
and maximum value is 15 sec; the
minimum value is 5 sec. If a value
smaller than the minimum is specified,
it will be changed to the minimum
value. If a value greater than the
maximum is specified, it will be
changed to the maximum value.

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-17
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<reprompt> no attributes — — Supported by Cisco VoiceXML.
<return> event block — Supported by Cisco VoiceXML.
namelist catch
error
filled
help
if
noinput
nomatch
<script> src block #pcdata Supported by Cisco VoiceXML.
charset catch
fetchhint error
fetchtimeout filled
maxage form
maxstale help
srcexpr if
noinput
nomatch
vxml
<subdialog> name form audio Supported by Cisco VoiceXML.
expr catch
cond enumerate
namelist error
src filled
method help
enctype noinput
fetchaudio nomatch
fetchtimeout param
fetchhint prompt
maxage property
maxstale value
#pcdata
<submit> next block — To submit a RAM recording to an external
express catch server with the POST method, the enctype
namelist error must be multipart/form-data.
method filled
enctype help
fetchaudio if
fetchhint noinput
fetchtimeout nomatch
maxage
maxstale

Cisco VoiceXML Programmer’s Guide

B-18 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<throw> event block — Supported by Cisco VoiceXML.
eventexpr catch
message error
messageexpr filed
help
if
noinput
nomatch
<transfer> name form audio • A Cisco feature is the implementation
expr catch of Cisco longpound (long-#) attribute.
cond enumerate
• For more information on the attribute
dest error
cisco-gtd, see the “Using <transfer>
destexpr filled
and <disconnect> for GTD
bridge grammar
Manipulation” section on page 1-109
connecttimeout help
in Chapter 1, “Cisco VoiceXML
maxtime noinput
Features.”
transferaudio nomatch
cisco-gtd prompt • The following specific Cisco
transferaudio property telephony attributes are supported:
aai value – cisco-username
aaiexpr #pcdata
type – cisco-ani
– cisco-aniexpr
– cisco-anitype
– cisco-aniplan
– cisco-anipi
– cisco-anisi
– cisco-desttype
– cisco-destplan
– cisco-rdn
– cisco-rdnexpr
– cisco-rdntype
– cisco-rdnplan
– cisco-rdnpi
– cisco-rdnsi
– cisco-redirect-reason

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-19
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<value> expr — audio Supported by Cisco VoiceXML.
block
catch
choice
emphasis
enumerate
error
field
filled
help
if
initial
log
menu
noinput
nomatch
object
p
paragraph
prompt
prosody
record
s
say-as
sentence
subdialog
transfer
voice
<var> name block — Supported by Cisco VoiceXML.
expr catch
error
filled
form
help
if
noinput
nomatch
vxml

Cisco VoiceXML Programmer’s Guide

B-20 OL-11175-01
 Appendix B Cisco VoiceXML Elements: Reference Table

Table B-1 Cisco VoiceXML Elements Reference Table (continued)

Element Attributes Parents Children Notes

<vxml> version — catch Supported by Cisco VoiceXML.
base data
xml:lang error
application form
xml:base help
xmlns link
menu
meta
metadata
noinput
nomatch
property
script
var

Cisco VoiceXML Programmer’s Guide

OL-11175-01 B-21
 Appendix B Cisco VoiceXML Elements: Reference Table

Cisco VoiceXML Programmer’s Guide

B-22 OL-11175-01
 Index

event 1-52
Symbols
unsupported element B-1
<dtmf> error.condition.baddestination error event 1-50
ignored inside <transfer> 1-34 event
<goto> types using default event handler 1-52
type-ahead support 1-21
<record> ?? to 1-31
<transfer>
L
longpound attribute 1-34 long-#. See longpound attribute.
type-ahead support 1-21 longpound attribute 1-34

A M
audio message URL http
recording and playout 1-9 to 1-11 //www.cisco.com/go/developersupport xv
message URL www.cisco.com/go/developersupport/ xv,
2-1
B metacharacters 1-23

bridge. See <transfer>, bridge.

buffer control and flushing 1-20
N

noinput event 1-52

C nomatch event 1-52

caution symbol, meaning of x note symbol, meaning of x

conventions, document x

R
D recording ?? to 1-31

document conventions x regular expression 1-23

DTMF
grammar support 1-23
S

session.handoff_string 1-43
E session.telephone.nas_port_id 1-43

element session.telephone.rdnis 1-43

unsupported session.telephone.redirect_reason 1-43

error event B-1 Symbols

error Caution x
Note x

Cisco VoiceXML Programmer’s Guide

OL-11175-01 IN-23
 Index

Timesaver x
Tips x

telephone.disconnect event 1-52

timesaver symbol, meaning of x
tips symbol, meaning of x
transfer
bridge 1-34
terminating 1-34
type-ahead support 1-20 to 1-21
<goto>, <transfer> to application 1-21

VoiceXML applications
document development 1-2
security 1-116
VoiceXML document loops 1-116
VoiceXML Specification
elements supported, unsupported B-1 to ??

Cisco VoiceXML Programmer’s Guide

IN-24 OL-11175-01