A single target destination is always present between the Processor Bridge and its client regardless of the number of active agent sessions or status of the connection to the third-party CTI solution. The Processor Control destination is used for several key functions:

Allows Processor Bridge to convey server status changes, such as server shutdown
Allows client to notify Processor Bridge in case of loss of communication with CTI
Supports validation of Agent login credentials
Retrieval of Agent information
Initiation of new Agent Sessions

The control destination for a specific processor bridge instance will always use {Processor_Name}.CONTROL as the target value. The name of the processor instance is obtained by the processor bridge from the HIS configuration. The client will need to have its own configuration mechanism to store and retrieve this value.

Control Destination Lifecycle

Unlike the communication targets used to control and monitor CTI resources, the processor control destination set up procedure isn’t strictly defined by the protocol. The client connects to the server using the configured network interface and port using TLS if enabled. Initialization is triggered by the client connecting to the server. The figure below depicts the initialization process:

The bridge begins interacting with the client by sending a request message indicating the client should send out an update on its current status. The client responds to the request with an acknowledgement and follows it with an event message that contains its current status.

Although this exchange could be handled using a query message with the server status information included in the response, a request is made instead to allow the client to asynchronously deliver its status. Since the client already sends out changes to its status using the event mechanism, allowing it to leverage the same pattern during initialization reduces the burden on client developers.

A second exchange is made between the bridge and client to finalize setup and initialization. The bridge sends a query message to the client requesting information about the capabilities of the client’s CTI solution. The information is returned to the bridge in the query response message. Once this final exchange is completed, the bridge becomes available and agents can begin to log in.

The connection is gracefully torn down with a request message. The client must acknowledge the request before disposing of any underlying CTI resources. One final CTI event is delivered from the client indicating that the processor bridge may terminate communication

Queries & Responses

This section defines the possible query messages the processor bridge may send to the control destination and the format of any expected result messages. Note that control destination queries and responses contain a "target" header with a value of "{Processor_Name}.CONTROL".

cti.query.capabilities

Retrieves a set of key value pairs that describe the underlying CTI’s capabilities.

Query Headers

Key	Value	Notes
type	cti.query	Query messages will always have this value
name	cti.query.capabilities	Name of this query type
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for this query

Query Body Properties

Key	Value	Notes
None

Response Headers

Key	Value	Notes
type	cti.response	Response messages will always have this value
name	cti.query.capabilities	Name of the original query
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for the orginal query
result	SUCCESS \| FAILURE	Result of the query
errorMessage	String	A human readable description of the error that caused this query to fail. This message will be logged.

Response Body Properties

Key	Value	Notes
channel-groups-supported	boolean	true if the CTI supports channel groups, false otherwise. A channel group is similar to a Place in Genesys that can have multiple channels configured in one location.
channel-groups-max-per-agent	Positive Integer (0-n)	The maximum number of channel groups an agent can log into simultaneously.
channel-groups-media-types	String	A comma separated list of multimedia types supported by channel groups by default.
single-channels-supported	boolean	true if the CTI supports an agent logging into individual channels, false otherwise.
single-channels-media-types	String	A comma separated list of multimedia types that can be registered through a single channel.

cti.query.agentinfo

Retrieves some basic information about a specific agent. To ensure security measures can be enforced, the requesting agent’s credentials are provided as part of the query.

Query Headers

Key	Value	Notes
type	cti.query	Query messages will always have this value
name	cti.query.agentinfo	Name of this query type
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for this query

Query Body Properties

Key	Value	Notes
agentId	String	The unique id of the agent whose info is being queried
requestingAgentLogin	String	The login name for the agent requesting the info. This may be the same as the agent id
requestingAgentPassword	String	The provided password for the agent requesting the info

Response Headers

Key	Value	Notes
type	cti.response	Response messages will always have this value
name	cti.query.agentinfo	Name of the original query
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for the orginal query
result	SUCCESS \| FAILURE	Result of the query
errorMessage	String	A human readable description of the error that caused this query to fail. This message will be logged and may be displayed to an agent.

Response Body Format

1{
"switch-agent-id" : "The login id agent uses to authenticate with the switch",
"first-name" : "The agent's first name",
"last-name" : "The agent's last name",
"full-name" : "The agent's full name",
"cti-specific" :
{
  Object structure containing any platform specific information about the
  agent
}
11}

The agent's name can either be provided as a single property "full-name" or divided into two pieces using "first-name" and "last-name" together. If "full-name" is provided, any values in "first-name" or "last-name" will be ignored. The contents and format of the cti-specific section is not defined here. This information will be provided as-is to the client for use in configuration or actionable during screen-pop.

Requests

This section defines the possible requests the processor bridge may make over to the control destination. The client will always generate a response message as a result of these requests. Some requests require the client to perform actions in a particular order. These constraints will be detailed in the description of the request.

cti.request.validateagentcredentials

Confirms the credentials provided for an agent are valid. Not all CTI platforms support validation of agent credentials without causing side effects such as logging the agent into a station. If the credentials cannot be validated in a side-effect free manner, a FAILURE should be returned indicating the operation is not supported.

Request Headers

Key	Value	Notes
type	cti.request	Request messages will always have this value
name	cti.request.validateagentcredentials	Name of this request type
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for this request

Request Body Properties

Key	Value	Notes
agentId	String	The unique id of the agent being validated
agentLogin	String	The login name for the agent. This may be the same as the agent id
agentPassword	String	The provided password for the agent

Response Headers

Key	Value	Notes
type	cti.response	Response messages will always have this value
name	cti.request.validateagentcredentials	Name of the original request
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for the orginal request
result	SUCCESS \| FAILURE	Result of the request
errorMessage	String	A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent.

Response Properties

Key	Value	Notes
None

cti.request.serverstatus

Requests that the client send its status to the bridge as soon as possible. This request is part of the control initialization phase. Although this request can be sent at any time, it will be rarely seen outside the initialization phase, as the client should be sending status updates any time a change occurs.

Request Headers

Key	Value	Notes
type	cti.request	Request messages will always have this value
name	cti.request.serverstatus	Name of this request type
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for this request

Request Body Properties

Key	Value	Notes
None

Response Headers

Key	Value	Notes
type	cti.response	Response messages will always have this value
name	cti.request.serverstatus	Name of the original request
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for the orginal request
cti.result	SUCCESS \| FAILURE	Result of the request
error.message	String	A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent.

cti.request.createsession

Instructs the client to prepare a new agent session using the destination described in the request message. The request can occur any time between the initialization and tear down phase of the control destination.

Request Headers

Key	Value	Notes
type	cti.request	Request messages will always have this value
name	cti.request.createsession	Name of this request type
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for this request

Request Body Properties

Key	Value	Notes
agentId	String	Id of the agent
agentPassword	String	Password of the agent
sessionId	String	Id of the new session
destination	String	Name of the target destination that will be used for this session

Response Headers

Key	Value	Notes
type	cti.response	Response messages will always have this value
name	cti.request. createsession	Name of the original request
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for the orginal request
result	SUCCESS \| FAILURE	Result of the request
errorMessage	String	A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent.

cti.request.dispose

Notifies the client that the processor bridge will be ending service and that any underlying CTI resources should be released. The actual disposal of resources should be performed after a response is returned.

Request Headers

Key	Value	Notes
type	cti.request	Request messages will always have this value
name	cti.request.dispose	Name of this request type
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for this request

Request Body Properties

Key	Value	Notes
None

Response Headers

Key	Value	Notes
type	cti.response	Response messages will always have this value
name	cti.request.dispose	Name of the original request
target	{Processor_Name}.CONTROL	Control destination name
requestId	{GUID}	Unique identifier for the orginal request
result	SUCCESS \| FAILURE	Result of the request
errorMessage	String	A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent.

Client Events

This section describes the possible events the client can send to the processor bridge control destination. In most cases, these events are unsolicited though may be the indirect result of executing a previously received request message.

cti.serverstatuschanged

This event is raised any time the client’s ability to service requests has changed or as a result of a server status request message from the processor bridge. This event may be raised at any point after the initial request during initialization and before the tear down phase.

Event Headers

Key	Value	Notes
type	cti.event	Event messages will always have this value
name	cti.serverstatuschanged	Name of this event type

Event Properties

Key

Value

Notes

status

starting-service |

in-service |

pausing-service |

stopping-service |

out-of-service

Starting service - the client is operational but still completing initialization. No new sessions will be created.

In service – the client is fully operational and accepting new sessions

Pausing service – the client is fully operational but will not accept any additional sessions. Existing sessions will continue to be serviced

Stopping service – the client is shutting down service. No new sessions will be accepted. Existing sessions will be serviced for some period of time.

Out of service – the client can no longer service sessions. No new sessions will be accepted and any existing sessions are immediately terminated.