TCL IVR API Version 2.0 Programming Guide
Preface
Downloads: This chapterpdf (PDF - 332.0KB) The complete bookPDF (PDF - 2.26MB) | Feedback

Preface

Table Of Contents

Preface

Revision History

Command History

Audience

Structure of This Guide

Related Documents

Conventions

Obtaining Documentation

World Wide Web

Documentation CD-ROM

Ordering Documentation

Documentation Feedback

Obtaining Technical Assistance

Cisco.com

Technical Assistance Center

Cisco TAC Web Site

Cisco TAC Escalation Center

Developer Support


Preface


November 17, 2006

This guide describes Version 2.0 of the Tool Command Language (Tcl) Interactive Voice Response (IVR) Application Programming Interface (API). The Tcl IVR API can be used to create Tcl scripts that control calls coming in to or going out of a Cisco gateway. This guide provides an annotated example of a Tcl IVR script and instructions for testing and loading a Tcl IVR script.

Revision History

Release
Modification

12.3(14)T

Added the following commands to Tcl IVR 2.0 for the Takeback and Transfer feature:

consumeDigit parameter to the leg collectdigits command.

leg senddigit command.

leg sendhookflash command.

Added the following to Tcl IVR 2.0 for HTTP support:

New and modified commands:

command export, media play (modified), media record (modified), modulespace, param read, param register.

New information tags:

ev_params, ev_module_handle, ev_module_subevent, ev_module_context.

New event:

ev_synthesizer

Standard Tcl 8.3.4 commands supported are:

cd, close, eof, fconfigure, file, fileevent, flush, gets, glob, open, package, pwd, read, seek.

HTTP commands supported are:

config, geturl, formatQuery, reset, status, size, code, ncode, data, error, cleanup.

12.4(4)XC

Added the following commands to Tcl IVR 2.1 for the Extension Assigner feature:

phone assign command.

phone query command.

phone unassign command.


Command History

This section provides tables of changes and applicable Cisco IOS releases.

Table 1 Feature History: Commands 

Cisco IOS Release
Command

12.2(11)T

leg vxmldialog

12.2(11)T

leg vxmlsend

12.2(11)T

command terminate

12.2(11)T

aaa authentication

12.2(11)T

aaa authorization

12.2(11)T

aaa accounting

12.2(11)T

clock

12.2(11)T

media play

12.2(11)YT

leg callerid

12.2(11)YT

leg consult abandon

12.2(11)YT

leg consult response

12.2(11)YT

leg consult request

12.2(11)YT

leg tranferdone

12.2(15)T

leg alert

12.2(15)T

leg disconnect_progind

12.2(15)T

leg setup_continue

12.2(15)T

leg progress

12.2(15)T

object create

12.2(15)T

object destroy

12.2(15)T

object append

12.2(15)T

object delete

12.2(15)T

object replace

12.2(15)T

object get

12.2(15)T

leg facility

12.2(15)T

log

12.2(15)T

media record

12.3(4)T

call close

12.3(4)T

handoff

12.3(4)T

handoff return

12.3(4)T

leg setup

12.3(4)T

sendmsg

12.3(4)T

service

12.3(4)T

set callinfo

12.3(4)T

subscription open

12.3(4)T

subscription close

12.3(4)T

subscription notify_ack

12.3(4)T

leg disconnect

12.3(4)T

call register

12.3(4)T

call unregister

12.3(4)T

call lookup

12.3(4)T

leg callerid

12.3(4)T

leg collectdigits

12.3(4)T

aaa accounting set status

12.3(4)T

aaa accounting get status

12.3(4)T

aaa accounting probe

12.3(4)T

timer left

12.3(4)T

timer start

12.3(4)T

timer stop

12.3(14)T

leg senddigit

12.3(14)T

leg sendhookflash

12.3(14)T

command export

12.3(14)T

modulespace

12.3(14)T

param read

12.3(14)T

param register


Table 2 Feature History: callInfo Parameters

Cisco IOS Release
callInfo Parameters

12.2(11)T

guid

12.2(11)T

incomingGuid

12.2(11)YT

destinationNum

12.2(11)YT

originationNum

12.2(11)YT

accountNum

12.2(11)YT

redirectNum

12.2(11)YT

mode

12.2(11)YT

reroutemode

12.2(11)YT

transferConsultID

12.2(11)YT

notifyEvents

12.2(11)YT

originalDest

12.2(15)T

retryCount

12.2(15)T

interceptEvents

12.2(15)T

notifyEvents

12.2(15)T

previousCauseCode

12.3(14)T

consumeDigit


Table 3 Feature History: Information Tags 

Cisco IOS Release
Information Tag

12.2(11)T

leg_rgn_noa

12.2(11)T

leg_rgn_npi

12.2(11)T

leg_rgn_pi

12.2(11)T

leg_rgn_si

12.2(11)T

leg_rgn_num

12.2(11)T

leg_rni_ri

12.2(11)T

leg_rni_orr

12.2(11)T

leg_rni_rc

12.2(11)T

leg_rni_rr

12.2(11)T

leg_ocn_noa

12.2(11)T

leg_ocn_npi

12.2(11)T

leg_ocn_pi

12.2(11)T

leg_ocn_num

12.2(11)T

leg_chn_noa

12.2(11)T

leg_chn_npi

12.2(11)T

leg_chn_num

12.2(11)T

leg_rnn_noa

12.2(11)T

leg_rnn_inn

12.2(11)T

leg_rnn_npi

12.2(11)T

leg_rnn_num

12.2(11)T

leg_rnr

12.2(11)T

leg_cdi_nso

12.2(11)T

leg_cdi_rr

12.2(11)T

leg_gno_ni

12.2(11)T

leg_cnn_noa

12.2(11)T

leg_cnn_npi

12.2(11)T

leg_cnn_pi

12.2(11)T

leg_cnn_si

12.2(11)T

leg_cnn_num

12.2(11)T

leg_gea_type

12.2(11)T

leg_gea_noa

12.2(11)T

leg_gea_npi

12.2(11)T

leg_gea_cni

12.2(11)T

leg_gea_pi

12.2(11)T

leg_gea_si

12.2(11)T

leg_gea_num

12.2(11)T

leg_cpc

12.2(11)T

leg_oli

12.2(11)T

leg_cid_ton

12.2(11)T

leg_cid_cid

12.2(11)T

leg_tns_ton

12.2(11)T

leg_tns_nip

12.2(11)T

leg_tns_cc

12.2(11)T

leg_tns_ns

12.2(11)T

leg_pci_instr

12.2(11)T

leg_pci_tri

12.2(11)T

leg_pci_dat

12.2(11)T

leg_fdc_parm

12.2(11)T

leg_fdc_fname

12.2(11)T

leg_fdc_instr

12.2(11)T

leg_fdc_dat

12.2(11)T

ev_vxmlevent

12.2(11)T

ev_vxmlevent_params

12.2(11)T

ev_status

12.2(11)T

ev_iscommand_done

12.2(11)T

ev_legs

12.2(11)T

last_command_handle

12.2(11)T

leg_guid

12.2(11)T

leg_incoming_guid

12.2(11)T

aaa_new_guid

12.2(11)YT

evt_consult_info

12.2(11)YT

evt_feature_report

12.2(11)YT

evt_feature_type

12.2(11)YT

evt_redirect_info

12.2(11)YT

evt_transfer_info

12.2(11)YT

leg_display_info

12.2(11)YT

leg_dn_tag

12.2(15)T

evt_gtd

12.2(15)T

evt_endpoint_address

12.2(15)T

evt_service_control_count

12.2(15)T

evt_service_control

12.2(15)T

evt_address_resolve_reject_reason

12.2(15)T

evt_address_resolve_term_cause

12.2(15)T

evt_last_event_handle

12.2(15)T

evt_facility_id

12.2(15)T

evt_facility_report

12.2(15)T

evt_gtd

12.2(15)T

evt_progress_indication

12.2(15)T

evt_status

12.2(15)T

gtd_attr_exists

12.3(100)

leg_rni_ri (removed)

12.3(100)

leg_rni_orr (removed)

12.3(100)

leg_rni_rc (removed)

12.3(100)

leg_rni_rr (removed)

12.3(100)

leg_ocn_noa (removed)

12.3(100)

leg_ocn_npi (removed)

12.3(100)

leg_ocn_pi (removed)

12.3(100)

leg_ocn_num (removed)

12.3(100)

leg_chn_noa (removed)

12.3(100)

leg_chn_npi (removed)

12.3(100)

leg_chn_num (removed)

12.3(100)

leg_rnn_noa (removed)

12.3(100)

leg_rnn_inn (removed)

12.3(100)

leg_rnn_npi (removed)

12.3(100)

leg_rnn_num (removed)

12.3(100)

leg_rnr (removed)

12.3(100)

leg_cdi_nso (removed)

12.3(100)

leg_cdi_rr (removed)

12.3(100)

leg_gno_ni (removed)

12.3(100)

leg_cnn_noa (removed)

12.3(100)

leg_cnn_npi (removed)

12.3(100)

leg_cnn_pi (removed)

12.3(100)

leg_cnn_si (removed)

12.3(100)

leg_cnn_num (removed)

12.3(100)

leg_gea_type (removed)

12.3(100)

leg_gea_noa (removed)

12.3(100)

leg_gea_npi (removed)

12.3(100)

leg_gea_cni (removed)

12.3(100)

leg_gea_pi (removed)

12.3(100)

leg_gea_si (removed)

12.3(100)

leg_gea_num (removed)

12.3(100)

leg_cpc (removed)

12.3(100)

leg_oli (removed)

12.3(100)

leg_cid_ton (removed)

12.3(100)

leg_cid_cid (removed)

12.3(100)

leg_tns_ton (removed)

12.3(100)

leg_tns_nip (removed)

12.3(100)

leg_tns_cc (removed)

12.3(100)

leg_tns_ns (removed)

12.3(100)

leg_pci_instr (removed)

12.3(100)

leg_pci_tri (removed)

12.3(100)

leg_pci_dat (removed)

12.3(100)

leg_fdc_parm (removed)

12.3(100)

leg_fdc_fname (removed)

12.3(100)

leg_fdc_instr (removed)

12.3(100)

leg_fdc_dat (removed)

12.3(4)T

leg_proto_headers

12.3(4)T

evt_handoff proto_headers

12.3(4)T

evt_handoff dnis

12.3(4)T

evt_handoff ani

12.3(4)T

evt_handoff argstring

12.3(4)T

evt_proto_content

12.3(4)T

evt_proto_content_type

12.3(4)T

evt_proto_headers

12.3(4)T

evt_status

12.3(4)T

evt_subscription_id

12.3(4)T

mod_all_handles

12.3(4)T

mod_handle

12.3(4)T

mod_handle_service

12.3(4)T

evt_msg

12.3(4)T

evt_msg_source

12.3(4)T

subscription_context

12.3(4)T

subscription_info

12.3(4)T

subscription_server_ipaddress

12.3(4)T

evt_disc_rsi

12.3(4)T

evt_disc_iec

12.3(4)T

evt_feature_report

12.3(4)T

evt_feature_param

12.3(4)T

evt_feature_type

12.3(4)T

evt_last_iec

12.3(4)T

media_timer_factor

12.3(4)T

set iec

12.3(4)T

evt_dest_handle

12.3(4)T

evt_handoff_legs

12.3(4)T

leg_type

12.3(4)T

aaa_accounting_last_sent

12.3(4)T

evt_aaa_status_info

12.3(4)T

evt_timer_name

12.3(4)T

leg_remote_media_ip_address

12.3(4)T

leg_remote_signaling_ip_address


Table 4 Feature History: Events 

Cisco IOS Release
Events

12.2(11)T

ev_vxmldialog_done

12.2(11)T

ev_vxmldialog_event

12.2(11)T

leg_suppress_outgoing_auto_acct

12.2(11)YT

ev_consult_request

12.2(11)YT

ev_consult_response

12.2(11)YT

ev_consultation_done

12.2(11)YT

ev_transfer_request

12.2(11)YT

ev_transfer_status

12.2(15)T

ev_facility

12.2(15)T

ev_disc_prog_ind

12.2(15)T

ev_address_resolved

12.2(15)T

ev_alert

12.2(15)T

ev_connected

12.2(15)T

ev_proceeding

12.2(15)T

ev_progress

12.3(4)T

ev_accounting_status_ind

12.3(4)T

ev_named_timer

12.3(4)T

ev_feature


Table 5 Feature History: Status Codes 

Cisco IOS Release
Status Codes

12.2(11)T

ls_016

12.2(11)T

vd_xxx—VoiceXML Dialog Completion Status

12.2(11)YT

cd_001 to cd_010

12.2(11)YT

cr_000 to cr_004

12.2(11)YT

cs_000 to cs_005

12.2(11)YT

ft_001 to ft_006

12.2(11)YT

ls_026

12.2(11)YT

ls_031 to ls_033

12.2(11)YT

ls_040 to ls_042

12.2(11)YT

ls_050 to ls_059

12.2(11)YT

ts_000 to ts_009

12.2(15)T

fa_000, fa_003, fa_007, fa_009, fa_010, fa_050 to fa_052

12.3(4)T

su_xxx, no_xxx, us_xxx, ul_xxx (000-010, 099)


Audience

This document is a reference guide for developers writing voice application software for Cisco voice interfaces, such as the Cisco AS5x00 series universal access servers. Voice application developers may include:

Independent software vendors (ISVs)

Corporate developers

System integrators

Original equipment manufacturers (OEMs)

This document presumes:

Tcl programming knowledge and experience

Although examples of how to create and use Tcl IVR scripts are provided in this document, this document is not intended to be a tutorial on how to write Tcl scripts.

Structure of This Guide

This guide contains the following chapters and appendixes:

Chapter 1, "Overview" provides an overview of Interactive Voice Response (IVR), the Tool Command Language (Tcl), and version 2.0 of the Tcl IVR Application Programming Interface (API).

Chapter 2, "Using Tcl IVR Scripts" contains information on how to create and use Tcl IVR scripts.

Chapter 3, "Tcl IVR API Command Reference" provides an alphabetical listing of the Tcl IVR API commands.

Chapter , "Information Tags" discusses identifiers that can be used to retrieve information about call legs, events, the script itself, the current configuration, and values returned from RADIUS.

Chapter 5, "Events and Status Codes," describes events received and status codes returned by Tcl IVR scripts.

Appendix , "Sample Scripts," provides some sample Tcl scripts.

Glossary, presents an alphabetical listing of common terms used throughout this document.

Related Documents

Configuring Interactive Voice Response for Cisco Access Platforms:

http://www.cisco.com/univercd/cc/td/doc/product/access/acs_serv/as5400/sw_conf/ios_121/pull_ivr.htm

Service Provider Features for Voice over IP:

http://www.cisco.com/univercd/cc/td/doc/product/software/ios120/120newft/120t/120t3/voip1203.htm

Voice over IP for the Cisco AS5300:

http://www.cisco.com/univercd/cc/td/doc/product/access/nubuvoip/voip5300/index.htm

Voice over IP for the Cisco AS5800:

http://www.cisco.com/univercd/cc/td/doc/product/access/nubuvoip/voip5800/index.htm

Voice over IP for the Cisco 2600/Cisco 3600 Series:

http://www.cisco.com/univercd/cc/td/doc/product/access/nubuvoip/voip3600/index.htm

Configuring H.323 VoIP Gateway for Cisco Access Platforms:

http://www.cisco.com/univercd/cc/td/doc/product/software/ios121/121cgcr/multi_c/mcprt1/mcdvoip.htm

Prepaid Distributed Calling Card via Packet Telephony:

http://www.cisco.com/univercd/cc/td/doc/product/access/acs_serv/as5400/sw_conf/ios_121/pull0134.htm

RADIUS Vendor-Specific Attributes Implementation Guide:

http://cco/univercd/cc/td/doc/product/access/acs_serv/vapp_dev/vsaig3.htm

Tcl IVR API Version 1.0 Programmer's Guide:

http://cco/univercd/cc/td/doc/product/access/acs_serv/vapp_dev/tclivrpg.htm

Interactive Voice Response Version 2.0 on Cisco VoIP Gateways:

http://www.cisco.com/en/US/docs/ios/12_1t/12_1t3/feature/guide/dt_skyn.html

Enhanced Multilanguage Guide:

http://www.cisco.com/univercd/cc/td/doc/product/software/ios122/122newft/122t/122t2/ftmultil.htm

Cisco IOS Security Configuration Guide, Release 12.2:

http://www.cisco.com/univercd/cc/td/doc/product/software/ios122/122cgcr/fsecur_c/index.htm

Cisco IOS Tcl and VoiceXML Application Guide

http://www.cisco.com/univercd/cc/td/doc/product/software/ios122/122newft/122t/122t11/ivrapp/index.htm

Cisco VoiceXML Programmer's Guide

http://www.cisco.com/univercd/cc/td/doc/product/software/ios122/rel_docs/vxmlprg/index.htm

Introduction to writing Tcl scripts:Tcl and the TK Toolkit, by John Ousterhout (published by Addison Wesley Longman, Inc)

Developer Support Agreement:

http://www.cisco.com/warp/public/779/servpro/programs/ecosystem/devsup

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 font

 Examples of information you must enter.

<    >

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

The following sections provide sources for obtaining documentation from Cisco Systems.

World Wide Web

You can access the most current Cisco documentation on the World Wide Web at the following URL:

http://www.cisco.com

Translated documentation is available at the following URL:

http://www.cisco.com/public/countries_languages.shtml

Documentation CD-ROM

Cisco documentation and additional literature are available in a Cisco Documentation CD-ROM package, which is shipped with your product. The Documentation CD-ROM is updated monthly and may be more current than printed documentation. The CD-ROM package is available as a single unit or through an annual subscription.

Ordering Documentation

Cisco documentation is available in the following ways:

Registered Cisco Direct Customers can order Cisco Product documentation from the Networking Products MarketPlace:

http://www.cisco.com/cgi-bin/order/order_root.pl

Registered Cisco.com users can order the Documentation CD-ROM through the online Subscription Store:

http://www.cisco.com/go/subscription

Nonregistered Cisco.com users can order documentation through a local account representative by calling Cisco corporate headquarters (California, USA) at 408 526-7208 or, in North America, by calling 800 553-NETS (6387).

Documentation Feedback

If you are reading Cisco product documentation on Cisco.com, you can submit technical comments electronically. Click the Fax or Email option under the "Leave Feedback" at the bottom of the Cisco Documentation home page.

You can e-mail your comments to bug-doc@cisco.com.

To submit your comments by mail, use the response card behind the front cover of your document, or write to the following address:

Cisco Systems
Attn: Document Resource Connection
170 West Tasman Drive
San Jose, CA 95134-9883

We appreciate your comments.

Obtaining Technical Assistance

Cisco provides Cisco.com as a starting point for all technical assistance. Customers and partners can obtain documentation, troubleshooting tips, and sample configurations from online tools by using the Cisco Technical Assistance Center (TAC) Web Site. Cisco.com registered users have complete access to the technical support resources on the Cisco TAC Web Site.

Cisco.com

Cisco.com is the foundation of a suite of interactive, networked services that provides immediate, open access to Cisco information, networking solutions, services, programs, and resources at any time, from anywhere in the world.

Cisco.com is a highly integrated Internet application and a powerful, easy-to-use tool that provides a broad range of features and services to help you to

Streamline business processes and improve productivity

Resolve technical issues with online support

Download and test software packages

Order Cisco learning materials and merchandise

Register for online skill assessment, training, and certification programs

You can self-register on Cisco.com to obtain customized information and service. To access Cisco.com, go to the following URL:

http://www.cisco.com

Technical Assistance Center

The Cisco TAC is available to all customers who need technical assistance with a Cisco product, technology, or solution. Two types of support are available through the Cisco TAC: the Cisco TAC Web Site and the Cisco TAC Escalation Center.

Inquiries to Cisco TAC are categorized according to the urgency of the issue:

Priority level 4 (P4)—You need information or assistance concerning Cisco product capabilities, product installation, or basic product configuration.

Priority level 3 (P3)—Your network performance is degraded. Network functionality is noticeably impaired, but most business operations continue.

Priority level 2 (P2)—Your production network is severely degraded, affecting significant aspects of business operations. No workaround is available.

Priority level 1 (P1)—Your production network is down, and a critical impact to business operations will occur if service is not restored quickly. No workaround is available.

Which Cisco TAC resource you choose is based on the priority of the problem and the conditions of service contracts, when applicable.

Cisco TAC Web Site

The Cisco TAC Web Site allows you to resolve P3 and P4 issues yourself, saving both cost and time. The site provides around-the-clock access to online tools, knowledge bases, and software. To access the Cisco TAC Web Site, go to the following URL:

http://www.cisco.com/tac

All customers, partners, and resellers who have a valid Cisco services contract have complete access to the technical support resources on the Cisco TAC Web Site. The Cisco TAC Web Site requires a Cisco.com login ID and password. If you have a valid service contract but do not have a login ID or password, go to the following URL to register:

http://www.cisco.com/register/

If you cannot resolve your technical issues by using the Cisco TAC Web Site, and you are a Cisco.com registered user, you can open a case online by using the TAC Case Open tool at the following URL:

http://www.cisco.com/tac/caseopen

If you have Internet access, it is recommended that you open P3 and P4 cases through the Cisco TAC Web Site.

Cisco TAC Escalation Center

The Cisco TAC Escalation Center addresses issues that are classified as priority level 1 or priority level 2; these classifications are assigned when severe network degradation significantly impacts business operations. When you contact the TAC Escalation Center with a P1 or P2 problem, a Cisco TAC engineer will automatically open a case.

To obtain a directory of toll-free Cisco TAC telephone numbers for your country, go to the following URL:

http://www.cisco.com/warp/public/687/Directory/DirTAC.shtml

Before calling, please check with your network operations center to determine the level of Cisco support services to which your company is entitled; for example, SMARTnet, SMARTnet Onsite, or Network Supported Accounts (NSA). In addition, please have available your service agreement number and your product serial number.

Developer Support

Developers using this guide may be interested in joining the Cisco Developer Support Program. This program was created to provide you with a consistent level of support that you can depend on while leveraging Cisco interfaces in your development projects.


Tip A signed Developer Support Agreement is required to participate in this program. For more details go to http://www.cisco.com/go/developersupport or contact developer-support@cisco.com.