CTI Session Settings

These settings are passed by the OPEN_REQ message that opens the CTI session. The installed configuration sets all of them for UCCX.

CiscoUCCEConnectorService.CtiProtocolVersion

Specifies the CTI protocol version preferred for communication with the selected Cisco contact center product. The current Connector implementation reads floating fields having the original one-byte header.

  • UCCX changed to a two-byte floating-field header at protocol version 18, so on UCCX the version must be 17 or lower. The Connector defaults to protocol version 16, which was verified against UCCX 15.0 and is compatible with UCCX 12.0 and later. UCCX releases before 12.0 support at most protocol version 14, so use 14 there.

  • UCCE, on the other hand, keeps the one-byte header through protocol version 19, and the Connector defaults to 19 for UCCE.

CiscoUCCEConnectorService.FloatingHeaderTwoByte

true or false. Leave it false; the two-byte floating-field header is not fully implemented.

CiscoUCCEConnectorService.CtiClientID and CtiClientPassword

The client credentials. UCCX needs none, so both are empty. UCCE deployments use the client ID and password configured for CTI authentication on the CTI Server, if it requires them. A key that is absent, or present with an empty value, is sent as empty.

CiscoUCCEConnectorService.CtiHeartbeatIntervalSeconds

How often, in seconds, the Connector checks the open session with a heartbeat: 5 to 29, or 0 for no heartbeats. Absent: 15. A value outside the range is replaced by the nearest one, with a warning. See Checking the session: heartbeats.

<add key="CiscoUCCEConnectorService.CtiProtocolVersion" value="16" />
<add key="CiscoUCCEConnectorService.CtiClientID" value="" />
<add key="CiscoUCCEConnectorService.CtiClientPassword" value="" />
<add key="CiscoUCCEConnectorService.CtiHeartbeatIntervalSeconds" value="15" />

When the session does not open

A CTI server that will not accept the session, typically because of the wrong product, protocol version or credentials, refuses it, drops the connection, or does not answer. The Connector resets the connection after a refusal, or after 15 seconds without an answer, and tries again: at the other address when two are configured.

After three failed attempts, the Connector waits before each further attempt: 10 seconds at first, doubling up to 5 minutes. It logs one warning for each wait. The wait resets once a session opens, so reconnecting after a CTI server restart is still immediate.

Checking the session: heartbeats

A connection can fail without either end noticing: a network path that goes down, or a CTI server host that stops responding, can leave the connection open while nothing arrives. To detect this, once the session is open the Connector sends the CTI server a heartbeat (HEARTBEAT_REQ) every CtiHeartbeatIntervalSeconds, as both Cisco guides ask, and the CTI server answers each one.

  • When three heartbeats in a row go unanswered, or the CTI server answers one with a failure, the Connector ends the session and resets the connection. It then reconnects, or moves to the other CTI server when two are configured, as for any lost connection. With the default of 15 seconds, a failed connection is detected within about 45 seconds.

  • The session request (OPEN_REQ) asks the CTI server to end the session after four heartbeat intervals without hearing from the Connector (its IdleTimeout: 60 seconds by default). UCCX requires this to be under 120 seconds, hence the maximum interval of 29 seconds.

  • With CtiHeartbeatIntervalSeconds set to 0, the Connector sends no heartbeats and asks for no idle timeout, as releases before 12.3 did. A failed connection is then noticed only when TCP notices it, which can take many minutes.

Heartbeats are logged at the Debug level only. A heartbeat that goes unanswered is logged as a warning.