IVR consists of simple voice prompting and digit collection to gather caller information for authenticating the user and identifying the destination. IVR applications can be assigned to specific ports or invoked on the basis of DNIS. An IP public switched telephone network gateway can have several IVR applications to accommodate many different gateway services, and you can customize the IVR applications to present different interfaces to the various callers.

IVR systems 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) signalling. 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 an account number. After playing the voice prompt, the IVR application collects the predetermined number of touch tones and then places the call to the destination phone or system.

IVR uses TCL scripts gather information and to process accounting and billing. For example, a TCL IVR script plays when a caller receives a voice-prompt instruction to enter a specific type of information, such as a personal identification number (PIN). After playing the voice prompt, the TCL IVR application collects the predetermined number of touch tones and sends the collected information to an external server for user authentication and authorization.

Note	Audio playback is not supported when Secure Real-Time Transport Protocol (SRTP) is used with TCL IVR applicatoins.

Since the introduction of the Cisco IVR technology, the software has undergone several enhancements. TCL IVR Version 2.0 is made up of separate components that are described individually in the sections that follow. The enhancements are as follows:

• Real Time Streaming Protocol (RTSP) client implementation

• TCL IVR prompt playout and digit collection on IP call legs

• New TCL verbs to utilize RTSP scripting features

The enhancements add scalability and enable the TCL IVR scripting functionality on VoIP legs. In addition, support for RTSP enables VoIP gateways to play messages from RTSP-compliant announcement servers. The addition of these enhancements also reduces the CPU load and saves memory on the gateway because no packetization is involved. Larger prompts can be played, and the use of an external audio server is allowed.

Note	TCL IVR 2.0 removed the signature locking mechanism requirement.

RTSP is an application-level protocol used for control over the delivery of data that has real-time properties. Using RTSP also enables an external RTSP server to play anouncements and interact with voice mail servers. It provides an extensive framework to enable control and to perform on-demand delivery of real-time data. For example, RTSP is used to control the delivery of audio streams from an audio server.

If you use an RTSP server in your network with VoIP gateways, a scripting application can run on the gateway and connect calls with audio streams from an external audio server. Using RTSP also has the following benefits:

• Reduces the CPU load

• Allows large prompts to be played that previously demanded high CPU usage from the gateway

• Saves memory on the gateway because no packetization is involved

• Allows use of an external audio server which removes the limitation on the number of prompts that can be played out and on the size of the prompt

TCL IVR Version 2.0 scripts can be configured for incoming plain old telephone service (POTS) or VoIP call legs to play announcements to the user or collect user input (digits). With TCL IVR Version 2.0 the prompts can be triggered from both the PSTN side of the call leg and the IP side of the call leg. This feature enables the audio files (or prompts) to be played out over the IP network.

TCL IVR scripts played toward a VoIP call leg are subject to the following conditions:

• G.711 mu-law encoding must be used when prompts are played.

• G.711 mu-law encoding must also be used for the duration of these calls, even after prompt playout has completed.

• Digital signaling protocols (DSPs) can not be on the IP call leg so the script cannot initiate a tone.

• When an TCL IVR script is used to collect digits on a VoIP call leg, one of the following DTMF relay methods must be used.

  • For H.323 protocol configured on the call leg, use one of the following DTMF relay methods: Cisco proprietary RTP, H.245 Alphanumeric IE, or H.245 Signal IE

  • For SIP protocol configured on the call leg, use Cisco proprietary RTP

Note	For additional information about the dtmf-relay command, refer to the Cisco IOS Voice Command Reference - D through I.

IVR 2.0 enables the system to accept calls initiated from the IP side of the network using G.711, and terminate calls to the terminating gateway using the same codec. IVR Control of Scripts on an IP Call Leg displays the TCL IVR application on the gateways controlling the scripts. IP phones can also originate a call to a gateway running an TCL IVR script.

TCL IVR, Version 2.0, delivers a new set of TCL verbs and scripts that replace the previous TCL version. The new TCL verbs enable the user to:

• Utilize the RTSP audio servers

• Develop TCL scripts that interact with the IVR application

• Pass events to the Media Gateway Controller, which is a call agent

TCL IVR Version 2.0 is not backward compatible with the IVR 1.0 scripts.

Note	For in-depth information about the TCL 2.0 verb set and how to develop scripts, refer to Cisco.com (Related Documentation index).

TCL IVR scripts use the TCL verbs to interact with the gateway during call processing in order to collect the required digits—for example, to request the PIN or account number for the caller. The TCL scripts are the default scripts for all Cisco voice features using IVR. TCL scripts are configured to control calls coming into or going out of the gateway.

Note	Ensure that you have loaded the version of TCL scripts that support IVR Version 2.

The TCL IVR scripts shown below are listed as an example of the types of scripts available to be downloaded from the cisco.com Software Center. For a complete list of scripts, it is recommended that you check the Software Center.

Cisco provides the following IVR scripts:

• fax_hop_on_1—Collects digits from the redialer, such as account number and destination number. When a call is placed to an H.323 network, the set of fields (configured in the call information structure) are "entered", "destination", and "account".

• clid_authen—Authenticates the call with automatic number identification (ANI) and DNIS numbers, collects the destination data, and makes the call.

• clid_authen_npw—Performs as clid_authen, but uses a null password when authenticating, rather than DNIS numbers.

• clid_authen_collect—Authenticates the call with ANI and DNIS numbers and collects the destination data. If authentication fails, it collects the account and password.

• clid_authen_col_npw—Performs as clid_authen_collect, but uses a null password and does not use or collect DNIS numbers.

• clid_col_npw_3—Performs as clid_authen_col_npw except with that script, if authentication with the digits collected (account and PIN) fails, the clid_authen_col_npwscript just plays a failure message (auth_failed.au) and then hangs up. The clid_col_npw_3 script allows two failures, then plays the retry audio file (auth_retry.au) and collects the account and PIN again.

• The caller can interrupt the message by entering digits for the account number, triggering the prompt to tell the caller to enter the PIN. If authentication fails the third time, the script plays the audio file auth_fail_final.au, and hangs up.

Table 1 lists the prompt audio files associated with the clid_col_npw_3script.

Table 2 lists additional audio files associated with the clid_col_npw_3script.

• clid_col_npw_npw—Tries to authenticate by using ANI, null as the user ID, user, and user password pair. If that fails, it collects an account number and authenticates with account and null. It allows three tries for the caller to enter the account number before ending the call with the authentication failed audio file. If authentication succeeds, it plays a prompt to enter the destination number.

Table 3 lists the audio files associated with the clid_col_npw_npw script.

• clid_col_dnis_3.tcl—Authenticates the caller ID three times. First it authenticates the caller ID with DNIS. If that is not successful, it attempts to authenticate with the caller PIN up to three times.

• clid_col_npw_3.tcl—Authenticates with null. If authentication is not successful, it attempts to authenticate by using the caller PIN up to 3 times.

• clid_4digits_npw_3.tcl—Authenticates with null. If the authentication is not successful, it attempts to authenticate with the caller PIN up to 3 times using the 14-digit account number and password entered together.

• clid_4digits_npw_3_cli.tcl— Authenticates the account number and PIN respectively by using ANI and null. The number of digits allowed for the account number and password are configurable through the CLI. If the authentication fails, it allows the caller to retry. The retry number is also configured through the CLI.

• clid_authen_col_npw_cli.tcl—Authenticates the account number and PIN respectively using ANI and null. If the authentication fails, it allows the caller to retry. The retry number is configured through the CLI. The account number and PIN are collected separately.

• clid_authen_collect_cli.tcl—Authenticates the account number and PIN by using ANI and DNIS. If the authentication fails, it allows the caller to retry. The retry number is configured through the CLI. The account number and PIN are collected separately.

• clid_col_npw_3_cli.tcl—Authenticates by using ANI and null for account and PIN respectively. If the authentication fails, it allows the caller to retry. The retry number is configured through the CLI.

• clid_col_npw_npw_cli.tcl—Authenticates by using ANI and null for account and PIN respectively. If authentication fails, it allows the caller to retry. The retry number is configured through the CLI. The account number and PIN are collected together.

Note	To display the contents of the TCL IVR script, use the show call application voice command.

Before you configure your Cisco gateway to support TCL IVR, you must perform the following prerequisite tasks:

• Configure VoIP to support H.323-compliant gateways—meaning that in addition to the basic configuration tasks, such as configuring dial peers and voice ports, you must configure specific devices in your network to act as gateways.

• Configure a TFTP sever to perform storage and retrieval of the audio files, which are required by the Debit Card gateway or other features requiring TCL IVR scripts and audio files.

• Download the appropriate TCL IVR script from the Cisco.com. Use the copy command to copy your audio file (.au file) to your Flash memory, and the audio-prompt load command to read it into RAM. When you use TCL IVR applications, the gateway needs to know the URL where the TCL script can be found, as well as the URL of any audio file you want to use. Cisco IOS File System (IFS) is used 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. During configuration of the application, you specify the URLs for the script and for the audio prompt. See the "Using URLs in IVR Scripts" chapter in the TCL IVR API Version 2.0 Programmer's Guide for more information.

• Make sure that your audio files are in the proper format. The TCL IVR prompts require audio file (.au) format of 8-bit, u-law, and 8-khz encoding. To encode your own audio files, we recommend that you use one of these two audio tools (or a tool of similar quality):

  • Cool Edit, manufactured by Syntrillium Software Corporation

  • AudioTool, manufactured by Sun Microsystems

• Make sure that your access platform has a minimum of 16 MB Flash and 128MB of DRAM memory.

• Install and configure the appropriate RADIUS security server in your network. The version of RADIUS that you are using must be able to support IETF-supported vendor specific attributes (VSAs), which are implemented by using IETF RADIUS attribute 26.

Before starting the software configuration tasks for the TCL IVR Version 2.0 features, complete the following preinstallation tasks:

• Download the TCL scripts and audio files to be used with this feature from the Cisco.com.

• Store the TCL scripts and audio files on a TFTP server configured to interact with your gateway access server.

• Create the TCL IVR application script to use with the call application voice command when configuring IVR using TCL scripts. You create this application first and store it on a server or location where it can be retrieved by the access server.

• Define the call flow and pass the defined parameter values to the application. Depending on the TCL script you select, these values can include the language of the audio file and the location of the audio file. Table 1 lists the TCL scripts and the parameter values they require.

• Associate the application to the incoming POTS or VoIP dial peer.

Note

When an IVR script is used to detect a "long #" from a caller connected to the H.323 call leg, the DTMF method used must either be Cisco proprietary RTP or DTMF relay using H.245 signal IE. DTMF relay using H.245 alphanumeric IE does not report the actual duration of the digit, causing long pound (#) detection to fail.

Use the show running-config command to display the entire gateway configuration. Example Configuration Topology shows the type of topology used in the configuration for the example.

In this example configuration, GW1 is running TCL IVR for phone A, and GW2 is running TCL IVR for phone B.

This section provides the following configuration examples:

The following output is the result of using the show running-config command:

GW1
 Router# show running-config 

 Building configuration...

 Current configuration:

 ! Last configuration change at 08:39:29 PST Mon Jan 10 2000 by lab
 !
 version 12.2
 service timestamps debug datetime msec
 service timestamps log datetime msec
 no service password-encryption
 !
 hostname GW1
 !
 logging buffered 100000 debugging
 aaa new-model
 aaa authentication login default local group radius
 aaa authentication login h323 group radius
 aaa authentication login con none
 aaa authorization exec h323 group radius
 aaa accounting connection h323 start-stop group radius
 enable password xxx
 !
 username lab password 0 lab
 !
 resource-pool disable
 !
 clock timezone PST -8
 ip subnet-zero
 ip host baloo 1.14.124.xxx
 ip host dirt 223.255.254.254
 ip host rtspserver3 1.14.1xx.2
 ip host rtspserver1 1.14.1xx.2
 !
 mgcp package-capability trunk-package
 mgcp default-package trunk-package
 isdn switch-type primary-net5
 isdn voice-call-failure 0
 !
 tftp://dirt/hostname/WV/en_new/
 call application voice debit_card tftp://dirt/Router/scripts.new/app_debitcard.tcl 
 call application voice debit_card uid-len 6
 call application voice debit_card language 1 en
 call application voice debit_card language 2 ch
 call application voice debit_card set-location ch 0 tftp://dirt/hostname/WV/ch_new/
 call application voice debit_card set-location en 0 tftp://dirt/hostname/WV/en_new/
 call application voice debit_card_rtsp tftp://dirt/IVR 2.0/scripts.new/app_debitcard.tcl
 call application voice debit_card_rtsp uid-len 6
 call application voice debit_card_rtsp language 1 en
 call application voice debit_card_rtsp language 2 ch
 call application voice debit_card_rtsp set-location ch 0 rtsp://rtspserver1:554/
 call application voice debit_card_rtsp set-location en 0 rtsp://rtspserver1:554/

 mta receive maximum-recipients 0
 !
 controller E1 0
  clock source line primary
  pri-group timeslots 1-31
 !
 controller E1 1
 !
 controller E1 2
 !
 controller E1 3
 !
 gw-accounting h323
 gw-accounting h323 vsa
 gw-accounting voip
 !
 interface Ethernet0
  ip address 1.14.128.35 255.255.255.xxx
  no ip directed-broadcast
  h323-gateway voip interface
  h323-gateway voip id gk1 ipaddr 1.14.128.19 1xxx
  h323-gateway voip h323-id gw1@cisco.com
  h323-gateway voip tech-prefix 5#
 !
 interface Serial0:15
  no ip address
  no ip directed-broadcast
  isdn switch-type primary-net5
  isdn incoming-voice modem
  fair-queue 64 256 0
  no cdp enable
 !
 interface FastEthernet0
  ip address 16.0.0.1 255.255.xxx.0
  no ip directed-broadcast
  duplex full
  speed auto
  no cdp enable
 !
 ip classless
 ip route 0.0.0.0 0.0.0.0 1.14.128.33
 ip route 1.14.xxx.0 255.xxx.255.xxx 16.0.0.2
 ip route 1.14.xxx.16 255.xxx.255.240 1.14.xxx.33
 no ip http server
 !
 radius-server host 1.14.132.2 auth-port 1645 acct-port 1646
 radius-server key cisco
 radius-server vsa send accounting
 radius-server vsa send authentication
 !
 voice-port 0:D
  cptone DE
 !
 dial-peer voice 200 voip
  incoming called-number 53
  destination-pattern 34.....
  session target ipv4:16.0.0.2
  dtmf-relay h245-alphanumeric
  codec g711ulaw
 !
 dial-peer voice 102 pots
  application debit_card_rtsp
  incoming called-number 3450072
  shutdown
  destination-pattern 53.....
  port 0:D
 !
 dial-peer voice 202 voip
  shutdown
  destination-pattern 34.....
  session protocol sipv2
  session target ipv4:16.0.0.2
  dtmf-relay cisco-rtp
  codec g711ulaw
 !
 dial-peer voice 101 pots
  application debit_card
  incoming called-number 3450070
  destination-pattern 53.....
  port 0:D
 !
 gateway
 !
 line con 0
  exec-timeout 0 0
  transport input none
 line aux 0
 line vty 0 4
  password xxx
 !
 ntp clock-period 17180740
 ntp server 1.14.42.23
 end

 GW1#

The following output is the result of using the show running-config command:

GW2#
 Router# show running-config 

 Building configuration...

 Current configuration:
 !
 ! Last configuration change at 08:41:12 PST Mon Jan 10 2000 by lab
 !
 version 12.2
 service timestamps debug uptime
 service timestamps log uptime
 no service password-encryption
 !
 hostname GW2
 !
 logging buffered 100000 debugging
 aaa new-model
 aaa authentication login default local group radius
 aaa authentication login h323 group radius
 aaa authentication login con none
 aaa authorization exec h323 group radius
 aaa accounting connection h323 start-stop group radius
 !
 username lab password xxx
 username 111119 password xxx
 !
 resource-pool disable
 !
 clock timezone PST -8
 ip subnet-zero
 ip host radiusserver2 1.14.132.2
 ip host radiusserver1 1.14.138.11
 ip host baloo 1.14.124.254
 ip host rtspserver2 1.14.136.2
 ip host dirt 223.255.254.254
 ip host rtspserver3 1.14.126.2
 !
 mgcp package-capability trunk-package
 mgcp default-package trunk-package
 isdn switch-type primary-5ess
 isdn voice-call-failure 0
 !
 call application voice clid_authen_sky 
tftp://dirt/hostname/sky_scripts/clid_authen_collect_cli_sky.tcl

 call application voice rtsp_demo tftp://dirt/hostname/sky_scripts/rtsp_demo.tcl
 tftp://dirt/hostname/WV/en_new/
 call application voice debit_card tftp://dirt/IVR 2.0/scripts.new/app_debitcard.tcl
 call application voice debit_card uid-len 6
 call application voice debit_card language 1 en
 call application voice debit_card language 2 ch
 call application voice debit_card set-location ch 0 tftp://dirt/hostname/WV/ch_new/
 call application voice debit_card set-location en 0 tftp://dirt/hostname/WV/en_new/
 call application voice clid_authen_rtsp tftp://dirt/IVR 
2.0/scripts.new/app_clid_authen_collect_cli_rtsp.tcl 

 call application voice clid_authen_rtsp location rtsp://rtspserver2:554/
 call application voice clid_authen1 tftp://dirt/IVR 
2.0/scripts.new/app_clid_authen_collect_cli_rtsp.tcl
 call application voice clid_authen1 location tftp://dirt/hostname/WV/en_new/
 call application voice clid_authen1 uid-len 6
 call application voice clid_authen1 retry-count 4
 mta receive maximum-recipients 0
 !
 controller T1 0
  framing esf
  clock source line primary
  linecode b8zs
  pri-group timeslots 1-24
 !
 controller T1 1
  clock source line secondary 1
 !
 controller T1 2
 !
 controller T1 3
 !
 gw-accounting h323
 gw-accounting h323 vsa
 gw-accounting voip
 !
 interface Ethernet0
  ip address 1.14.xxx.4 255.255.xxx.240
  no ip directed-broadcast
  h323-gateway voip interface
  h323-gateway voip id gk2 ipaddr 1.14.xxx.18 1719
  h323-gateway voip h323-id gw2@cisco.com
  h323-gateway voip tech-prefix 3#
 !
 interface Serial0:23
  no ip address
  no ip directed-broadcast
  isdn switch-type primary-5ess
  isdn incoming-voice modem
  fair-queue 64 256 0
  no cdp enable
 !
 interface FastEthernet0
  ip address 16.0.0.2 255.xxx.255.0
  no ip directed-broadcast
  duplex full
  speed 10
  no cdp enable
 !
 ip classless
 ip route 0.0.0.0 0.0.0.0 1.14.xxx.5
 ip route 1.14.xxx.32 255.255.xxx.240 16.0.0.1
 no ip http server
 !
 radius-server host 1.14.132.2 auth-port 1645 acct-port 1646
 radius-server key cisco
 radius-server vsa send accounting
 radius-server vsa send authentication
 !
 voice-port 0:D
 !
 dial-peer voice 100 voip
  application debit_card 
  incoming called-number 34
  shutdown
  destination-pattern 53.....
  session target ras
  dtmf-relay h245-alphanumeric
  codec g711ulaw
 !
 dial-peer voice 200 pots
  incoming called-number 30001
  destination-pattern 3450070
  port 0:D
  prefix 50070
 !
 dial-peer voice 101 voip
  application debit_card 
 incoming called-number 34.....
  shutdown
  session protocol sipv2
  session target ipv4:16.0.0.1
  dtmf-relay cisco-rtp
  codec g711ulaw
 !
 dial-peer voice 102 voip
  incoming called-number 34.....
  destination-pattern 53.....
  session target ipv4:16.0.0.1
  dtmf-relay h245-alphanumeric
  codec g711ulaw
 !
 gateway
 !
 line con 0
  exec-timeout 0 0
  transport input none
 line aux 0
 line vty 0 4
  password xxx
 !
 ntp clock-period 17180933
 ntp server 1.14.42.23
 end

 GW2#