Session Destination Messages
- Trip Gilman
A session destination is created by the processor bridge each time an agent logs in to the system. The destination is used to register and manage the channels and channel groups the agent will use during their session.
Add/Remove a channel group
Log out of session
Dispose of session resources
As with the processor control destination, the session destination follows the same lifecycle of setup, initialization, and tear down. The following figure depicts the initialization phase a session destination:
It is important to note that with all CTI resource related destinations, no event messages should be raised prior to receiving and responding to the initialization query message.
Queries & Responses
This section defines the possible query messages the processor bridge may send related to the session destination and the format of any expected result messages.
session.query.init
This query retrieves information about the channels and channel groups registered to the agent. An agent may already be logged into a channel or channel group prior to session creation for several reasons:
Loss of connectivity between the CRM and HIS
Loss of connectivity between the processor bridge and the message broker
Loss of connectivity between the processor bridge and the client
Another agent desktop is in used in parallel
The response to this query carries a JSON payload describing the channels and channel groups in use by the agent after the login process is complete. This request should always return a single channel group that will contain the telephony channel and any enabled media channels regardless of whether this is a reconnect of an existing session or the start of a new one.
Query Headers
Key | Value | Notes |
|---|---|---|
type | cti.query | Query messages will always have this value |
name | session.query.init | Name of this query type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Query Body Properties
Key | Value | Notes |
|---|---|---|
name | String | The name of the channel or channel group from the name field in config server. The overall meaning of this field is platform dependent |
chat | Boolean | True if the agent should have chat enabled |
Boolean | True if the agent should have email enabled | |
callback | Boolean | True if the agent should have callback enabled. Not all platforms support callback. If not supported this field should be ignored |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | session.query.init | Name of the original query |
target | String | See generating message targets above |
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 |
|---|---|---|
channelGroup | String | Identifier used by the CTI to reference the channel group that is associated with the agent |
Special Considerations
The processor bridge will use the information provided in the response message to create a channel group communication destination. Any session related events sent to the destination remain in queue until these objects are initialized themselves. Once this is complete, the events are processed in the order they arrived.
Requests
This section defines the possible requests the processor bridge may make to the session 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.
session.request.createchannelgroup
Instructs the client to prepare a new channel group destination. The request can occur any time between the initialization and tear down phase of the session destination.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | session.request.createchannelgroup | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
name | String | The name of the channel group (CTI identifier) |
id | String | The bridge id of the channel group |
String | Extension | |
properties.chat | Boolean | Agent is configured to handle chat |
properties.email | Boolean | Agent is configured to handle email |
properties.callback | Boolean | Agent is configured to handle callback |
properties.voicemail | Boolean | Agent is configured to handle voicemail |
extensions.mobileagent-mode | String | Mobile Agent Mode |
extensions.mobileagent-dialnumber | String | Dial Number |
extensions.MaxEmails | String | Max Emails from configuration |
extension.MaxChats | String | Max Chats from configuration |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | session.request.createchannelgroup | Name of the original 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. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
session.request.close
Notifies the client that the processor bridge is ready to close the session. If the session is in an active state and should not be closed, for example on a phone call, a failure response should be generated. All ended interactions should be automatically marked complete, the agent should be placed into NOT_READY on all channels, the agent should be logged out of all active channels, and any channel group associations should be removed. Each of these actions should generate the appropriate events for their respective objects.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | session.request.close | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes | ||
|---|---|---|---|---|
type | cti.response | Response messages will always have this value | ||
name | session.request.close | Name of the original 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. | ||
target | String | See generating message targets above | ||
requestId | {GUID} | Unique identifier for the orginal query | ||
|
|
|
|
|
session.request.externallogoutreasons
Requests the client provide a list of appropriate logout reasons for this session. Note: This request produces the "session.externallogoutreasons.updated" event in response.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | session.request.externallogoutreasons | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | session.request.externallogoutreasons | Name of the original 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. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
session.request.externalnotreadyreasons
Requests the client provide a list of appropriate not ready reasons for this session. Note: This request produces the "session.externalnotreadyreasons.updated" event in response.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | session.request.externalnotreadyreasons | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | session.request.externalnotreadyreasons | Name of the original 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. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
session.request.dispose
Notifies the client that the processor bridge is ready to dispose of the session and that any underlying CTI resources should be released. The actual disposal of resources should be performed after a response is returned. This request differs from session.request.close in that the agent state should not be modified in any way. The client should merely dispose of any CTI resources and clear any cached data about the agent session.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | session.request.dispose | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | session.request.dispose | Name of the original 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. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
session.request.getteamstatus
Requests the current status of all team members from the switch. The “realtime” flag determines if the switch should provide realtime updates to team status through events.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | session.request.getteamstatus | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
realtime | Boolean | True if updates events should be sent. False otherwise |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | session.request.getteamstatus | Name of the original 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. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Response Body
Below is an example of the JSON contained in the event message:
{
"teamstatus" :
[
{
"loginid" : "<agent login id>",
"firstname" : "<agent first name>",
"lastname" : "<agent last name>",
"extension" : "<agent extension>",
"state" : "<agent state>",
"statechangetime" : "<agent state change time>"
},
…
]
}
session.request.stopteamstatus
Indicates the switch should stop providing realtime updates related team status through events.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | session.request.stopteamstatus | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | session.request.stopteamstatus | Name of the original 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. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Client Events
This section describes the possible events the client can send the processor bridge to the session destination. In most cases, these events are unsolicited though may be the indirect result of executing a previously received request message.
session.closed
This event indicates that the CTI side of the agent session has been closed. This event is generally only raised as a result of executing a session.request.close request message.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | session.closed | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
session.channel.added
This event indicates that a channel was added for this agent.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | session.channel.added | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
endpoint | String | The endpoint of the channel that was added |
type | String | Type of channel. TELEPHONY | EMAIL | CHAT | CALLBACK, UNSUPPORTED |
session.channelgroup.added
This event indicates that a channel group was added for this agent.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | session.channelgroup.added | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
name | String | The name of the channel group (CTI identifier) |
session.externallogoutreasons.updated
This event indicates that the appropriate logout reasons for this session have changed. This event contains a body of JSON that describes the logout reasons.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | session.externallogoutreasons.updated | Name of this event type |
target | String | See generating message targets above |
Event Body
Below is an example of the JSON contained in the event message:
{
"logoutReasons" :
[
{
"logoutReasonId" : "<unique-id-of-reason>",
"logoutReasonCode" : "<code- of-reason>",
"extensions" : [],
"labels" :
[
{
"language" : "en",
"country" : "US",
"name" : "<name-in-language>",
"description" : "<description>"
},
…
]
},
…
]
}session.externalnotreadyreasons.updated
This event indicates that the appropriate not ready reasons for this session have changed. This event contains a body of JSON that describes the not ready reasons.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | session.externalnotreadyreasons.updated | Name of this event type |
target | String | See generating message targets above |
Event JSON
Below is an example of the JSON contained in the event message:
{
"reasonCodes" :
[
{
"reasonCodeId" : "<unique-id-of-reason>",
"reasonCodeCode" : "<code- of-reason>",
"selectable" : true|false
"extensions" : [],
"labels" :
[
{
"language" : "en",
"country" : "US",
"name" : "<name-in-language>",
"description" : "<description>"
},
…
]
},
…
]
}
session.teamstatus.updated
This event indicates that the status of one or more team members has changed. This event contains a body of JSON that describes the updated team members.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | session.teamstatus.updated | Name of this event type |
target | String | See generating message targets above |
Event JSON
Below is an example of the JSON contained in the event message:
Client Warnings
This section describes the generic unsolicited warnings that can be delivered to the client.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.warning | Event messages will always have this value |
name | Warning name | Name of this warning |
target | String | See generating message targets above |
code | String | Warning Code |
message | String | Warning Message |
Warning JSON
Below is an example of the JSON contained in the warning message:
Client Errors
This section describes the generic unsolicited errors that can be delivered to the client.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.error | Event messages will always have this value |
name | Error name | Name of this error |
target | String | See generating message targets above |
code | String | Error Code |
message | String | Error Message |
Error JSON
Below is an example of the JSON contained in the error message:
This document may contain confidential and/or privileged information belonging to OpenMethods. If you are not the intended recipient (or have received this document in error) please notify the sender immediately and destroy this document. Any unauthorized copying, disclosure, or distribution of the material in this document is strictly forbidden.