cisco onprem uc · published

Troubleshooting CTI applications that cannot control phones in Unified CM

Verified 2026-10-02 · 57 sources · tier 2

Also known as cucm-ctimanager-troubleshooting.

CTI, JTAPI and TAPI applications connect to the Cisco CTIManager service 3132, which is activated per node in Cisco Unified Serviceability 7. To control a phone, the application or end user must be in the Standard CTI Enabled group 37, and the device must be in the user's Controlled Devices list or covered by the Standard CTI Allow Control of All Devices role 236.

How CTI control works

An application that is not set up for security connects to CTIManager on the nonsecure port 2748 31. A secured application and CTIManager mutually authenticate with TLS and exchange messages over port 2749 32.

A device is placed under an application user's control by moving it from the Available Devices list to the Controlled Devices list on the Application User Configuration page 2. The Standard CTI Allow Control of All Devices role lets an application control or monitor any CTI-controllable device in the cluster, not just devices in its controlled list 36. A CTI route point is a virtual device that can receive multiple simultaneous calls for application-controlled redirection 41.

The access control groups that the claims in this article describe are: 37363839640

Group	What the claims say about it
Standard CTI Enabled	Required for every CTI application user or end user to connect to Unified CM over CTI 37
Standard CTI Allow Control of All Devices	Allows control or monitoring of any CTI-controllable device in the cluster 36
Standard CTI Secure Connection	Requires the user's CTI connection to be TLS, which depends on cluster security being enabled 38
Standard CTI Allow Reception of SRTP Key Material	Gives the application the keying data needed to decrypt encrypted media for recording or monitoring 39
Standard CTI Allow Control of Phones supporting Connected Xfer and conf	Required for Jabber desk phone control of 9900, 8900, 8800 or DX series phones 6
Standard CTI Allow Control of Phones supporting Rollover Mode	Required for Jabber desk phone control of 6900 series phones 40

Diagnosing a device the application cannot control

Start by confirming the device model is CTI-controllable, because the JTAPI guide's CTI Supported Devices appendix marks analog phones and several legacy models as not supported 29. If Allow Control of Device from CTI is not selected on the desk phone's device configuration, Jabber users cannot control that desk phone 1. Confirm the device is in the application user's Controlled Devices list, unless the application relies on Standard CTI Allow Control of All Devices 236.

We infer that when a CTI application controls most devices but not one, the per-device settings (controlled devices list, Allow Control of Device from CTI on phone or line, CTI-supported model) are likelier causes than a CTIManager outage, which would affect every device on that provider 9.

If restrictions prevent a CTI application from monitoring or controlling a device or directory number, CTIManager does not send it the keying material for that device or line 26.

Diagnosing a provider that will not open

Check that Cisco CTIManager is activated on the intended nodes under Tools > Service Activation in Cisco Unified Serviceability, where it is checked in the CM Services list 7. Check that the application user or end user is in Standard CTI Enabled 37.

A Directory Login Timeout on provider open means CTI gave no authentication response to the ProviderOpenRequest, for example from LDAP connectivity problems, database delay or CTIManager unavailability, and the application should retry 8.

The CTIManager service parameter Maximum Devices Per Provider defaults to 2000 devices 23. The CTIManager service parameter Maximum Devices Per Node defaults to 800 devices 22.

To use IPv6 addresses with CTI, the application must use a JTAPI or TAPI client interface version that supports IPv6 11.

JTAPI client versions

The Cisco JTAPI client is downloaded from Cisco Unified CM Administration under Application > Plugins 18. The installed client version can be checked by running java CiscoJtapiVersion 19.

Cisco states that JTAPI generally preserves backward compatibility, so older JTAPI clients are compatible with newer Unified CM versions 30. Cisco's JTAPI installation guide states that upgraded JTAPI client software does not work with previous releases of Unified CM 57. In the Cisco compatibility matrix, the JTAPI 12.5(x) client is listed as compatible with Unified CM 12.5(x), 14(x) and 15(x), and JTAPI 14(x) with Unified CM 14(x) and 15(x) 15. The JTAPI 15(x) client is listed as compatible only with Unified CM 15(x), not with 14(x) or 12.5(x) 16.

WarmTransfer's reading of the sources is that, because newer JTAPI clients are not listed as working with older Unified CM releases, upgrading an application's JTAPI client before the Unified CM cluster it connects to risks provider-open failures 10.

JTAPI tracing

Cisco JTAPI tracing is configured with the JTAPI Preferences utility (JTPREFS), and traces can be written to a chosen folder so simultaneous JTAPI instances keep separate trace destinations 21. JTAPI trace levels are WARNING, INFORMATIONAL and DEBUG, and DEBUG exposes sub-levels including CTI_DEBUGGING, CTIIMPL_DEBUGGING and PROTOCOL_DEBUGGING 20.

Secure CTI connections

A TLS connection between a CTI application and CTIManager requires the cluster security mode to be mixed mode 44. If the cluster is not in mixed mode, the application cannot access the CTL file and connects to CTIManager over nonsecure port 2748 instead of TLS 28. The application user or end user must be in the Standard CTI Secure Connection group 45.

A secure CTI connection needs an Application User CAPF Profile or End User CAPF Profile with certificate operation Install/Upgrade, and the certificate must be installed through the JTAPI or TSP client using the authentication string 43. The Cisco Certificate Authority Proxy Function service must be activated on the publisher node before CTI clients can obtain locally significant certificates 5. The CAPF authentication string is 4 to 10 digits and can be used only once 3.

Each instance of a secured CTI application on a PC or server needs its own certificate, and one certificate does not cover all instances 56. If a secured CTI application is uninstalled from one PC and installed on another, a new certificate must be installed for each instance on the new PC 24.

When certificate installation hits a communication failure, the JTAPI client retries 3 times at 30-second intervals and these values are not configurable, while the TSP retry count and timer are configurable 17. Cisco recommends issuing CAPF certificates during a scheduled maintenance window because generating many certificates at once can interrupt call processing 4.

SRTP key material for recording and monitoring

To receive SRTP session keys, the application or end user must belong to Standard CTI Enabled, Standard CTI Secure Connection and Standard CTI Allow Reception of SRTP Key Material 42. CTIManager does not send SRTP keying material to an application connected on nonsecure port 2748 25.

Failover and redundancy

When a Unified CM call-processing node fails, CTIManager recovers the affected CTI ports and route points by reopening them on another Unified CM node 35. When a CTIManager fails, connected applications recover their devices by reopening them on another CTIManager, chosen from the primary and backup CTIManagers configured in the application 34.

Applications do not automatically rehome to the primary CTIManager when it returns to service; they fail back only when the application restarts or the backup CTIManager fails 27. When a TAPI, JTAPI or direct CTI application fails, CTIManager closes it and redirects unterminated calls at its CTI ports and route points to the configured Call Forward on Failure number 33.

Jabber desk phone control

Jabber desk phone control requires the Cisco CTIManager service to be running in the Unified CM cluster 12. The end user must at minimum be in Standard CCM End Users and Standard CTI Enabled 13. For Cisco IP Phone 9900, 8900, 8800 or DX series desk phones, Jabber desk phone control also requires the Standard CTI Allow Control of Phones supporting Connected Xfer and conf group 6. For Cisco IP Phone 6900 series desk phones, it requires the Standard CTI Allow Control of Phones supporting Rollover Mode group 40.

Cisco's Jabber deskphone guide says not to assign users provisioned with secure phone capabilities to the Standard CTI Secure Connection group 14.

Unified CCX agents, ports and triggers

The UCCX RMCM application user in Unified CM needs Standard CTI Enabled, Standard CTI Allow Control of Phones supporting Connected Xfer and conf, and Standard CTI Allow Control of All Devices 53. For UCCX agents, Allow Control of Device from CTI must be enabled on the Phone Configuration page, the End User Configuration page and the Directory Number Configuration page of the IPCC extension 46.

The UCCX JTAPI component does not support shared lines, so an IPCC extension shared across devices or in a line group can cause intermittent agent login failures 52. The IPCC extension must be on one of the first 4 lines of the phone or user device profile because JTAPI monitors only the first 4 configured lines 50. With Extension Mobility, the IPCC extension is associated with the user device profile rather than with the physical phone 49.

For UCCX agent phones or user device profiles, the Common Device Configuration should be set to IPv4 only 47. The IPCC extension's Maximum Number of Calls and Busy Trigger should be 2 and 1 respectively 51.

A UCCX CTI port shows out of service when it was dissociated from the application user or deleted in Unified CM, and Cisco's fix is to restart the CCX Engine and recreate the affected call control group 48. A UCCX trigger goes out of service when its CTI route point was deleted in Unified CM or its directory number no longer exists, and the fix includes removing orphaned DNs via Route Plan Report, recreating the route point and running a UCCX data resync 54. For a trigger showing Call Control Group is Unknown, Cisco says to reselect the call control group and, if the problem persists, restart the CTI Manager service on Unified CM and the CCX Engine 55.

Applicability

Applies to: Cisco Unified Communications Manager, Cisco Jabber, Cisco Unified CM JTAPI, and Cisco Unified Contact Center Express. Deployments: on-premises. Sources checked 2026-10-02. The JTAPI compatibility statements cover JTAPI 12.5(x), 14(x) and 15(x) clients against Unified CM 12.5(x), 14(x) and 15(x) 1516. The UCCX release that the UCCX troubleshooting steps apply to is not covered by the sources below.

What remains uncertain

Per-model CTI support for current phones, including the Webex App softphone, is not covered by the sources below.
Webex App desk phone control requirements on Unified CM, as the Jabber successor, are not covered by the sources below.
Cluster-wide CTI device and connection capacity by OVA size is not covered by the sources below.
The complete list of Standard CTI access control groups in release 15, including how the Rollover Mode and Connected Xfer groups fit into it, is not covered by the sources below.
CTI application support and restrictions on Webex Calling Dedicated Instance are not covered by the sources below.
The meaning and defaults of the RTMT CtiDeviceOpenFailure and CtiProviderOpenFailure alerts in release 15 are not covered by the sources below.
Whether Standard CTI Allow Control of All Devices overrides an unchecked Allow Control of Device from CTI setting is not covered by the sources below.
The full set of CTIManager reason codes for provider and device open failures is not covered by the sources below.