CTI CSTA Protocol Suite

This chapter describes how to configure the Computer Telephony Integration (CTI) Computer Supported Telecommunications Applications (CSTA) protocol suite in Cisco Unified Communications Manager Express (Cisco Unified CME) 8.0 and later versions to allow computer-based CSTA client applications, such as a Microsoft Office Communicator (MOC) client or an application developed using the Cisco Unified Communications Express (UC Express) Services Interface SDK, to monitor and control the Cisco Unified CME system and enable programmatic control of SCCP telephony devices registered in Cisco Unified CME.


Note

To configure support for interoperability between Cisco Unified CME and Cisco Customer Response Solutions (CRS) with Cisco Unified Contact Center Express (Cisco Unified CCX), see Configure Interoperability with Cisco Unified CCX.

Information About CTI CSTA Protocol Suite

CTI CSTA in Cisco Unified CME

The CTI CSTA Protocol Suite in Cisco Unified CME 8.0 and later versions provides third-party call-control capabilities for computer-based CSTA client applications, such as a Microsoft Office Communicator (MOC) client through Microsoft Office Communications Server (OCS) and applications created using the Cisco Unified CME CTI SDK, and enables click-to-dial from the application.

The CTI CSTA Protocol Suite in Cisco Unified CME 8.8 and later versions enables the dial-via-office functionality from the application.

CSTA Client Application Deployment

Typically, a computer-based application uses CSTA to control its associated PBX phone via a SIP CSTA gateway. The gateway terminates SIP messages and converts ECMA-323 messages to and from the PBX-specific protocol.

In Cisco Unified CME 8.0 and later versions, a computer-based CSTA client application interacts directly with Cisco Unified CME via the CTI interface in Cisco Unified CME to control and monitor IP phones registered in Cisco Unified CME. Cisco Unified CME replaces the CSTA gateway and the PBX in the typical application-to-PBX deployment to terminate SIP messages from the client application and convert CSTA XML into the line-side protocol that controls the phone.

CTI Session

If required, a CSTA client application creates a session by establishing a SIP dialog with the CTI interface in Cisco Unified CME 8.0 and later versions. The logical name of the phone user is described in the SIP “From” header while the PBX phone line is described in the SIP “To” header. The user and line configurations are created in the application.

The SIP INVITE body includes a System Status service request. A SIP “OK” response that includes a System Status response is sent from Cisco Unified CME. The application continues only if it receives the expected response.

After receiving the expected response, the client application begins the capabilities exchange by sending a SIP message requesting a list of supported CSTA services and events from Cisco Unified CME. Cisco Unified CME sends a response with an encapsulated CSTA features response that is a list of supported services and events. For information, see Supported Services and Events.

The CSTA client application must start a CSTA monitor before it can observe changes to calls and features by CSTA events. To start the Call Monitor Module (CMM) in Cisco Unified CME, the application sends a SIP INFO message with an encapsulated service request. The CTI interface authorizes this request and sends back a SIP 200 OK response with an encapsulated ECMA-323 Monitor Start response. After this, Cisco Unified CME starts generating subsequent events in SIP INFO messages to the application.

During a CTI session, the CSTA client application sets a timer (default: 30 minutes) in the INVITE message and refreshes it via RE-INVITE message. Cisco Unified CME deletes a SIP dialog after the session expires.

Supported Services and Events

Table 1 lists CSTA services and events that are supported by the CTI CSTA protocol Suite in Cisco Unified CME 8.0 and later versions. Not all CSTA client applications can support all features. For more information, see the user documentation for your CSTA client application.

Table 1. Supported CSTA Services and Events

Function

Supported Services and Events

Call Control

  • Make Call

  • Answer Call

  • Clear Connection

  • Reconnect

  • Hold Call

  • Retrieve Call (Resume)

  • Deflect Call (only at alerting state)

  • Single Step Transfer Call

  • Consultation Call

  • Transfer Call

  • Alternate Call Generate Digits (DTMF)

Logical Phone Features

  • Get Do Not Disturb

  • Set Do Not Disturb

  • Get CFwdALL

  • Set CFwdAll

Physical Device

Set MWI

Snapshot Services

Snapshot Device

For a complete list of the services and events supported by the CTI CSTA Protocol Suite, see UCX-SI SDK Developer’s Guide at: http://developer.cisco.com/web/ucxapi/docs.

Configure CTI CSTA Protocol Suite

Table 1 contains a list of tasks required to enable a computer-based CSTA client application to control IP phones in Cisco Unified CME, presented in the order in which the tasks are to be completed. This document contains information about performing tasks in the first 2 steps in this table and procedures for completing step 3.

Table 2. Tasks to Configure Interoperability Between a CSTA Client Application and Cisco Unified CME

Step

Task

Name of Document

1

Verify that the appropriate version of Cisco Unified Communications Manager Express (Cisco Unified CME) is installed on the router.

-

2

Configure Cisco Unified CME including AXL user name and password for the computer-based CSTA client application, if required.

Tip 

Take note of the AXL user ID and password of the application and the IP address of the Cisco Unified CME router.

Note 

An AXL credential is not required for a MOC client.

See 'Prerequisites' in Enable CTI CSTA in Cisco Unified CME.

3

Configure Cisco Unified CME to enable interoperability with CSTA client application.

See the configuration procedures.

4

Install CSTA client application.

See documentation for your application.

5

Configure CSTA client application for Cisco Unified CME, including SIP URI of CTI gateway front-end or client application.

Enable CTI CSTA in Cisco Unified CME

To configure Cisco Unified CME to enable interoperability between Cisco Unified CME and a computer-based CSTA client application, perform the following steps.


Note

During the initial setup of the CSTA client application, you need the router IP address configured using the ip source-address command in telephony-service configuration mode. For some client applications, you may also need the AXL username and password configured using the xml user command in telephony-service configuration mode.

Before you begin

  • Cisco Unified CME 8.0 or a later version must be installed and configured on the Cisco router.

  • (Not required for a MOC client) XML API must be configured to create an AXL username for some CSTA client application access. To determine if an AXL username is required for your application, see your application documentation. For configuration information, see Configure the XML API.

SUMMARY STEPS

  1. enable
  2. configure terminal
  3. voice service voip
  4. allow-connections sip-to-sip
  5. no supplementary-service sip moved-temporary
  6. no supplementary-service sip refer
  7. no cti shutdown
  8. callmonitor
  9. gcid
  10. cti csta mode basic
  11. cti message device-id suppress-conversion
  12. sip
  13. registrar server [ expires [ max sec][ min sec]]
  14. end

DETAILED STEPS

  Command or Action Purpose
Step 1

enable

Example:

Router# enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 3

voice service voip

Example:

Router(config)# voice service voip

Enters voice-service configuration mode and specifies voice-over-IP encapsulation.

Step 4

allow-connections sip-to-sip

Example:

Router(config-voi-serv)# allow-connections sip-to-sip

Allows connections between specific types of endpoints in a VoIP network.

Step 5

no supplementary-service sip moved-temporary

Example:

Router(config-voi-serv)# no supplementary-service sip moved-temporary

Disables supplementary service for call forwarding.

Step 6

no supplementary-service sip refer

Example:

Router(config-voi-serv)# no supplementary-service sip refer

Prevents the router from forwarding a REFER message to the destination for call transfers.

Step 7

no cti shutdown

Example:

Router(config-voi-serv)# no cti shutdown

Enables CTI integration.

Step 8

callmonitor

Example:

Router(config-voi-serv)# callmonitor

(Optional) Enables call monitoring messaging functionality for processing and reporting.

  • This command is not required for a MOC client.

Step 9

gcid

Example:

Router(config-voi-serv)# gcid

(Optional) Enables Global Call-ID (Gcid) for call control purposes.

  • This command is not required for a MOC client.

Step 10

cti csta mode basic

Example:

Router(config-voi-serv)# cti csta mode basic

(Optional) Suppresses enhanced feature/extension in CTI messages.

  • Required for a MOC client.

Step 11

cti message device-id suppress-conversion

Example:

Router(config-voi-serv)# cti message device-id suppress-conversion

(Optional) Suppresses conversion or promotion of extension numbers of associated endpoints in CTI messages.

  • This command is not required for a MOC client.

Step 12

sip

Example:

Router(config-voi-serv)# sip

Enters SIP configuration mode.

  • Required only if you perform the following step for enabling the SIP registrar function in Cisco Unified CME.

Step 13

registrar server [ expires [ max sec][ min sec]]

Example:

Router(config-voi-sip)# registrar server expires max 600 min 60

(Optional) Enables SIP registrar functionality in Cisco Unified CME.

  • max sec —(Optional) Maximum time for a registration to expire, in seconds. Range: 600 to 86400. Default: 3600. Recommended value: 600.

Note 

Ensure that the registration expiration timeout is set to a value smaller than the TCP connection aging timeout to avoid disconnection from the TCP.

  • This command is not required for a MOC client.

Step 14

end

Example:

Router(config-voi-sip)# end

Exits voice-service configuration mode and enters privileged EXEC mode.

Examples

The following example shows the required configuration for supporting interaction with a MOC client: 


voice service voip 
 allow-connections sip to sip
 no supplementary-service sip moved-temporarily
 no supplementary-service sip refer
 no cti shutdown
 cti csta mode basic
!
!
!

What to do next

Create a Session Manager

To configure a session manager in Cisco Unified CME for a CSTA client application, perform the following steps.


Note

  • This task is not required for a MOC client.

  • A single Cisco Unified CME can support multiple session managers.

SUMMARY STEPS

  1. enable
  2. configure terminal
  3. voice register global
  4. mode cme
  5. exit
  6. voice register session-server session-server-tag
  7. cti-aware
  8. register-id name
  9. keepalive seconds
  10. end

DETAILED STEPS

  Command or Action Purpose
Step 1

enable

Example:

Router> enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 3

voice register global

Example:

Router(config)# voice register global

Enters voice register global configuration mode.

Step 4

mode cme

Example:

Router(voice-register-global)# mode cme

Enables mode for provisioning SIP devices in Cisco Unified CME.

Step 5

exit

Example:

Router(voice-register-global)# configure terminal

Exits to global configuration mode.

Step 6

voice register session-server session-server-tag

Example:

Router(config)# voice register session-server 1

Enters voice register session-server configuration mode to enable and configure a session manager.

  • Range: 1 to 8.

  • A single Cisco Unified CME can support multiple session managers.

Step 7

cti-aware

Example:

Router(config-register-fs)# cti-aware

Binds this session manager to the CTI subsystem and enables CTI-specific Register heartbeat.

Step 8

register-id name

Example:

Router(config-register-fs)# register app1

Creates an ID for explicitly identifying the CSTA client application during Register requests.

  • name —String for identifying application. Can contain 1 to 30 alphanumeric characters.

Step 9

keepalive seconds

Example:

Router(config-register-fs)# keepalive 60

Keepalive duration for registration, in seconds, after which the registration expires unless the application reregisters before the registration expiry.

  • Range: 60 to 3600. Default: 300.

Step 10

end

Example:

Router(config-register-fs)# end

Exits voice register session-server configuration mode and enters privileged EXEC mode.

Examples


!
voice register global
 mode cme
 source-address 10.0.0.1 port 5060
!
!
voice register session-server  1
 keepalive 60
 register-id app1
 cti-aware
!
 

Configure a Number or Device for CTI CSTA Operations

To configure a directory number or an IP phone for CTI CSTA operations, perform the following steps for each number or phone to be monitored and controlled by the CSTA client application.


Restriction

  • Only SCCP IP phones can be controlled by a CSTA client application. The Cisco VG224 Analog Phone Gateway and analog and SIP phones are supported as usual in Cisco Unified CME but not as IP phones for a CSTA client application.

  • Overlay DNs are not supported on IP phones for a CSTA client application. The Call Monitor Module in Cisco Unified CME is unable to determine if two inbound calls to the same directory number are on the same phone or on different phones, as in an overlay configuration. Overlays DNs are supported as usual in Cisco Unified CME but not on IP phones to be controlled or monitored by a CSTA client application.

  • Not all SCCP IP phones support the Prompted Make Call feature in the CTI CSTA protocol suite. The Cisco VG224 Analog Phone Gateway, Cisco ATAs, and SCCP-controlled FXS ports on Cisco routers do not support a prompted make-call request from a CSTA client application. Certain Cisco Unified phone models, including the Cisco Unified 792X and Cisco Unified 793X, may be unable to complete a prompted make-call request from a CSTA client application.

  • Prompted Make Call is not supported on IP phones associated with a MOC Client. Prompted Make Call is supported as usual in Cisco Unified CME but not on IP phones to be controlled by a MOC client.

  • Shared lines are not supported on an IP phone associated with a MOC client. Shared lines are supported as usual in Cisco Unified CME but not on IP phones to be controlled by a MOC client.

  • If the phone to be controlled and monitored by a MOC client is an Extension Mobility (EM) phone, the MOC client must log into the phone using the credential in an EM user profile when no users are logged into the EM phone or after an EM user logs in.

Before you begin

  • Directory number or IP phone to be controlled and monitored by the application is configured in Cisco Unified CME. For configuration information, see Configure Phones to Make Basic Call.

  • Extension Mobility (EM) phone to be controlled and monitored by the application must be configured in Cisco Unified CME, including the required user profiles. For information, see Extension Mobility.

SUMMARY STEPS

  1. enable
  2. emadmin login name ephone-tag
  3. emadmin logout name
  4. configure terminal
  5. ephone-dn tag
  6. cti watch
  7. cti notify
  8. exit
  9. telephony-service
  10. em external
  11. url services url root
  12. end

DETAILED STEPS

  Command or Action Purpose
Step 1

enable

Example:

Router# enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

emadmin login name ephone-tag

Example:

Router# emadmin login user204 2

(Optional) Enables application to log in to an IP phone that is enabled for Extension Mobility.

  • name —Credential in EM user profile configured with the user (voice user-profile) command.

  • ephone-tag —identifier for IP phone that is enabled for Extension Mobility.

Required for a MOC client if the MOC client will control the number or device to be configured.

Step 3

emadmin logout name

Example:

Router# emadmin logout user204

(Optional) Logs the application out of the Extension Mobility phone.

  • name —Credential in Extension Mobility that the application used to log into an Extension Mobility phone.

Step 4

configure terminal

Example:

Router# configure terminal

Enters global configuration mode.

Step 5

ephone-dn tag

Example:

Router(config)# ephone-dn 1

Enters ephone-dn configuration mode.

Step 6

cti watch

Example:

Router(config-ephone-dn)# cti watch

Allows this directory number to be monitored and controlled by a CSTA client application.

  • This command can also be configured in ephone-dn-template configuration mode. The value set in ephone-dn configuration mode has priority over the value set in ephone-dn-template mode.

Step 7

cti notify

Example:

Router(config-ephone-dn)# cti notify

(Optional) Forces ephone-dn into constant “up” state to allow CTI operations on this directory number.

  • Required if ephone-dn to be monitored/controlled is not associated with a physical device.

  • This command can also be configured in ephone-dn-template configuration mode. The value set in ephone-dn configuration mode has priority over the value set in ephone-dn-template mode.

Step 8

exit

Example:

Router(config-ephone-dn)# exit

Exits ephone-dn configuration mode.

Step 9

telephony-service

Example:

Router(config)# telephony-service

Enters telephony-service configuration mode.

  • Required only if you perform Step 10 to Step 11 for configuring the Services menu on an IP phone.

Step 10

em external

Example:

Router(config-telephony)# em external

(Optional) Removes login page for Extension Mobility from the Services menu on IP phones.

Step 11

url services url root

Example:

Router(config-telephony)# url services http://my_application/menu.html root

(Optional) Provides menu of root phone services under the Services button on IP phones.

  • url —URL for external menu of root phone services provided by an application.

Step 12

end

Example:

Router(config-telephony)# end

Exits telephony-service configuration mode and enters privileged EXEC mode.

Examples


!
voice logout-profile 1
 number 203 type normal
!
voice user-profile 1
 user user204 password psswrd
 number 204 type normal
!
.
.
.
ephone-dn  1
 number 201
 cti watch
!
!
ephone-dn  2
 number 202
 cti watch
!
!
ephone-dn  3
 number 203
 cti watch
!
!
ephone-dn  4
 number 204
 cti notify
 cti watch
!
!
ephone  1
 mac-address 001E.4A34.A35F
 type 7961
 button  1:1
!
!
!
ephone  2
 mac-address 000F.8FC7.B681
 type 7960
 button  1:2
!
!
!
ephone  3
 mac-address 0019.E7FF.1E30
 type 7961
 logout-profile 1

Clear a Session Between a CSTA Client Application and Cisco Unified CME

To gracefully tear down a CTI session between a CSTA client application and Cisco Unified CME, perform the following steps.

Before you begin

  • Cisco Unified CME 8.0 or a later version.

  • Determine the session ID using the show cti session command.

SUMMARY STEPS

  1. enable
  2. clear cti session id session-tag

DETAILED STEPS

  Command or Action Purpose
Step 1

enable

Example:

Router# enable

Enables privileged EXEC mode.

  • Enter your password if prompted.

Step 2

clear cti session id session-tag

Example:

Router# clear cti session id 3

Clears the session between a CSTA client application and Cisco Unified CME.

Configuration Examples for CTI CSTA Protocol Suite

Example for Configuring MOC Client


!
version 12.4
service timestamps debug datetime msec
service timestamps log datetime msec
no service password-encryption
!
hostname sdatar-2811s
!
boot-start-marker
boot system flash c2800nm-ipvoice-mz.oct_20090510
boot-end-marker
!
logging message-counter syslog
!
no aaa new-model
!
ip source-route
!
!
ip cef
!
ip dhcp pool test
   network 10.0.0.0 255.255.255.0
   option 150 ip 10.0.0.1 
   default-router 10.0.0.1 
!
!
no ipv6 cef
multilink bundle-name authenticated
!
!
voice service voip 
 allow-connections sip to sip
 no supplementary-service sip moved-temporarily
 no supplementary-service sip refer
 no cti shutdown
 cti csta mode basic
!
!
!
!
voice logout-profile 1
 number 203 type normal
!
voice user-profile 1
 user user204 password psswrd
 number 204 type normal
!
voice-card 0
!
!
!
archive
 log config
  hidekeys
!
!
!
interface FastEthernet0/0
 ip address 10.0.0.1 255.255.255.0
 duplex auto
 speed auto
!
interface Service-Engine0/0
 no ip address
 shutdown
!
interface FastEthernet0/1
 ip address 1.5.41.5 255.255.0.0
 duplex auto
 speed auto
!
ip forward-protocol nd
ip route 0.0.0.0 0.0.0.0 10.1.43.254
ip route 223.255.254.254 255.255.255.255 1.5.0.1
!
!
ip http server
!
!
ixi transport http
 response size 64
 no shutdown
 request outstanding 1
 request timeout 60
!
ixi application cme
 no shutdown
!
!
!
control-plane
!
!
!
voice-port 0/0/0
!
voice-port 0/0/1
!
voice-port 0/0/2
!
voice-port 0/0/3
!
!
mgcp fax t38 ecm
!
!
!
sip-ua 
!
!
telephony-service
 em logout 1:0 
 max-ephones 10
 max-dn 100
 ip source-address 10.0.0.1 port 2000
 cnf-file location flash:
 cnf-file perphone
 max-conferences 8 gain -6
 transfer-system full-consult
 create cnf-files version-stamp Jan 01 2002 00:00:00
!
ephone-dn  1
 number 201
 cti watch
!
!
ephone-dn  2
 number 202
 cti watch
!
!
ephone-dn  3
 number 203
 cti watch
!
!
ephone-dn  4
 number 204
 cti notify
 cti watch
!
!
ephone  1
 mac-address 001E.4A34.A35F
 type 7961
 button  1:1
!
!
!
ephone  2
 mac-address 000F.8FC7.B681
 type 7960
 button  1:2
!
!
!
ephone  3
 mac-address 0019.E7FF.1E30
 type 7961
 logout-profile 1

Example for Configuring CSTA Client Application Requiring a Session Manager 


!
version 12.4
service timestamps debug datetime msec
service timestamps log datetime msec
no service password-encryption
!
hostname sdatar-2811s
!
boot-start-marker
boot system flash c2800nm-ipvoice-mz.oct_20090510
boot-end-marker
!
logging message-counter syslog
!
no aaa new-model
!
ip source-route
!
!
ip cef
!
ip dhcp pool test
   network 10.0.0.0 255.255.255.0
   option 150 ip 10.0.0.1 
   default-router 10.0.0.1 
!
!
no ipv6 cef
multilink bundle-name authenticated
!
!
voice service voip 
 no cti shutdown
 csta cti mode basic
 sip
  registrar server expires max 120 min 60
!
voice register global
 mode cme
 source-address 10.0.0.1 port 5060
!
voice register session-server  1
 keepalive 60
 register-id apps
 cti-aware
!
!
voice logout-profile 1
 number 203 type normal
!
voice user-profile 1
 user user204 password cisco
 number 204 type normal
!
!
!
voice-card 0
!
!
!
archive
 log config
  hidekeys
!
!
!
interface FastEthernet0/0
 ip address 10.0.0.1 255.255.255.0
 duplex auto
 speed auto
!
interface Service-Engine0/0
 no ip address
 shutdown
!
interface FastEthernet0/1
 ip address 1.5.41.5 255.255.0.0
 duplex auto
 speed auto
!
ip forward-protocol nd
ip route 0.0.0.0 0.0.0.0 10.1.43.254
ip route 223.255.254.254 255.255.255.255 1.5.0.1
!
!
ip http server
!
!
ixi transport http
 response size 64
 no shutdown
 request outstanding 1
 request timeout 60
!
ixi application cme
 no shutdown
!
!
!
control-plane
!
!
!
voice-port 0/0/0
!
voice-port 0/0/1
!
voice-port 0/0/2
!
voice-port 0/0/3
!
!
mgcp fax t38 ecm
!
!
!
!
sip-ua 
!
!
telephony-service
 em logout 1:0 
 max-ephones 10
 max-dn 100
 ip source-address 10.0.0.1 port 2000
 cnf-file location flash:
 cnf-file perphone
 max-conferences 8 gain -6
 transfer-system full-consult
 create cnf-files version-stamp Jan 01 2002 00:00:00
!
!
ephone-dn  1
 number 201
 cti watch
!
!
ephone-dn  2
 number 202
 cti watch
!
!
ephone-dn  3
 number 203
 cti watch
!
!
ephone-dn  4
 number 204
 cti notify
 cti watch
!
!
ephone  1
 mac-address 001E.4A34.A35F
 type 7961
 button  1:1
!
!
!
ephone  2
 mac-address 000F.8FC7.B681
 type 7960
 button  1:2
!
!
!
ephone  3
 mac-address 0019.E7FF.1E30
 type 7961
 logout-profile 1
!
!
!

Feature Information for CTI CSTA Protocol Suite

The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Table 3. Feature Information for CTI CSTA Protocol Suite

Feature Name

Cisco Unified CME Version

Feature Information

CTI CSTA Protocol Suite Enhancement

8.8

Enables the dial-via-office functionality from computer-based CSTA client applications and adds support to CSTA services and events.

CTI CSTA Protocol Suite in Cisco Unified CME

8.0

Introduces industry-standard Computer Telephony Integration (CTI) interface that enables computer-based CSTA client applications to interact directly with Cisco Unified CME to monitor/control IP phones.

The following commands are new or modified for this feature:clear csta session , cti-aware , cti csta mode , cti message device-id suppress-conversion , cti notify ,cti shutdown , cti watch , debug cti ,debug cti callmon , emadmin login , emadmin logout ,em external , show cti , url (telephony-service)