|
|
Version 07/24/00
This document contains information about the Tool Command Language (TCL) Interactive Voice Response (IVR) Application Programming Interface (API) Version 2.0 that you can use to create TCL scripts that control calls coming into or going out of the gateway. It provides an annotated example of a TCL IVR script and includes instructions for testing and loading a TCL IVR script.
This document helps developers writing voice application software for Cisco voice interfaces, such as the Cisco AS5x00 series. This includes independent software vendors (ISVs), in-house corporate developers, system integrators, and Original Equipment Manufacturers (OEMs).
This document includes the following sections:
IVR is a term that is used to describe systems that provide information in the form of recorded messages over telephone lines in response to user input in the form of spoken words or, more commonly, dual tone multifrequency (DTMF) signaling. For example, when a user makes a call with a debit card, an IVR application is used to prompt the caller to enter a specific type of information, such as a PIN. After playing the voice prompt, the IVR application collects the predetermined number of touch tones (digit collection), forwards the collected digits to a server for storage and retrieval, and then places the call to the destination phone or system. Call records can be kept and a variety of accounting functions performed.
In essence, the IVR application (or script) is a voice application designed to handle calls on a voice gateway, which is a router that is equipped with voice features and capabilities.
The prompts used in an IVR script can be either static or dynamic:
The Cisco Interactive Voice Response (IVR) feature, available in Cisco IOS Release 12.0(6)T and later, provides IVR capabilities using TCL 1.0 scripts. These scripts are signature locked, and can be modified only by Cisco. The IVR feature allows IVR scripts to be used during call processing. The scripts interact with the IOS software to perform various call-related functions. Starting with
Cisco IOS Release 12.1(3), no longer is any TCL script lock in place, thus customers can create and change their own TCL scripts.
TCL is an interpreted scripting language. Because TCL is an interpreted language, scripts written in TCL do not have to be compiled before they are executed. TCL provides a fundamental command set, which allows for standard functions such as flow control (if, then, else) and variable management. By design, this command set can be expanded by adding extensions to the language to perform specific operations.
Cisco has created a set of extensions, called TCL IVR commands, that allows users to create IVR scripts using TCL. Unlike other TCL scripts, which are invoked from a shell, TCL IVR scripts are invoked when a call comes into the gateway.
The remainder of this document assumes that you are familiar with TCL and how to create scripts using TCL. If you are not, we recommend that you read TCL and the TK Toolkit by John Ousterhout (published by Addison Wesley Longman, Inc).
This overview contains sections that describe the prerequisites, restrictions, benefits, features, and the developer support program for this application programming interface.
The open TCL IVR feature is currently supported on the Cisco AS5300 voice platform only. In order to use the open TCL IVR feature, you need the following:
1. Cisco AS5300 universal access server (voice platform).
2. Cisco IOS Release 12.1(3) or later.
3. TCL Version 7.1 or later.
Calls can come into a gateway using analog lines, ISDN lines, a VoIP link, or a Voice over Frame Relay (VoFR) link. TCL IVR scripts can provide full functionality for calls received over analog or ISDN lines. The functionality provided for calls received over VoIP or VoFR links varies depending on the release of Cisco IOS software being used. For example, if you are using
Cisco IOS Release 12.0, you cannot play prompts or tones, and you cannot collect tones.
If a TCL 2.0 script is used with the TCL Interpreter 8.0.5, the minimum memory requirement is
64 megabytes for the Cisco 2600 and Cisco 3600 series platforms, starting with
Cisco IOS Release 12.1(3)T. Additional memory is needed only if you use TCL 2.0 scripts with TCL interpreter 8.0.5. At this time, the unlocked TCL scripts are not supported on the Cisco 2600 and the Cisco 3600 series platforms. This memory requirement applies regardless of whether the TCL scripts are locked or unlocked.
TCL IVR API Version 2.0 has the following benefits:
leg collect digits 1 callInfo leg collect digits 2 callInfo leg setup 295786 setupInfo $callID5 puts "\n This will be excuted immediately i.e. before the collect digits or call setup is actually complete"
TCL IVR API Version 2.0 commands provide access to the following facilities and features:
For more information, see the "TCL IVR API Command Reference" section.
Developers using this guide may be interested in joining the Cisco Developer Support Program. This new program has been developed to provide you with a consistent level of support that you can depend on while leveraging Cisco interfaces in your development projects.
A signed Developer Support Agreement is required to participate in this program. For more details, and access to this agreement, please visit us at: http://www.cisco.com/warp/public/779/servpro/programs/ecosystem/devsup, or contact developer-support@cisco.com
With TCL IVR Version 2.0, the script can be divided into three parts: the initialization procedures, the action functions, and the Finite State Machine (FSM).
set callfsm(any_state,ev_any_event)"defaultProc,same_state"
set callfsm(any_state,ev_disconnected) "cleanupCall,CLOSE_CALL"
set callfsm(any_state,ev_disconnected) "cleanupCall,CLOSE_CALL" set callfsm(MEDIA_PLAYING,ev_disconnected) "doSomthingProc,MEDIA_WAIT_STATE" set callfsm(MEDIA_WAIT_STATE,ev_media_done) "cleanupCall,CLOSE_CALL"
When the gateway receives a call, the gateway hands the call to an application that is configured on the system. If the application is a TCL script that uses the TCL IVR API Version 2.0, an execution instance of the application (or script) is created and executed.
When the script is executed, the TCL interpreter reads the procedures in the script and executes the main section of the script (including the initialization of global variables). At this point, the fsm define command registers the state machine and the start state. This initialized execution instance is handed the call. From then on (until the call close command), when an event is received, the appropriate action procedure is called according to the current state of the call and the event received by the script.
An execution instance can handle only one call. Therefore, if the system is handling 10 calls using the same script, there will be 10 instances of that script. In between calls, the execution instances are cached to handle the next call. These cached execution instances are removed when the application is reloaded. Cached execution instances are also removed if a CLI parameter or attribute-value (AV)-pair is changed, removed, or added, or if an application is unconfigured.
This section of the document includes information on how to create and use TCL IVR scripts. This section includes the following topics:
Before you write an IVR script using TCL, you should familiarize yourself with the TCL extensions for IVR scripts. You can use any text editor to create your TCL IVR script. Follow the standard conventions for creating a TCL script and incorporate the TCL IVR commands as necessary.
A sample script is provided in this section to illustrate how the TCL IVR API Version 2.0 commands can be used.
The following standard TCL commands can be used in TCL IVR scripts:
append | array | break | case |
catch | concat | continue | error |
eval | expr | for | foreach |
format | global | history | if |
incr | info | join | lappend |
lindex | linsert | list | llength |
lrange | lreplace | lsearch | lsort |
proc | puts | regexp | regsub |
rename | return | set | split |
string | switch | tcl_trace | unset |
uplevel | upvar | while |
|
For additional information about the standard TCL commands, see the TCL and the TK Toolkit by John Ousterhout (published by Addison Wesley Longman, Inc).
In addition to the standard TCL commands, you can use the TCL extensions for IVR scripts that Cisco has created. Also, Cisco modified the existing puts TCL command to perform specific tasks. The TCL IVR API Version 2.0 commands are as follows:
| Command | Description |
aaa authenticate | Sends an authentication request to an external system, typically a Remote Access Dial-In User Services (RADIUS) server. |
aaa authorize | Sends an authorization request to an external system, typically a RADIUS server. |
call close | Marks the end of the call, releases all resources associated with that call, and frees the execution instance to handle the next call. |
connection create | Connects two call legs. |
connection destroy | Destroys a connection. |
fsm define | Registers a state machine specified by a TCL array and its start state. |
fsm setsate | Specifies the next state of the FSM after completion of the current action procedure. |
handoff appl | Hands off the call leg to another application. The call leg cannot be returned using the handoff return command. |
handoff callappl | Hands off the call leg to another application and waits for the call leg to return. |
handoff return | Returns the call leg to the application. |
infotag get | Retrieves information from a call leg, script, or system. |
infotag set | Allows you to set information in the system. |
leg collectdigits | Moves the call into Digit Collect mode and collects the digits. |
leg connect | Sends a call connect message to the incoming call leg. |
leg disconnect | Disconnects one or more call legs that are not part of a connection. |
leg proceeding | Sends a call proceeding message to the incoming call leg. |
leg setup | Initiates an outgoing call setup to the destination number. |
leg setupack | Sends a call setup acknowledgement back to the incoming call leg. |
media pause | Pauses the prompt playing on a specific call leg. |
media play | Plays a prompt on a specific call leg. |
media resume | Resumes play of a prompt on a specific call leg. |
media seek | Seeks forward or backward in the current prompt. |
media stop | Stops the prompt playing on a specific call leg. |
playtone | Plays a specific tone or one according to the status code provided on a call leg. |
puts | Prints the parameter to the console. Used for debugging. |
requiredversion | Verifies the current version of the TCL IVR API. |
timer left | Returns the time left on an active timer. |
timer start | Starts a timer for a call on a specific call leg. |
timer stop | Stops the timer. |
For more on each command, see the "TCL IVR API Command Reference" section.
TCL IVR API Version 2.0 allows two types of prompts: memory-based and RTSP-based prompts.
As mentioned earlier, through the use of dynamic prompts, TCL IVR API Version 2.0 also provides some basic TTS functionality, like playing numbers, dollar amounts, date, and time. It also allows you to classify prompts using different languages so that when the script is instructed to play a particular prompt, it automatically plays the prompt in the active or specified language.
The following example shows how to use the TCL IVR API Version 2.0 commands. We recommend that you start with the header information. This includes the name of the script, the date that the script was created and by whom, and some general information about what the script does.
We also recommend that you include a version number for the script, using a three-digit system, where the first digit indicates a major version of the script , the second digit is incremented with each minor revision (such as a change in function within the script), and the third digit is incremented each time any other changes are made to the script.
The following sample script does the following: plays dial-tone, collects digits to match a dial-plan, places an outgoing call to the destination, conferences the two call legs, and destroys the conference call legs and the disconnect call legs, when anyone hangs up.
# app_session.tcl # Script Version 1.0.1 #------------------------------------------------------------------ # August 1999, Saravanan Shanmugham # # Copyright (c) 1998, 1999 by cisco Systems, Inc. # All rights reserved. #------------------------------------------------------------------ # # This tcl script mimics the default SESSION app # # # If DID is configured, place the call to the dnis. # Otherwise, output dial-tone and collect digits from the # caller against the dial-plan. # # Then place the call. If successful, connect it up. Otherwise, # the caller should hear a busy or congested signal. # The main routine establishes the state machine and then exits. # From then on, the system drives the state machine depending on the # events it recieves and calls the appropriate TCL procedure.
Next, we define a series of procedures.
The init procedure defines the initial parameters of the digit collection. In this procedure:
proc init { } {
global param
set param(interruptPrompt) true
set param(abortKey) *
set param(terminationKey) #
}
The act_Setup procedure is executed when an ev_setup_indication event is received. It gathers the information necessary to place the call. In this procedure:
proc act_Setup { } {
global dest
global beep
set beep 0
leg setupack leg_incoming
if { [infotag get leg_isdid] } {
set dest [infotag get leg_dnis]
leg proceeding leg_incoming
leg setup $dest callInfo leg_incoming
fsm setstate PLACECALL
} else {
playtone leg_incoming tn_dial
set param(dialPlan) true
leg collectdigits leg_incoming param
}
}
The act_GotDest procedure is executed when an ev_collectdigits_done event is received. It determines whether the collected digits match the dial plan, in which case the call should be placed. In this procedure:
proc act_GotDest { } {
global dest
set status [infotag get evt_status]
if { $status == "cd_004" } {
set dest [infotag get evt_dcdigits]
leg proceeding leg_incoming
leg setup $dest callInfo leg_incoming
} else {
puts "\nCall [infotag get con_all] got event $status collecting destination"
call close
}
}
The act_CallSetupDone procedure is executed when an ev_setup_done event is received. It determines whether there is a time limit on the call. In this procedure:
proc act_CallSetupDone { } {
global beep
set status [infotag get evt_status]
if { $status == "ls_000"} {
set creditTimeLeft [infotag get leg_settlement_time leg_outgoing]
if { ($creditTimeLeft == "unlimited") ||
($creditTimeLeft == "uninitialized") } {
puts "\n Unlimited Time"
} else {
# start the timer for ...
if { $creditTimeLeft < 10 } {
set beep 1
set delay $creditTimeLeft
} else {
set delay [expr $creditTimeLeft - 10]
}
timer start leg_timer $delay leg_incoming
}
} else {
puts "Call [infotag get con_all] got event $status while placing an outgoing call"
call close
}
}
The act_Timer procedure is executed when an ev_leg_timer event is received. It is used in the last 10 seconds of credit time and warns the user that time is expiring and terminates the call when the credit limit is reached. In this procedure:
proc act_Timer { } {
global beep
global incoming
global outgoing
set incoming [infotag get leg_incoming]
set outgoing [infotag get leg_outgoing]
if { $beep == 0 } {
#insert a beep ...to the caller
connection destroy con_all
set beep 1
} else {
media play leg_incoming flash:out_of_time.au
fsm setstate CALLDISCONNECTED
}
}
The act_Destroy procedure is executed when an ev_destroy_done event is received. It plays a beep to the incoming call leg.
proc act_Destroy { } {
media play leg_incoming flash:beep.au
}
The act_Beeped procedure is executed when an ev_media_done event is received. It creates a connection between the incoming and the outgoing call legs.
proc act_Beeped { } {
global incoming
global outgoing
connection create $incoming $outgoing
}
The act_ConnectedAgain procedure is executed when an ev_create_done event is received. It resets the timer on the incoming call leg to 10 seconds.
proc act_ConnectedAgain { } {
timer start leg_timer 10 leg_incoming
}
The act_Ignore procedure reports "Event Capture."
proc act_Ignore { } {
# Dummy
puts "Event Capture"
}
The act_Cleanup procedure is executed when an ev_disconnected event is received and when the state is CALLDISCONNECTED. It closes the call.
proc act_Cleanup { } {
call close
}
Finally, we put all the procedures together in a main routine. The main routine defines a TCL array that defines the actual state transitions for the various state and event combinations. It registers the state machine that will drive the calls. In the main routine:
init #---------------------------------- # State Machine #---------------------------------- set TopFSM(any_state,ev_disconnected) "act_Cleanup,same_state" set TopFSM(CALL_INIT,ev_setup_indication) "act_Setup,GETDEST" set TopFSM(GETDEST,ev_collectdigits_done) "act_GotDest,PLACECALL" set TopFSM(PLACECALL,ev_setup_done) "act_CallSetupDone,CALLACTIVE" set TopFSM(CALLACTIVE,ev_leg_timer) "act_Timer,INSERTBEEP" set TopFSM(INSERTBEEP,ev_destroy_done) "act_Destroy,same_state" set TopFSM(INSERTBEEP,ev_media_done) "act_Beeped,same_state" set TopFSM(INSERTBEEP,ev_create_done) "act_ConnectedAgain,CALLACTIVE" set TopFSM(CALLACTIVE,ev_disconnected) "act_Cleanup,CALLDISCONNECTED" set TopFSM(CALLDISCONNECTED,ev_disconnected) "act_Cleanup,same_state" set TopFSM(CALLDISCONNECTED,ev_media_done) "act_Cleanup,same_state" set TopFSM(CALLDISCONNECTED,ev_disconnect_done) "act_Cleanup,same_state" set TopFSM(CALLDISCONNECTED,ev_leg_timer) "act_Cleanup,same_state"
fsm define TopFSM CALL_INIT
It is important to thoroughly test a script before it is deployed. To test a script, you must place it on a router and place a call to activate the script. When you test your script, make sure that you test every procedure in the script and all variations within each procedure.
You can view debugging information applicable to the TCL IVR scripts that are running on the router. The debug voip ivr command allows you to specify the type of debug output you want to view. To view debug output, enter the following command in privileged Exec mode:
[no] debug voip ivr [states | error | tclcommands | callsetup | digitcollect | script | dynamic | applib | settlement | all]
For more information about the debug voip ivr command, see the Interactive Voice Response Version 2.0 on Cisco VoIP Gateways document on CCO.
The output of any TCL puts commands is displayed if script debugging is on.
Possible sources of errors are:
In most cases, an error such as these causes the underlying infrastructure to disconnect the call legs and clean up.
To associate an application with your TCL IVR script, use the following command:
(config)# call application voice application_name script_url
Once you have associated an application with your TCL IVR script, you can use the following form of the command to configure parameters:
(config)# call application voice application_name script_url [parameter value]
In this command:
For more information about the call application voice command, see the Interactive Voice Response Version 2.0 on Cisco VoIP Gateways document on CCO.
In the following example, the application named "test" is associated with the TCL IVR script called newapp.tcl, which is located at tftp://keyer/debit_audio/:
(config)# call application voice test tftp://keyer/debit_audio/newapp.tcl
For more information about the call application voice command, see the Interactive Voice Response Version 2.0 on Cisco VoIP Gateways document on CCO.
If you modify your script, you can reload it using only the script name as shown below:
(config)# call application voice load script_name
For more information about the call application voice load command, see the Interactive Voice Response Version 2.0 on Cisco VoIP Gateways document on CCO.
To invoke your TCL IVR script to handle a call, you must associate the application configured with an inbound dial peer. To associate your script with an inbound dial peer, enter the following commands in configuration mode:
(config)# dial-peer voice number voip
(conf-dial-peer)# incoming called-number destination_number
(conf-dial-peer)# application application_name
In these commands:
For example, the following commands indicate that the application called "newapp" should be invoked for calls that come in from an IP network and are destined for the telephone number of 125.
(config)# dial-peer voice 3 voip (conf-dial-peer)# incoming called-number 125 (conf-dial-peer)# application newapp
For more information about inbound dial peers, see the Cisco IOS software documentation.
To view a list of the voice applications that are configured on the router, use the show call application voice command. A one-line summary of each application is displayed.
show call application voice [ [name] | [summary] ]
In this command:
The following is an example of the output of the show call application voice command:
router# show call application voice session2
Idle call list has 0 calls on it.
Application session2
The script is read from URL tftp://dirt/sarvi/scripts/tcl/app_session.tcl
The uid-len is 10 (Default)
The pin-len is 4 (Default)
The warning-time is 60 (Default)
The retry-count is 3 (Default)
It has 0 calls active.
The TCL Script is:
------------------
# app_session.tcl
#------------------------------------------------------------------
# August 1999, Saravanan Shanmugham
#
# Copyright (c) 1998, 1999 by cisco Systems, Inc.
# All rights reserved.
#------------------------------------------------------------------
#
# This tcl script mimics the default SESSION app
#
#
# If DID is configured, just place the call to the dnis
# Otherwise, output dial-tone and collect digits from the
# caller against the dial-plan.
#
# Then place the call. If successful, connect it up, otherwise
# the caller should hear a busy or congested signal.
# The main routine just establishes the state machine and then exits.
# From then on the system drives the state machine depending on the
# events it recieves and calls the appropriate tcl procedure
#---------------------------------
# Example Script
#---------------------------------
proc init { } {
global param
set param(interruptPrompt) true
set param(abortKey) *
set param(terminationKey) #
}
proc act_Setup { } {
global dest
global beep
set beep 0
leg setupack leg_incoming
if { [infotag get leg_isdid] } {
set dest [infotag get leg_dnis]
leg proceeding leg_incoming
leg setup $dest callInfo leg_incoming
fsm setstate PLACECALL
} else {
playtone leg_incoming tn_dial
set param(dialPlan) true
leg collectdigits leg_incoming param
}
}
proc act_GotDest { } {
global dest
set status [infotag get evt_status]
if { $status == "cd_004" } {
set dest [infotag get evt_dcdigits]
leg proceeding leg_incoming
leg setup $dest callInfo leg_incoming
} else {
puts "\nCall [infotag get con_all] got event $status while placing an outgoing call"
call close
}
}
proc act_CallSetupDone { } {
global beep
set status [infotag get evt_status]
if { $status == "CS_000"} {
set creditTimeLeft [infotag get leg_settlement_time leg_outgoing]
if { ($creditTimeLeft == "unlimited") ||
($creditTimeLeft == "uninitialized") } {
puts "\n Unlimited Time"
} else {
# start the timer for ...
if { $creditTimeLeft < 10 } {
set beep 1
set delay $creditTimeLeft
} else {
set delay [expr $creditTimeLeft - 10]
}
timer start leg_timer $delay leg_incoming
}
} else {
puts "Call [infotag get con_all] got event $status collecting destination"
call close
}
}
proc act_Timer { } {
global beep
global incoming
global outgoing
set incoming [infotag get leg_incoming]
set outgoing [infotag get leg_outgoing]
if { $beep == 0 } {
#insert a beep ...to the caller
connection destroy con_all
set beep 1
} else {
media play leg_incoming flash:out_of_time.au
fsm setstate CALLDISCONNECTED
}
}
proc act_Destroy { } {
media play leg_incoming flash:beep.au
}
proc act_Beeped { } {
global incoming
global outgoing
connection create $incoming $outgoing
}
proc act_ConnectedAgain { } {
timer start leg_timer 10 leg_incoming
}
proc act_Ignore { } {
# Dummy
puts "Event Capture"
}
proc act_Cleanup { } {
call close
}
init
#----------------------------------
# State Machine
#----------------------------------
set TopFSM(any_state,ev_disconnected) "act_Cleanup,same_state"
set TopFSM(CALL_INIT,ev_setup_indication) "act_Setup,GETDEST"
set TopFSM(GETDEST,ev_digitcollect_done) "act_GotDest,PLACECALL"
set TopFSM(PLACECALL,ev_setup_done) "act_CallSetupDone,CALLACTIVE"
set TopFSM(CALLACTIVE,ev_leg_timer) "act_Timer,INSERTBEEP"
set TopFSM(INSERTBEEP,ev_destroy_done) "act_Destroy,same_state"
set TopFSM(INSERTBEEP,ev_media_done) "act_Beeped,same_state"
set TopFSM(INSERTBEEP,ev_create_done) "act_ConnectedAgain,CALLACTIVE"
set TopFSM(CALLACTIVE,ev_disconnected) "act_Cleanup,CALLDISCONNECTED"
set TopFSM(CALLDISCONNECTED,ev_disconnected) "act_Cleanup,same_state"
set TopFSM(CALLDISCONNECTED,ev_media_done) "act_Cleanup,same_state"
set TopFSM(CALLDISCONNECTED,ev_media_done) "act_Cleanup,same_state"
set TopFSM(CALLDISCONNECTED,ev_disconnect_done) "act_Cleanup,same_state"
set TopFSM(CALLDISCONNECTED,ev_leg_timer) "act_Cleanup,same_state"
fsm define TopFSM CALL_INIT
With IVR scripts, you use URLs to call the script and to call the audio files that the script plays. The VoIP system uses Cisco IOS File System (IFS) to read the files, so any IFS supported URLs can be used, which includes TFTP, FTP, or a pointer to a device on the router.
The URL of the IVR script is a standard URL that points to the location of the script. Examples include:
URLs for audio files are different from those used to load IVR scripts. With URLs for audio files:
This section provides some answers to frequently asked questions about using TCL IVR scripts.
1. How do I get information from my RADIUS server to the TCL IVR script?
Once you have performed an authentication and authorization, you can use the infotag get command to obtain the credit amount, credit time, and cause codes maintained by the RADIUS server.
2. What happens if my script encounters an error?
When an error is encountered in the script, the call is cleared with a cause of TEMPORARY_FAILURE (41). If the IVR application has already accepted the incoming call, the caller hears silence. If the script has not accepted the incoming call, the caller might hear a fast busy signal.
If the script exits with an error and IVR debugging is on (as described in the "Testing and Debugging Your Script" section), the location of the error in the script is displayed at the command line.
This section provides an alphabetical listing of the new TCL IVR API commands. The following is provided for each command:
For information about returns and events, see the "Events" section.
The aaa authenticate command validates the authenticity of the user. This command sends the account number and password to the appropriate server for authentication.
aaa authenticate account password [avSend]
The arguments of this command are:
None
When the command has finished, the script receives an ev_authenticate_done event.
aaa authenticate $account $password
set avsend(h323-credit-amount) 25.0
set avsend(h323-ivr-out,0) "payphone:true" set avsend(h323-ivr-out,1) "creditTime:3400"
The aaa authorize command sends a RADIUS authorization request. Typically, this command is used to provide additional information to the RADIUS server (destination and origination numbers) after a user has been successfully authenticated. It sends the authorization request to the RADIUS server after the IVR application prompts the user to enter the destination number.
aaa authorize account password ani destination {legID | info-tag} [avSend]
The arguments of this command are:
The account and password arguments are the same as those specified in the aaa authenticate command. The destination and ani arguments provide additional information to the external server.
None
When the command finishes, the script receives an ev_authorize_done event.
aaa authorize $account $password $ani $destination $legid
set avsend(h323-credit-amount) 25.0
set avsend(h323-ivr-out,0) "payphone:true" set avsend(h323-ivr-out,1) "creditTime:3400"
The call close command marks the end of the call and frees the execution instance of the script to handle the next call. This command causes the system to clean up the resources associated with that call. If conference legs exist, this command destroys the connection and clears all the call legs. If leg collectdigits is active on any of the call legs, the digit collection process is terminated and the call is cleared.
call close
None
None
Immediate
proc act_Disconnected {} {
call close
}
set FSM(any_state,ev_disconnected) "act_Disconnected, CALL_CLOSED"
The call close command marks the end of the call and the end of the script. This command causes the system to clean up the resources.
The connection create command connects two call legs.
connection create {legID1 | info-tag1} {legID2 | info-tag2}
The arguments of this command are:
This command returns the following:
When this command finishes, the script receives an ev_create_done event.
set connID [connection create $legID1 $legID2]
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The connection destroy command destroys the connection between the two call legs.
connection destroy {connectionID | info-tag}
The arguments of this command are:
None
When this command finishes, the script receives an ev_destroy_done event.
connection destroy $connID
The individual call legs are not disconnected; only the connection between the call legs is destroyed.
The fsm define command registers a state machine for the script. The state machine is specified using a TCL array that lists the state event transition along with the appropriate action procedure.
fsm define statemachine_array start_state
The arguments of this command are:
None
Immediate
#----------------------------------
# State Machine
#----------------------------------
set FSM(CALL_INIT,ev_setup_indication) "act_Setup,DEST_COLLECT"
set FSM(DEST_COLLECT,ev_disconnect_done) "act_DCDone,CALL_SETTING"
set FSM(DEST_COLLECT,ev_disconnected) "act_DCDisc,CALL_DISCONNECTING"
set FSM(CALL_SETTING,ev_callsetup_done) "act_PCDone,CALL_ACTIVE"
set FSM(CALL_SETTING,ev_disconnected) "act_PCDisc,CALL_SETTING_WAIT"
fsm define FSM CALL_INIT
The fsm setstate command allows you to specify the state that the FSM will move to after completion of the action procedure.
fsm setstate StateName
The argument of this command is:
None
None
#Check for DNIS, if there is DNIS you want to go to Call setup right away
set legID [infotag get evt_legs]
set destination [infotag get leg_dnis $legID]
if {destination != ""} {
callProceeding $legID
set callInfo(alertTimer) 30
call setup $destination callInfo leg_incoming
#Moves to CALL_SETTING state
fsm setstate CALL_SETTING
} else {
leg setupack $legID
playtone $legID TN_DIAL
set DCInfo(dialPlan) true
# Assumption: As per the state machine moves to DIGIT_COLLECT}
leg collectdigits $legID DCInfo
}
The handoff appl command hands off the specified call leg (and all call legs connected to it) to the specified application and does not expect it to return.
handoff appl {legID | info-tag} app-name [argstring]
The arguments of this command are:
None
None
handoff appl leg_outgoing new_app "DIAL_PEER=25"
handoff appl leg_outgoing melody_app "SONG=hello_world.au;VOLUME=25"
The handoff callappl command hands off the specified call leg (and all call legs connected to it) to the specified application and can wait for the leg to be returned by the destination application.
handoff callappl {legID | info-tag} app-name [argstring]
The arguments of this command are:
None
When the application has completed its processing, the script receives an ev_returned event. This event indicates that all the call legs have been accounted for. This means that they have either been returned or disconnected.
handoff callappl leg_outgoing other_app "DIAL_PEER=25"
handoff callappl leg_outgoing melody_app "SONG=hello_world.au;VOLUME=25"
The handoff return command returns the call leg (and all connected call legs) to the application that handed the specified call leg to this application using the handoff callappl command.
handoff return {legID | info-tag} [argstring]
The arguments of this command are:
None
Immediate
handoff return leg_outgoing "RESULT=25"
handoff return leg_outgoing "SONG=hello_world.au;VOLUME=25"
The infotag get command retrieves information from a call leg, call, script, or system. The information retrieved is based on the info-tag specified.
infotag get info-tag [parameter-list]
The arguments of this command are:
The information requested.
Immediate
set dnis [infotag get leg_dnis]
set language [infotag get med_language]
set leg_list2 [infotag get leg_legs]
Some info-tags have specific scopes of access. For example, you cannot call evt_dcdigits while handling the ev_setup_done event. In other words, if the previous command is leg setup and the ev_setup_done event has not yet returned, then you cannot execute an infotag get evt_dcdigits command, or the script terminates with error output. For more information, see the "Information Tags" section.
The infotag set command allows you to set information in the system. This command works only with info-tags that are writable.
infotag set {info-tag [parameters]} value
The arguments of this command are:
None
Immediate
infotag set med_language prefix ch
infotag set med_location ch 0 tftp://www.cisco.com/mediafiles/Chinese
The leg collectdigits command instructs the system to collect digits on a specified call leg against a dial plan, a list of patterns, or both.
leg collectdigits {legID | info-tag} [param [match]]
The arguments of this command are:
None
When the command finishes, the script receives an ev_collectdigits_done event, which contains the success or failure code and the digits collected. For more information about the success and failure codes, see the "Status Codes" section.
Example 1 - Collect digits to match dialplan:
set params(interruptPrompt) true
set params(dialPlan) true
leg collectdigits $legID params
Example 2 - Collect digits to match a pattern:
set pattern(1) "99.....9*"
set pattern(2) "88.....9*"
leg collectdigits $legID params pattern
The leg connect command sends a signaling level CONNECT message to the incoming call leg.
leg connect {legID | info-tag }
The arguments of this command are:
None
Immediate
leg connect leg_incoming leg connect $legID
The leg disconnect command disconnects one or more call legs that are not part of any connection.
leg disconnect {legID | info-tag} [cause_code]
The arguments of this command are:
None
When the command finishes, the script receives an ev_disconnect_done event.
leg disconnect leg_incoming
leg disconnect leg_outgoing
leg disconnect leg_all
leg disconnect 25
leg disconnect $callId
leg disconnect [info-tag get evt_legs]
The leg proceeding command sends a call proceeding message to the incoming call leg. The gateway is responsible for translating this message into the appropriate protocol message (depending on the call leg) and sending them to the caller.
 | Caution The ISDN state machine actually connects the incoming call on a setup acknowledgement. |
leg proceeding {legID | info-tag}
The arguments of this command are:
None
Immediate
leg proceeding leg_incoming
The leg setup command requests the system to place an outgoing call to the specified destination numbers.
leg setup {destination | array-of-destinations} callinfo {legID | info-tag}
The arguments of this command are:
None
When the command finishes, the script receives an ev_setup_done event.
set callInfo(alertTime) 25
leg setup 9857625 callInfo leg_incoming
set destinations(1) 9787659
set destinations(2) 2621336
leg setup destinations callInfo leg_incoming
The leg setupack command sends a setup acknowledgement message on the specified incoming call leg.
leg setupack {legID | info-tag}
The arguments of this command are:
None
Immediate
leg setupack leg_incoming
The media pause command temporarily pauses the prompt that is currently playing on the specified call leg.
media pause {legID | info-tag}
The arguments of this command are:
None
Immediate
media pause $legID
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The media play command plays the specified prompt on the specified call leg.
media play {legID | info-tag} url-list
The arguments of this command are:
None
When the command finishes, the script receives an ev_media_done event. If a seek is done on this playing stream and the seek goes beyond the end of the prompt, the script still receives an ev_media_done event. However, if the prompt is terminated by a media stop command, the script does not receive an ev_media_done event.
media play $legID "_welcome.au" "%a$amt %s1000 en_enter_dest.au"
media play $legID "flash:message1.au rtspu://realplayer.com/audio/weather.ra"
set prompts "flash:prompt1.au ftp://dirt/sarvi/welcome.au %a285"
media play $legID $prompts _hello.au flash:welcome.au
media play $legID %c1 _welcome.au %c2 _welcome.au %c3 _welcome.au
media play $legID %i3
The media resume command resumes play of the prompt that is currently paused on the specified call leg.
media resume {legID | info-tag}
The arguments of this command are:
None
Immediate
media resume $legID
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The media seek command does a relative seek on the prompt that is currently playing. This command moves the prompt forward the specified number of seconds within the message.
media seek {legID | info-tag} time-in-seconds
The arguments of this command are:
None
Immediate
media seek $legID +25
media seek $legID -10
The media stop command stops the prompt that is currently playing on the specified call leg.
media stop {legID | info-tag}
The arguments of this command are:
None
Immediate. However, the script receives an ev_media_done event if the prompt completed prior to being stopped.
media stop $legID
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The playtone command plays a tone on the specified call leg. If a conference is in session, the digital signaling processor (DSP) stops sending data to the remote end while playing a tone. This command is typically used to give the caller a dial tone if the script needs to collect digits.
playtone {legID | info-tag} {Tone | StatusCode}
The arguments of this command are:
None
Immediate
playtone leg_incoming [getInfo evt_status]
playtone leg_all tn_oos
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The puts command outputs a debug string to the console if the IVR state debug flag is set (using the debug voip ivr script command).
puts string
The argument of this command is:
None
None
puts "Hello $name"
The requiredversion command verifies that the script is running the correct version of the TCL IVR API.
requiredversion majorversion.minorversion
The arguments of this command are:
None
None
requiredversion 2.5
If the version of the script does not match the major version specified or is not equal to or greater than the minor version specified, the script terminates and an error is displayed at the console.
The timer left command returns the number of seconds left on an active timer.
timer left type [legID | info-tag]
The arguments of this command are:
None
Immediate
set time [timer left call_timer0]
set time [timer left leg_timer $legID2]
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The timer start command starts a timer for a specified number of seconds for the whole call or for specified call leg.
timer start type time [legID | info-tag]
The arguments of this command are:
None
When the timer expires, the script receives an ev_call_timer0 or an ev_leg_timer event.
timer start call_timer0 30
timer start leg_timer 65 $legID2
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The timer stop command stops a timer.
timer stop type [legID | info-tag]
The arguments of this command are:
None
None
timer stop call_timer0
timer stop leg_timer $legID2
If the specified call leg is invalid, the script terminates and displays an error to the console, and the call is cleared.
The following events can be received by the TCL IVR script. Any events received that are not included below are ignored.
| Event | Description |
|---|---|
ev_any_event | A special wildcard event that can be used in the state machine to represent any event that might be received by the script. |
ev_authorize_done | Indicates the completion of the aaa authorize command. You can use the evt_status info-tag to determine the authorization status (whether it succeeded or failed). |
ev_authenticate_done | Indicates the completion of the authentication command. You can use the evt_status info-tag to determine the authentication status (whether it succeeded or failed). |
ev_call_timer0 | Indicates that the call-level timer expired. |
ev_collectdigits_done | Indicates the completion of the leg collectdigits command on the call leg. You can then use the evt_status info-tag to determine the status of the command completion. You can use the evt_dcdigits info-tag to retrieve the collected digits. |
ev_create_done | Indicates the completion of the connection create command. You can use the evt_connection info-tag to determine the ID of the completed connection. |
ev_destroy_done | Indicates the completion of the connection destroy command. You can use the evt_connection info-tag to determine the ID of the connection that was destroyed. |
ev_digit_end | Indicates that a digit key is pressed and released. You can use the evt_digit info-tag to determine which digit was pressed. You can use the evt_digit_duration info-tag to determine how long (in seconds) the digit was pressed. This can be used to detect long pounds or long digits. |
ev_disconnect_done | Indicates that the call leg has been cleared. |
ev_disconnected | Indicates that one of the call legs needs to disconnect. Upon receiving this event, the script must issue a leg disconnect on that call leg. You can use the evt_legs info-tag to determine which call leg disconnected. |
ev_grab | Indicates that an application that called this script is requesting that the script return the call leg. The script receiving this event can clean up and return the leg with a handoff return command. Whether this is done is at the discretion of the script receiving the ev_grab event. |
ev_hookflash | Indicates a hook flash (such as a quick onhook-offhook in the middle of a call), assuming that the underlying platform or interface supports hook flash detection. |
ev_handoff | Indicates that the script received one or more call legs from another application. When the script receives this event, you can use the evt_legs and the evt_connections info-tags to obtain a list of the call legs and connection IDs that accompanied the ev_handoff event. |
ev_leg_timer | Indicates that the leg timer expired. You can use the evt_legs info-tag to determine which leg timer expired. |
ev_media_done | Indicates that the prompt playout either completed or failed. You can use the evt_status info-tag to determine the completion status. |
ev_returned | Indicates that a call leg that was sent to another application (using handoff callappl) has been returned. This event can be accompanied by one or more call legs that were created by the called application. When the script receives this event, you can use the evt_legs and the evt_connections info-tags to obtain a list of the call legs and connection IDs that accompanied the ev_returned event. You can use the evt_iscommanddone info-tag to verify that all of the call legs sent have been accounted for, meaning that the handoff callappl command is complete. |
ev_setup_done | Indicates that the leg setup command has finished. You can then use the evt_status info-tag to determine the status of the command completion (whether the call was successfully set up or failed for some reason). |
ev_setup_indication | Indicates that the system received a call. This event and the ev_handoff event are the events that initiate an execution instance of a script. |
Information tags (info-tags) are identifiers that can be used to retrieve information about call legs, events, the script itself, current configuration, and values returned from RADIUS. Some info-tags have one or more parameters that are used to further identify the information to be retrieved, set, or modified.
Info-tags are grouped according to use. The first three characters of the info-tag label indicate the grouping.
This section lists the available info-tags and the following information about each:
Description | Returns the value of an AV-pair that was returned by RADIUS. After an authorize command finishes, the RADIUS server could have returned parameters as av-pairs. This info-tag along with aaa_avpair_exists is used to check if a parameter was returned and if it was, to get the value. Refer to the table in AV Pair Names, for a list of valid VSA avpair names. |
Syntax | infotag get aaa_avpair avpair-name |
Mode | Read |
Scope | Global |
Return Type | String, Number, Boolean (1 or 0), or any other value that is configured or returned through RADIUS. |
Direct Mapping | None |
Description | Returns an indication of whether the RADIUS has determined a VSA avpair exists. After an authorize command completes the RADIUS server could have returned parameters as av-pairs. This info-tag along with aaa_avpair is used to check if a parameter was returned and if it has, to get the value. Refer to the table in AV Pair Names, for a list of valid VSA avpair names. |
Syntax | infotag get aaa_avpair_exists avpair-name |
Mode | Read |
Scope | Global |
Return Type | Boolean (1 = true; 0=false) |
Direct Mapping | None |
The info-tag aaa_avpair_exists can be used to check the availability of a VSA. The info-tag aaa_avpair can be used to access the value returned in this VSA. The valid VSA names that can be passed parameters to these commands are the following.
| Type | Name | Description |
|---|---|---|
aaa | h323-ivr-in | A generic VSA for the billing server to send any information to the gateway in the form of an avpair like "color:blue" or "advprompt:rtsp://www.cisco.com/rtsp/areyouready.au" |
| h323-ivr-out | A generic VSA for the gateway to send any information to the billing server in the form of an avpair like "color:blue" or "advprompt:rtsp://www.cisco.com/rtsp/areyouready.au" |
| h323-credit-amount | The credit amount remaining in the account is returned. |
| h323-credit-time | The credit time remaining in the account is returned. |
| h323-prompt-id | The ID of the prompt is returned. |
| h323-redirect-number | The number for redirection of a call is returned. |
| h323-redirect-ip-addr | The IP address for the preferred route is returned. |
| h323-preferred-lang | The language that the billing system returns as the preferred language of the end user. Currently, three languages are supported; en (english), sp (spanish) and ch (mandarin). You can define additional languages as needed. |
| h323-time-and-day | The current time and day at the destination. |
| h323-return-code | This information is returned only after an authorization command is issued. It returns either a numerical value or "Unknown variable name." The numerical value indicates what action the IVR application should take, namely to play a particular audio file to inform the end user of the reason for the failed authorization. If "Unknown variable name" is returned, this indicates that the external AAA server is out of service. |
| h323-billing-model | Indicates the billing model used for the call. Initial values: 0=Credit, 1=Debit. Note: The debit card application assumes a Debit billing model. |
| h323-currency | ISO currency to indicate what units to use in playing the remaining balance. Note: the debit card application assumes units of preferred_language_dollar.au and preferred_language_cent.au. |
Description | Returns the value of an AV-pair that was configured through the CLI. |
Syntax | infotag get cfg_avpair avpair-name |
Mode | Read |
Scope | Global |
Return Type | String, Number, Boolean (1 or 0), or any other value that is configured or returned through RADIUS. |
Direct Mapping | None |
Description | Returns an indication of whether the specified parameter or AV-pair was configured through the CLI. |
Syntax | infotag get cfg_avpair_exists avpair-name |
Mode | Read |
Scope | Global |
Return Type | Boolean (1 = true; 0=false) |
Direct Mapping | None |
Description | Returns or maps to a list of all the connection IDs in the script. |
Syntax | infotag get con_all |
Mode | Read |
Scope | Global |
Return Type | Number list |
Direct Mapping | Connections |
Description | Gets a list of all the connections the leg is a part of. This does not include those connections that are in Creation or under Destruction. The info-tag should map to just one leg. |
Syntax | infotag get con_ofleg {info-tag | legID} |
Mode | Read |
Scope | Global |
Return Type | Number list |
Direct Mapping | Connections |
Description | Returns a list of connection IDs associated with the event received. |
Syntax | infotag get evt_connections |
Mode | Read |
Scope | ev_handoff |
Return Type | Number list |
Direct Mapping | Connections |
Description | Returns the digits collected by the leg collectdigits command. |
Syntax | infotag get evt_dcdigits |
Mode | Read |
Scope | ev_collectdigits_done |
Return Type | String |
Direct Mapping | None |
Description | Returns the digit key that was pressed. |
Syntax | infotag get evt_digit |
Mode | Read |
Scope | ev_digit_end |
Return Type | String |
Direct Mapping | None |
Description | Returns the duration of the digit that was pressed. |
Syntax | infotag get evt_digit_duration |
Mode | Read |
Scope | ev_digit_end |
Return Type | Number |
Direct Mapping | None |
Description | Returns the name of the event received. |
Syntax | infotag get evt_event |
Mode | Read |
Scope | Global |
Return Type | String |
Direct Mapping | None |
Description | Returns an indication of whether the command has finished. |
Syntax | infotag get evt_iscommanddone |
Mode | Read |
Scope | ev_returned |
Return Type | Boolean (1 = true; 0 = false) |
Direct Mapping | None |
Description | Returns the handoff string when one or more call legs are handed off or returned to the script. |
Syntax | infotag get evt_ho_string |
Mode | Read |
Scope | ev_handoff |
Return Type | String |
Direct Mapping | None |
Description | Returns a list of leg IDs associated with the event received. For information about which legs the evt_legs info-tag returns for a specific event, see the "Events" section. |
Syntax | infotag get evt_legs |
Mode | Read |
Scope | ev_leg_timer |
Return Type | Number list |
Direct Mapping | Legs |
Description | Returns the status of the event received. This info-tag is valid only in the scope of the function handling the event. For a list of possible statuses, see the "Status Codes" section. |
Syntax | infotag get evt_status |
Mode | Read |
Scope | ev_setup_done |
Return Type | String |
Direct Mapping | None |
Description | Returns or maps to one or more call legs. This is the union of leg_incoming and leg_outgoing. |
Syntax | infotag get leg_all |
Mode | Read |
Scope | Global |
Return Type | Number list |
Direct Mapping | Legs |
Description | Returns the ANI field of CallInfo. |
Syntax | infotag get leg_ani [legID] If no leg ID is specified, this info-tag returns the ANI field of the first incoming call leg. Not specifying a leg ID works only if there is at least one incoming call leg. If a leg ID is specified, this info-tag returns the ANI field of that call leg. If the call leg is not valid, the script terminates with error output. |
Mode | Read |
Scope | Global |
Return Type | String |
Direct Mapping | None |
Description | Returns the DNIS field of CallInfo. |
Syntax | infotag get leg_dnis [legID] If no leg ID is specified, this info-tag returns the DNIS field of the first incoming call leg. Not specifying a leg ID works only if there is at least one incoming call leg. If a leg ID is specified, this info-tag returns the DNIS field of that call leg. If the call leg is not valid, the script terminates with error output. |
Mode | Read |
Scope | Global |
Return Type | String |
Direct Mapping | None |
Description | Returns or maps to one or more incoming call legs. |
Syntax | infotag get leg_incoming |
Mode | Read |
Scope | Global |
Return Type | Number list |
Direct Mapping | Legs |
Description | Gets a list of legs that are part of this connection. The info-tag parameter maps to just one connection. |
Syntax | infotag get inconnection {connID | info-tag} |
Mode | Read |
Scope | Global |
Return Type | Number list |
Direct Mapping | Legs |
Description | Returns the DID field of CallInfo. This is a Boolean field (1 and 0) that reflects the FinalDestination flag of the call leg. |
Syntax | infotag get leg_isdid [legID] If no leg ID is specified, this info-tag returns the DID field of the first incoming call leg. Not specifying a leg ID works only if there is at least one incoming call leg. If a leg ID is specified, this info-tag returns the DID field of that call leg. If the call leg is not valid, the script terminates with error output. |
Mode | Read |
Scope | Global |
Return Type | Boolean (1 = true; 0 = false) |
Direct Mapping | None |
Description | Returns or maps to one or more outgoing call legs. |
Syntax | infotag get leg_outgoing |
Mode | Read |
Scope | Global |
Return Type | Number list |
Direct Mapping | Legs |
Description | Returns the minimum of the OSP settlement time (in seconds) associated with the list of specified legs. |
Syntax | infotag get leg_settlement_time {legID | info-tag} [minimum] If you specify minimum, this returns the minimum of the OSP settlement time of the list of legs and the value of the AAA avpair creditTime. This AAA avpair creditTime was returned by a previous aaa authorize command. If all credit times are uninitialized, "uninitialized" is returned. If all have unlimited time, or if one is uninitialized and the others have unlimited time, "unlimited" is returned. |
Mode | Read |
Scope | Global |
Return Type | Number |
Direct Mapping | None |
Description | Returns or sets the backup server. This is applicable for RTSP-based prompts. If the script attempts to play a prompt using a URL and the URL fails, it reattempts to play the URL from list of backup servers by replacing the server portion of the URL. For example, if the script had tried (but failed) to play a prompt from: rtsp://www.cisco.com:5554/audiofiles/english/anounce.au and the backup server 0 was configured as: rtsp://www.real.com/cisco/ then the backup URL attempted would be: rtsp://www.real.com/cisco/audiofiles/english/anounce.au There can be a maximum of two backup servers configured (0 and 1). This info-tag applies only to streams on which you have not played any prompts. Therefore, this is typically used in the one-time initialization section of the script. |
Syntax | infotag get med_backupserver index infotag set med_backupserver index server-URL |
Mode | Read/Write |
Scope | Global |
Return Type | String |
Direct Mapping | None |
Description | Returns or sets the current active language for media playout. This info-tag returns the language index or the language prefix (depending on whether prefix is specified) for the currently active language. |
Syntax | infotag get med_language [prefix] infotag set med_language [index | prefix prefix] |
Mode | Read/Write |
Scope | Global |
Return Type | String/Number |
Direct Mapping | None |
Description | Returns or sets the mapping between the language index and the language prefix. This info-tag returns the language index or the language prefix (depending on whether prefix is specified) for the currently active language. |
Syntax | infotag get med_language_map [index | prefix prefix] infotag set med_language_map index prefix |
Mode | Read/Write |
Scope | Global |
Return Type | String/Number |
Direct Mapping | None |
Description | Returns or sets the language locations for all the languages the script will use. The language prefix, category, and location are the same as those configurable from the command line interface (CLI). |
Syntax | infotag get med_location prefix category infotag set med_location prefix category location |
Mode | Read/Write |
Scope | Global |
Return Type | String |
Direct Mapping | None |
Description | Returns the total number of languages configured. |
Syntax | infotag get med_total_languages |
Mode | Read |
Scope | Global |
Return Type | Number |
Direct Mapping | None |
Description | Returns the version of the TCL IVR API. |
Syntax | infotag get sys_version |
Mode | Read |
Scope | Global |
Return Type | String |
Direct Mapping | None |
The evt_status info-tag returns a status code for the event received. This sections lists the possible status codes and their meaning.
Status codes are grouped according to function. The first two characters of the status code indicate the grouping.
Authentication status is reported in au_xxx format:
| Value for xxx | Description |
|---|---|
000 | Authentication was successful. |
001 | Authentication failed. |
Authorization status is reported in ao_xxx format:
| Value for xxx | Description |
|---|---|
000 | Authorization was successful. |
001 | Authorization failed. |
Media status is reported in ms_xyy format:
| x indicates the command | yy indicates the status of the command | ||
|---|---|---|---|
| Value for x | Description | Value for yy | Description |
0 | Status for a media play command. | 00 | The command was successful and the prompt finished.1 |
2 | Status for a media stop command. | 01 | Failure. |
3 | Status for a media pause command. | 02 | Unsupported feature or request. |
4 | Status for a media resume command. | 03 | Invalid host or URL specified. |
5 | Status for a media seek command to forward. | 04 | Received disconnected. |
6 | Status for a media seek command to rewind. | 05 | The prompt was interrupted by a key press. |
| 1Valid for the media play command only, because media_done events are not received for successful completion of other media commands. |
Leg setup status is reported in ls_xxx format:
| Value for xxx | Description |
|---|---|
000 | The call is active or was successful. |
001 | The outgoing call leg was looped. |
002 | The call setup timed out (meaning that the destination phone was alerting, but no one answered). The limit of this timeout can be specified in the leg setup command. |
003 | The call setup failed due to a lack of resources in the network. |
004 | The call setup failed because of an invalid number. |
005 | The call setup failed for reasons other than a lack of resources or an invalid number. |
006 | The destination was busy. |
007 | The incoming side of the call disconnected. |
008 | The outgoing side of the call disconnected. |
009 | The conferencing or connecting of the two call legs failed. |
010 | Supplementary services internal failure. |
011 | Supplementary services failure. |
012 | Supplementary services failure. Inbound call leg was disconnected. |
Digit collection status is reported in cd_xxx format:
| Value for xxx | Description |
|---|---|
001 | The digit collection timed out, because no digits were pressed and not enough digits were collected for a match. |
002 | The digit collection was aborted, because the user pressed an abort key. |
003 | The digit collection failed, because the buffer overflowed and not enough digits were collected for a match. |
004 | The digit collection succeeded with a match to the dial plan. |
005 | The digit collection succeeded with a match to one of the patterns. |
006 | The digit collection failed, because the number collected was invalid. |
007 | The digit collection was terminated, because an ev_disconnected event was received on the call leg. |
008 | The digit collection was terminated, because an ev_grab event was received on the call leg. |
009 | The digit collection successfully turned on digit reporting to the script. |
010 | The digit collection was terminated because of an unsupported or unknown feature or event. |
Disconnect causes use the format di_xxx where xxx is the Q931 cause code. Possible values are:
| Value for xxx | Description |
|---|---|
000 | Uninitialized |
001 | Unassigned number |
002 | No route to the transit network |
003 | No route to the destination |
004 | Send information tone |
005 | Misdialed trunk prefix |
006 | Unacceptable channel |
007 | Call awarded |
008 | Preemption |
009 | Preemption reserved |
016 | Normal |
017 | Busy |
018 | No response from the user |
019 | No answer from the user |
020 | Subscriber is absent |
021 | Call rejected |
022 | Number has changed |
026 | Selected user is clearing |
027 | Destination is out of order |
028 | Invalid number |
029 | Facility rejected |
030 | Response to status inquiry |
034 | No circuit available |
035 | Requested VPCI VCI is not available |
036 | VPCI VCI assignment failure |
037 | Cell rate is not available |
038 | Network is out of order |
039 | Permanent frame mode is out of service |
040 | Permanent frame mode is operational |
041 | Temporary failure |
042 | Switch is congested |
043 | Access information has been discarded |
044 | No required circuit |
045 | No VPCI VCI is available |
046 | Precedence call blocked |
047 | No resource available |
048 | DSP error |
049 | QoS is not available |
050 | Facility is not subscribed |
053 | Outgoing calls barred |
055 | Incoming calls barred |
057 | Bearer capability is not authorized |
058 | Bearer capability is not available |
062 | Inconsistency in the information and class |
063 | Service or option not available |
065 | Bearer capability is not implemented |
066 | Change type is not implemented |
069 | Facility is not implemented |
070 | Restricted digital information only |
079 | Service is not implemented |
081 | Invalid call reference value |
082 | Channel does not exist |
083 | Call exists and call ID in use |
084 | Call ID in use |
085 | No call suspended |
086 | Call cleared |
087 | User is not in CUG |
088 | Incompatible destination |
090 | CUG does not exist |
091 | Invalid transit network |
093 | AAL parameters not supported |
095 | Invalid message |
096 | Mandatory Information Element (IE) is missing |
097 | Message type is not implemented |
098 | Message type is not compatible |
099 | IE is not implemented |
100 | Invalid IE contents |
101 | Message in incomplete call state |
102 | Recovery on timer expiration |
103 | Non-implemented parameter was passed on |
110 | Unrecognized parameter message discarded |
111 | Protocol error |
127 | Internetworking error |
128 | Next node is unreachable |
129 | Holst Telephony Service Provider Module (HTSPM) is out of service |
160 | DTL transit is not my node ID |
AAA--Authentication, authorization, and accounting. A suite of network security services that provides the primary framework through which you can set up access control on your Cisco router or access server.
ANI--Automatic number identification. Same as calling party.
API--Application programming interface.
AV-pair--An attribute-value pair used in authentication.
CDR--Call data record.
CLI--Command line interface.
connection--The tying together of two streams or call legs so that the incoming voice stream of one call leg is sent as the outgoing voice stream of the other call leg.
DID--Dial in direct. Calls in which the gateway uses the number that you initially dialed (DNIS) to make the call, as opposed to prompting you to dial additional digits.
DNIS--Dialed number identification service. Same as the called number.
DSP--Digital signaling processor.
DTMF--Dual tone multifrequency. Use of two simultaneous voice-band tones for dialing (such as touch tone).
execution instance--An instance of the TCL interpreter that is created to execute the script.
FSM--Finite State Machine.
gatekeeper--A gatekeeper maintains a registry of devices in the multimedia network. The devices register with the gatekeeper at startup and request admission to a call from the gatekeeper.
The gatekeeper is an H.323 entity on the LAN that provides address translation and control access to the LAN for H.323 terminals and gateways. The gatekeeper can provide other services to the H.323 terminals and gateways, such as bandwidth management and locating gateways.
gateway--A gateway allows H.323 terminals to communicate with non-H.323 terminals by converting protocols. A gateway is the point where a circuit-switched call is encoded and repackaged into IP packets.
An H.323 gateway is an endpoint on the LAN that provides real-time, two-way communications between H.323 terminals on the LAN and other ITU-T terminals in the WAN or to another H.323 gateway.
IFS--Cisco IOS file system.
information-tag--An information identifier used to retrieve and set system variables and information.
ISDN--Integrated Services Digital Network. Communication protocol, offered by telephone companies, that permits telephone networks to carry data, voice, and other source traffic.
IVR--Interactive voice response. When someone dials in, IVR responds with a prompt to get a personal identification number (PIN), and so on.
leg--A control or voice stream to an external endpoint through a telephony, VoIP, VoFR, or other protocol and transport medium.
OSP--Open Settlement Protocol. Protocol used to allow carriers to communicate with third-party settlement servers.
PIN--Personal identification number. Password used with account number for authentication.
POTS--Plain old telephone service. Basic telephone service supplying standard single line telephones, telephone lines, and access to the PSTN.
PSTN--Public Switched Telephone Network. PSTN refers to the local telephone company.
RADIUS--Remote Access Dial-In User Service. Database for authenticating modem and ISDN connections and for tracking connection time.
rotary--The concept of attempting to reach a specific destination by trying one dial peer at a time (if a dial peer match for a destination returns multiple dial peers, meaning multiple routes).
RTSP--Real Time Streaming Protocol.
SPI--Service Provider Interface (such as H.323 SPI, VTSP SPI, and SIP SPI).
TCL--Tool Command Language. TCL is an interpreted script language developed by Dr. John Ousterhout of the University of California, Berkeley, and is now developed and maintained by
Sun Microsystems Laboratories.
Tcl_Eval--An API provided by the TCL interpreter interface to execute a TCL script or procedure.
TTS--Text-to-Speech.
URL--Universal Resource Locator. Standardized addressing scheme for accessing hypertext documents and other services using a browser.
VoFR--Voice over Frame Relay. Voice over Frame Relay enables a router to carry voice traffic (for example, telephone calls and faxes) over a Frame Relay network. When sending voice traffic over Frame Relay, the voice traffic is segmented and encapsulated for transit across the Frame Relay network using FRF.12 encapsulation.
VoIP--Voice over IP. The ability to carry normal telephone-style voice signals over an IP-based network with POTS-like functionality, reliability, and voice quality. VoIP is a blanket term that generally refers to Cisco's open standards-based (for example, H.323) approach to IP voice traffic.
Cisco Connection Online (CCO) is Cisco Systems' primary, real-time support channel. Maintenance customers and partners can self-register on CCO to obtain additional information and services.
Available 24 hours a day, 7 days a week, CCO provides a wealth of standard and value-added services to Cisco's customers and business partners. CCO services include product information, product documentation, software updates, release notes, technical tips, the Bug Navigator, configuration notes, brochures, descriptions of service offerings, and download access to public and authorized files.
CCO serves a wide variety of users through two interfaces that are updated and enhanced simultaneously: a character-based version and a multimedia version that resides on the World Wide Web (WWW). The character-based CCO supports Zmodem, Kermit, Xmodem, FTP, and Internet e-mail, and it is excellent for quick access to information over lower bandwidths. The WWW version of CCO provides richly formatted documents with photographs, figures, graphics, and video, as well as hyperlinks to related information.
You can access CCO in the following ways:
For a copy of CCO's Frequently Asked Questions (FAQ), contact cco-help@cisco.com. For additional information, contact cco-team@cisco.com.
Cisco documentation and additional literature are available in a CD-ROM package, which ships with your product. The Documentation CD-ROM, a member of the Cisco Connection Family, is updated monthly. Therefore, it might be more current than printed documentation. To order additional copies of the Documentation CD-ROM, contact your local sales representative or call customer service. The CD-ROM package is available as a single package or as an annual subscription. You can also access Cisco documentation on the World Wide Web at http://www.cisco.com, http://www-china.cisco.com, or http://www-europe.cisco.com.
If you are reading Cisco product documentation on the World Wide Web, you can submit comments electronically. Click Feedback in the toolbar and select Documentation. After you complete the form, click Submit to send it to Cisco. We appreciate your comments.
Posted: Mon Aug 7 19:25:17 PDT 2000
Copyright 1989-2000©Cisco Systems Inc.