A session resource represents an active agent session with the underlying CTI platform. It is a dynamic resource created as the result of a successful prepareSession service request. A session resource is designed to only allow a single client to bind to it; almost always the same client who called prepareSession.
Session Resource Messages
There are three categories of requests supported by a session resource: session management, telephony control, and multimedia control. All implementations must support the session management requests. However, the telephony and multimedia control categories are optional, with most implementations at least supporting telephony. Not all implementations will include multimedia control, as the underlying CTI may not support multimedia functionality.
The "command" property of requests and the "name" property of events will indicate the type of object the message is related to based on the prefix of the property value. Session object requests and events always start with the "session." prefix. This holds true for channel, interaction, and conversation objects.
The "target" property of session requests, responses, and events represents the object the message is directed to or is the source of the message. The property contains a text value that follows '.' (dot) notation identifying the full object ownership. The final segment of the value is the unique identifier for the target object, while each previous segment matches that object's parent. The first segment is always the session id.
The "data" property carries any request, response, or event specific information that is needed to perform the requested action or describe the event. The "context" property is optional for all messages and serves as a tool for debugging protocol implementations. Under normal circumstances "context" should not be present. Below is an example that shows the context of a telephony conversation:
"context":
{
"conversation":
{
"id": "<conversation-id>",
"interaction":
{
"id": "<interaction-id>",
"type": "Telephony",
"modeltype": "TELEPHONY",
"channel":
{
"id": "<channel-id>",
"name": "<channel-name>",
"type": "TELEPHONY",
"modeltype": "TELEPHONY",
"session":
{
"id": "<session-id>"
}
}
}
}
}
Session Management Requests and Responses
session.start
The client sends this session management request immediately after it has bound the session resource. Any other request sent prior to this message will generate an error response. The interaction processor begins the session initialization process once this message is received. The extension property is optional and is only used by the Avaya Processor at this time.
Request
{
"command": "session.start",
"target": "<session-id>",
"data":
{
"extension": "<telephony channel extension>"
}
}
Success Response
{
"command": "session.start",
"target": "<session-id>",
"result": "success"
}
Failure Response
{
"command": "session.start",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
During session initialization, the interaction processor determines the agent's current state within the underlying CTI platform. If the agent already has active channels, interactions, or conversations, those objects will be created within the session resource and events about their current state will be sent to the client. Regardless of any additional events generated during initialization, the session.initialized event will always be generated when the process is complete.
session.logout
The client sends this session management request to indicate that the session should end and all associated objects should be released. The interaction processor should not respond to this request until the logout process has completed.
Request
{
"command": "session.logout",
"target": "<session-id>",
"data": {}
}
Success Response
{
"command": "session.logout",
"target": "<session-id>",
"result": "success"
}
Failure Response
{
"command": "session.logout",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Logging out of a session should not generate any secondary events. The session should be completely inert once the process is complete and a success is returned.
session.addchannel
Adds a standalone channel to this agent session. The type of channel to be added is provided in the "data" property. The endpoint (i.e. extension for telephony) for the channel is also included in the "data" property.
Request
{
"command": "session.addchannel",
"target": "<session-id>",
"data":
{
"channel":
{
"endpoint": "<CTI-channel-identifier>",
"type": "Telephony | Chat | Email"
}
}
}
Success Response
{
"command": "session.addchannel",
"target": "<session-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "session.addchannel",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Several secondary events might occur during initialization of a channel. However, if the channel is successfully added, the client will always receive the following events:
· channel.created
· state.updated (channel state event)
· channel.initialized
session.removechannel
Removes a previously added standalone channel from this agent session. The channel will automatically be deactivated if it is still active. A failure is generated if the channel has an active interaction or cannot be deactivated before being removed from the session.
Request
{
"command": "session.removechannel",
"target": "<session-id>",
"data":
{
"channel":
{
"id": "<channel-identifier>"
}
}
}
Success Response
{
"command": "session.removechannel",
"target": "<session-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "session.removechannel",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Removing a channel will generate the following secondary events:
· channel.infochanged (If still active)
· state.updated (channel state event, if still active)
· channel.disposed
session.addchannelgroup
Adds a channel group to this agent session. All channels associated with the given group will then be added to the group during the initialization phase. The channel group to add is identified in the "data" property of the request.
Request
{
"command": "session.addchannelgroup",
"target": "<session-id>",
"data":
{
"channelgroup":
{
"name": "<CTI-channel-group-identifier>",
"chat": true | false,
"email": true | false,
"callback": true | false
}
}
}
Success Response
{
"command": "session.addchannelgroup",
"target": "<session-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "session.addchannelgroup",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Several secondary events might occur during initialization of a channel group and its associated channels. However, if the channel group is successfully added, the client will always receive the following events:
· channelgroup.created
· state.updated (channel group state event)
· channel.created (for each associated channel)
· state.updated (channel state event)
· channel.initialized
· channelgroup.initialized
session.removechannelgroup
Removes a previously added channel group and its associated channels from this agent session. Associated channels will automatically be deactivated if they are still active. A failure is generated if an associated channel has an active interaction or cannot be deactivated before being removed from the group.
Request
{
"command": "session.removechannelgroup",
"target": "<session-id>",
"data":
{
"channel":
{
"id": "<channel-group-identifier>"
}
}
}
Success Response
{
"command": "session.removechannelgroup",
"target": "<session-id>,
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "session.removechannelgroup",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Removing a channel group will generate the following secondary events:
· channel.infochanged (for each associated channel If still active)
· state.updated (channel state event, if still active)
· channel.disposed
· state.updated (channel group state event)
· channelgruop.disposed
session.request.getdirectory
Retrieves a directory listing of quick dial entries directly from the switch. These entries are added to the static entries available from Config Server.
Request
{
"command": "session.request.getdirectory",
"target": "<session-id>",
"data":
{
}
}
Success Response
{
"command": " session.request.getdirectory ",
"target": "<session-id>,
"result": "success",
"data":
{
}
}
Failure Response
{
"command": " session.request.getdirectory ",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Requesting the directory does not generate any secondary events.
session.request.externalnotreadyreasons (Optional)
Requests the list of not ready reason codes available to this agent. If supported by the CTI platform, the list should come directly from the platform.
Request
{
"command": "session.request.externalnotredyreasons",
"target": "<session-id>",
"data":
{
}
}
Success Response
{
"command": "session.request.externalnotreadyreasons",
"target": "<session-id>",
"result": "success",
"data":
{
}
}
Failure Response
{
"command": "session.request.externalnotreadyreasons",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
If this request is supported, a session.externalnotreadyreasons.updated event is generated that contains the list of not ready reason codes available to the agent.
session.request.externallogoutreasons
Requests the list of logout reason codes available to this agent. If supported by the CTI platform, the list should come directly from the platform.
Request
{
"command": "session.request.externallogoutreasons",
"target": "<session-id>",
"data":
{
}
}
Success Response
{
"command": "session.request.externallogoutreasons",
"target": "<session-id>",
"result": "success",
"data":
{
}
}
Failure Response
{
"command": "session.request.externallogoutreasons",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
If this request is supported, a session.externallogoutreasons.updated event is generated that contains the list of logout reason codes available to the agent.
session.request.incontact.agentleg.connect
Requests the agent leg be connected.
Request
{
"command": "session.request.incontact.agentleg.connect",
"target": "<session-id>",
"data":
{
}
}
Success Response
{
"command": " session.request.incontact.agentleg.connect",
"target": "<session-id>",
"result": "success",
"data":
{
}
}
Failure Response
{
"command": "session.request.incontact.agentleg.connect",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
If successful, a session.agentleg.connected event will be generated. Otherwise, a session.agentleg.failed event will be generated.
session.request.incontact.agentleg.disconnect
Requests the agent leg be connected.
Request
{
"command": "session.request.incontact.agentleg.disconnect",
"target": "<session-id>",
"data":
{
}
}
Success Response
{
"command": " session.request.incontact.agentleg.disconnect",
"target": "<session-id>",
"result": "success",
"data":
{
}
}
Failure Response
{
"command": "session.request.incontact.agentleg.disconnect",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
If successful, a session.agentleg.disconnected event will be generated.
session.request.incontact.addressbook
Requests a structured list of dial destinations. The destination structure is specific to Incontact. The "realtime" property controls whether or not update events will be sent to the client.
Request
{
"command": "session.request.incontact.addressbook",
"target": "<session-id>",
"data":
{
"realtime": true | false
}
}
Success Response
{
"command": " session.request.incontact.addressbook",
"target": "<session-id>",
"result": "success",
"data":
{
"addressbooks":
[
{
"name": "<address_book_name>",
"groups":
[
"name": "<group_name>",
"groups": []
"entries": []
],
"entries":
[
"type": "external" | "agent" | "skill",
"destinations":
[
"label": "<destination_label>",
"value": "<destination_value>"
]
"name": "<entry_name>",
"properties":
{
#agent_properties#
"state": "<agent_state_name>"
#skill_properties#
"mediaType": "<skill_media_type>",
#optional skill properties
"numAvailable": <num_avail_agents>,
"numUnavailable": <num_unavail_agents>,
"ewt": "<estimated_wait_time>"
}
]
}
]
}
}
Failure Response
{
"command": "session.request.incontact.addressbook",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
If the real time property is true, a session.incontact.addressbook.updated event is periodically generated that contains fully updated address book information that should replace any previous information.
session.request.incontact.addressbook.stop
Requests that any ongoing address book real time updates stop. This should be called after requesting the address book with the real time property as true and updates are no longer required.
Request
{
"command": "session.request.incontact.addressbook.stop",
"target": "<session-id>",
"data":
{
}
}
Success Response
{
"command": " session.request.incontact.addressbook.stop",
"target": "<session-id>",
"result": "success",
"data":
{
}
}
Failure Response
{
"command": "session.request.incontact.addressbook.stop",
"target": "<session-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
None.
channelgroup.activateall
Attempts to place all channels associated with the channel group into activated status. Channels that are already activated will be unaffected by this request. A failure is generated if one of the channels cannot be activated for some reason. Any channels that were already activated during this request will remain active after a failure but remaining channels will not be activated.
The "data" property should carry any CTI specific activation parameters within the "channeloptions" array. Each channel that requires parameters should be represented by a JSON structure identifying the channel by id and any other necessary JSON properties or structure to perform the activation.
Request
{
"command": "channelgroup.activateall",
"target": "<session-id>.<channel-group-id>",
"data":
{
"channeloptions":
[
{
"id": "<channel-identifier>",
"queue": "<channel-queue>"
}
…
]
}
}
Success Response
{
"command": "channelgroup.activateall",
"target": "<session-id>.<channel-group-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channelgroup.activateall",
"target": "<session-id>.<channel-group-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Activating the channels associated with a channel group will generate the following secondary events:
· channel.infochanged (for each associated channel If not active)
· state.updated (channel state event, if not active)
channelgroup.deactivateall
Attempts to place all channels associated with the channel group into inactive status. Channels that are already inactive will be unaffected by this request. A failure is generated if one of the channels cannot be deactivated for some reason. Any channels that were already deactivated during this request will remain inactive after a failure but remaining channels will not be deactivated.
Request
{
"command": "channelgroup.deactivateall",
"target": "<session-id>.<channel-group-id>",
"data": {}
}
Success Response
{
"command": "channelgroup.deactivateall",
"target": "<session-id>.<channel-group-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channelgroup.deactivateall",
"target": "<session-id>.<channel-group-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Deactivating the channels associated with a channel group will generate the following secondary events:
· channel.infochanged (for each associated channel If active)
· state.updated (channel state event, if active)
channel.activate
Attempts to place the given channel into activated status. A failure is generated if the channel cannot be activated or is already in the active state. The "data" property should carry any CTI specific activation parameters within the "channeloptions" property.
Request
{
"command": "channel.activate",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"data":
{
"channeloptions":
{
"queue": "<channel-queue>"
}
}
}
Success Response
{
"command": "channel.activate",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channel.activate",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Activating a channel will generate the following secondary events:
· channel.infochanged
· state.updated
channel.deactivate
Attempts to place the channel into inactive status. A failure is generated if the channel cannot be deactivated for some reason or is already in the inactive state.
Request
{
"command": "channel.deactivate",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"data":
{
"channelOptions":
{
"queue": "<optional list of queues that are being deactivated>",
"reason": "<optional numerical code for logout reason>"
}
}
}
Success Response
{
"command": "channel.deactivate",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channel.deactivate",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Deactivating a channel will generate the following secondary events:
· channel.infochanged
· state.updated
channel.ready
Attempts to place the agent into ready status on the given channel. A failure is generated if the channel is not already in the active state or if the agent cannot be made ready on that channel.
Request
{
"command": "channel.ready",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"data": {}
}
Success Response
{
"command": "channel.ready",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channel.ready",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Placing an agent into ready status on a channel will generate the following secondary events:
· channel.infochanged
· state.updated
channel.notready
Attempts to place the agent into not ready status on the given channel. The "reasoncode" and "reasondesc" properties of the "data" request structure control the type of not ready status the agent enters. The "reasoncode" property is required and should map to the CTI specific configuration for that agent. The "reasondesc" property is informational is not required. A special reason code of "acw" can be used to enter the After Call Work mode offered by many CTI platforms. A failure is generated if the channel is not already in the active state or if the agent cannot be made not ready on that channel.
Request
{
"command": "channel.notready",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"data":
{
"reasoncode": "acw | <CTI-reason-code>",
"reasondesc": "<Descriptive text>"
}
}
Success Response
{
"command": "channel.notready",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channel.notready",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Placing an agent into not ready status on a channel will generate the following secondary events:
· channel.infochanged
· state.updated
Session Management Events
session.initialized
Indicates the session has been fully initialized. During the initialization process, the interaction processor will determine the current state of the agent based on information retrieved from the underlying switch platform. If the agent is already logged into channels or channel groups, those items will be created and initialized prior to this message being delivered.
{
"messageType": "objectEvent",
"target": "<session_id>",
"name": "session.initialized",
"data": {}
}
session.externalnotreadyreasons.updated
Indicates that the list of not ready reason codes available has been updated. This event is generated as a result of session.request.externalnotreadyreasons.
{
"messageType": "objectEvent",
"target": "<session_id>",
"name": "session.externalnotreadyreasons.updated",
"data":
{
"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.externallogoutreasons.updated
Indicates that the list of logout reason codes available has been updated. This event is generated as a result of session.request.externallogoutreasons.
{
"messageType": "objectEvent",
"target": "<session_id>",
"name": "session.externallogoutreasons.updated",
"data":
{
"logoutReasons":
[
{
"logoutReasonId": "<unique-id-of-reason>",
"logoutReasonCode": "<code- of-reason>",
"extensions": [],
"labels":
[
{
"language": "en",
"country": "US",
"name": "<name-in-language>",
"description": "<description>"
}
…
]
},
…
]
}
}
session.incontact.agentleg.failed
Indicates that the Incontact agent leg failed to connect.
{
"messageType": "objectEvent",
"target": "<session_id>",
"name": "session.incontact.agentleg.failed",
"data":
{
"error": "<error_message>"
}
}
session.incontact.addressbook.updated
Indicates that the Incontact agent leg failed to connect.
{
"messageType": "objectEvent",
"target": "<session_id>",
"name": "session.incontact.addressbook.updated",
"data":
{
"addressbooks":
[
{
"name": "<address_book_name>",
"groups":
[
"name": "<group_name>",
"groups": []
"entries": []
],
"entries":
[
"type": "external" | "agent" | "skill",
"destinations":
[
"label": "<destination_label>",
"value": "<destination_value>"
]
"name": "<entry_name>",
"properties":
{
#agent_properties#
"state": "<agent_state_name>"
#skill_properties#
"mediaType": "<skill_media_type>",
#optional skill properties
"numAvailable": <num_avail_agents>,
"numUnavailable": <num_unavail_agents>,
"ewt": "<estimated_wait_time>"
}
]
}
]
}
}
channel.created
Indicates a new channel has been created. The target property will determine if this channel was created on the session, and thus a standalone channel, or if it is a member of a channel group. This event will appear during session initialization if the agent is already logged into the channel (recovering an active session or through some other mechanism). It will also be raised in response to a successful session.addchannel or session.addchannelgroup request.
{
"messageType": "objectEvent",
"target": "<session_id>" | "<session_id>.<channelgroup_id>",
"name": "channel.created",
"data":
{
"channel":
{
"id": "<channel_id>",
"name": "<endpoint_name>",
"type": "TELEPHONY" | "EMAIL" | "CHAT" | "<custom_type>",
"modelType": "TELEPHONY" | "EMAIL" | "CHAT" | "<custom_type>"
}
}
}
channel.infochanged
Indicates a state change has occurred for the target channel. This change can either be to the overall channel state or to the agent's availability. A channel can be in one of three states:
· INACTIVE – No agent is logged onto this channel
· UNAVAILABLE – An agent other than the one associated with this session is logged into this channel
· ACTIVE – The agent associated with this channel is logged into this channel
Agent availability has three components: status, reason code, and reason name. The status indicates the general availability of the agent. There are three main status types and a sub status for each main type:
· ready – The agent is ready to received an interaction on this channel
· not_ready – The agent is not ready to receive interactions on this channel
· after_call_work – The agent is finalizing work related to the last interaction and is not ready to receive a new one
The "busy_" status sub type indicates that the agent is actively handling an interaction but their overall status has not changed according to the underlying switching platform. Not all platforms will use or support the busy status sub types.
{
"messageType": "objectEvent",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"name": "channel.infochanged",
"data":
{
"state": "INACTIVE" | "UNAVAILABLE" | "ACTIVE",
"agentStatus":
{
"status": "ready" | "not_ready" | "after_call_work" | "busy" | "busy_ready" | "busy_not_ready" | "busy_after_call_work",
"lastReasonCode": "acw" | "<cti_reason_id>",
"lastReasonName": "" | "<readable_reason_name>"
}
}
}
channel.initialized
Indicates that the channel has been fully initialized after being added to a session or channel group. Channels are always added in the INACTIVE state. One or more channel.infochanged events may be raised prior to channel.initialized to reflect the actual state of the channel and the agent's current availability.
{
"messageType": "objectEvent",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"name": "channel.initialized",
"data": {}
}
channel.disposed
Indicates that the channel has been removed from the session or channel group and disposed of. The client should release any resources related to the channel. No further requests can be submitted to this channel and the channel will produce no further events.
{
"messageType": "objectEvent",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"name": "channel.disposed",
"data": {}
}
channelgroup.created
Indicates a new channel group has been created and added to the session. This event will appear during session initialization if the agent is already logged into the channel group (recovering an active session or through some other mechanism). It will also be raised in response to a successful session.addchannelgroup request.
{
"messageType": "objectEvent",
"target": "<session_id>",
"name": "channelgroup.created",
"data":
{
"channelgroup":
{
"id": "<channelgroup_id>",
"name": "<channelgroup_name>",
}
}
}
channelgroup.initialized
Indicates that the channel group has been fully initialized after being added to the session. All member channels will have been added to this group and initialized prior to this event being raised.
{
"messageType": "objectEvent",
"target": "<session-id>.<channel-group-id>",
"name": "channelgroup.initialized",
"data": {}
}
channelgroup.disposed
Indicates that the channel group has been removed from this session and disposed of. The client should release any resources associated with the channel group. No further requests can be submitted to this channel group and the channel group will produce no further events.
{
"messageType": "objectEvent",
"target": "<session-id>.<channel-group-id>",
"name": "channelgroup.disposed",
"data": {}
}
directory.updated
Indicates that the directory listing has been updated. This event is triggered by making a request to session.request.getdirectory.
{
"messageType": "objectEvent",
"target": "<session-id>",
"name": "directory.updated",
"data":
{
"categories":
[
{
"name": "<category_name>",
"entries":
[
{
"name": "<entry_name>",
"number": "<entry_number>"
}
…
]
}
…
]
}
}
Telephony and Multimedia Requests and Responses
channel.dial (Telephony only)
Attempts to place an outbound call using the given telephony channel. The "destination" property of the "data" request property contains the number to be dialed. A failure is generated if the channel is not already in the active state or if the outbound call cannot be initiated for some reason. The extensions object can be empty or missing if not applicable to the current request.
Request
{
"command": "channel.dial",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"data":
{
"destination": "<number-to-dial>",
"extensions":
{
<platform-specific-extensions>
}
}
}
Success Response
{
"command": "channel.dial",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channel.dial",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Placing an outbound call on a channel will generate the following secondary events:
· channel.infochanged
· state.updated (channel state event)
· interaction.created
· state.updated (interaction state event)
· conversation.created
· state.updated (conversation state event)
· conversation.member.added
· conversation.initialized
· interaction.datachanged
· interaction.preview
· interaction.initialized
Incontact Extensions
Incontact has two extensions for making an outbound call: type of call destination and outbound skill to use. The type of destination is provided in the "type" property of the extensions object and can have a value of "external", "agent", or "skill. This extension is required. The outbound skill to use is provided by the "skill" property of the extensions object. This extension is only required when the agent has more than one outbound skill configured and the destination type is external. The media bar should attempt to make the call without the outbound skill extension populated. If a skill needs to be selected, the media bar will receive a NeedsMoreInfo error that contains the available outbound skills to choose from:
{
"command": "channel.dial",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "needinfo",
"uiExtension":
{
"id": "inContact.outboundskill",
"skills":
[
{
"id": "<skill_id>",
"skillName": "<skill_name>"
}
]
}
"original":
<Contains the original request JSON structure>
}
channel.request.externaldispositions
Requests a list of dynamic interaction dispositions appropriate for the channel. After a successful request the list of interaction dispositions is delivered in a channel.externaldispositions.updated event.
Request
{
"command": "channel.request.externaldispositions",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"data":
{
}
}
Success Response
{
"command": "channel.request.externaldispositions",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "channel.request.externaldispositions",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Placing an outbound call on a channel will generate the following secondary events:
· channel.externaldispositions.updated
interaction.accept (Telephony and Multimedia)
Accepts an alerting interaction. A new interaction, whether from an inbound call or multimedia contact, will generate an "interaction.preview" event. However, the interaction is still not officially assigned to the agent. The agent must accept the interaction before it is assigned. Although this request can be used to accept in inbound phone call, it is recommended for clients to use the telephony specific "conversation.answer" request instead. A failure is generated if the interaction cannot be assigned to the agent.
Request
{
"command": "interaction.accept",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": "interaction.accept",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.accept",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Accepting an interaction will generate the following secondary events:
· interaction.screenpop
· state.updated (interaction state event)
interaction.reject (Telephony and Multimedia)
Rejects an alerting interaction. A new interaction, whether from an inbound call or multimedia contact, will generate an "interaction.preview" event. However, the interaction is still not officially assigned to the agent. The agent reject the interaction before it is assigned allowing another agent to handle the interaction. Although this request can be used to reject in inbound phone call, it is recommended for clients to use the telephony specific "conversation.release" request instead. A failure is generated if the agent cannot reject the interaction.
Request
{
"command": "interaction.reject",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": "interaction.reject",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.reject",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Rejecting an interaction will generate the following secondary events:
· interaction.ended
· state.updated (interaction state event)
interaction.setinteractiondata (Telephony and Multimedia)
Attempts to add or modify the call data of an interaction. The "key" and "value" properties of the "data" request property hold the name of the data item and its value. If the key already exists, the current value is overwritten with the new value. If the key does not exist, it is added to the call data. A failure is generated if the interaction call data cannot be updated for some reason.
Request
{
"command": "interaction.setinteractiondata",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data":
{
"key": "[name-of-data-item]",
"value": "[value-of-data-item]"
}
}
Success Response
{
"command": "interaction.setinteractiondata",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.setinteractiondata",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Modifying the interaction call data will generate the following secondary events:
· interaction.datachanged
interaction.request.setdisposition (Telephony and Multimedia)
Attempts to add or modify the disposition of an interaction. The "disposition" properties of the "data" request property holds the value. A failure is generated if the interaction disposition cannot be updated for some reason.
Request
{
"command": "interaction.setdisposition",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data":
{
"disposition": "[disposition-text]"
}
}
Success Response
{
"command": "interaction.setdisposition",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.setdisposition",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Modifying the interaction disposition does not generate any secondary events.
interaction.complete (Telephony and Multimedia)
Marks the interaction complete indicating no additional work is required by the agent. A failure is generated if the agent cannot reject the interaction. Multimedia interactions can be completed at any time after being accepted. All conversations of a telephony interaction must have ended before the interaction can be completed.
Request
{
"command": "interaction.complete",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": "interaction.complete",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.complete",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Incontact Extensions
Incontact has two extensions for completing an interaction: ACW and Interaction Disposition. The current implementation of Interaction Disposition isn't compatible with InContact as each skill can have this turned on and have a different set of available dispositions to choose from. The media bar should attempt to complete the interaction without additional information to see either the ACW or Interaction Disposition behavior is required.
If a skill has ACW enabled, the interaction is actually completed by changing the agent state back to ready. The media bar will receive a NeedsInfo response:
{
"command": "interaction.request.complete",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "needinfo",
"uiExtension":
{
"type": "agentstate"
}
"original":
<Contains the original request JSON structure>
}
This indicates that the media bar should simulate a click on the agent state drop-down so the agent can select a new state. This automatically complete the current interaction.
If a skill has Interaction Disposition enabled, the media bar will receive a NeedsInfo response:
{
"command": "interaction.request.complete",
"target": "<session-id>.<channel-id>" |
"<session-id>.<channel-group-id>.<channel-id>",
"result": "needinfo",
"uiExtension":
{
"type": "disposition",
"dispositionRequired": true | false,
"dispositions": [
{
"dispositionId": 0,
"dispositionName": "string",
"priority": 0,
"isPreviewDisposition": true
}
]
}
"original":
<Contains the original request JSON structure>
}
The media bar should provide the agent a way to select a disposition as well as provide a set of notes related to the interaction. The call should be made again providing "skipDisposition": true if dispositionRequired is false and the agent doesn't select a disposition. Otherwise the call is should be made providing "dispositionId" and "notes" properties.
Secondary Events
Completing an interaction will generate the following secondary events:
· interaction.complete
· state.updated (interaction state event)
· interaction.disposed
interaction.consult (Telephony only)
Places the current call on hold and attempts to place a second outbound call under the same interaction. The "destination" property of the "data" request property contains the number to be dialed. A failure is generated if the interaction has not started or if the outbound call cannot be initiated for some reason.
Request
{
"command": "interaction.consult",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data":
{
"destination": "[number-to-dial]"
}
}
Success Response
{
"command": "interaction.consult",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.consult",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Placing a consult call will generate the following secondary events:
· state.updated (interaction state event)
· state.updated (conversation state event, original call)
· conversation.created
· state.updated (conversation state event, new call)
· conversation.member.added
· conversation.initialized
· interaction.focuschanged
interaction.alternate (Telephony only)
Places the current talking party on hold and retrieves the other held party. A failure is generated if a consult call is not connected.
Request
{
"command": "interaction.alternate",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": "interaction.alternate",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.alternate",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Alternating between the primary and consult calls will generate the following secondary events:
· state.updated (conversation state event, original call)
· state.updated (conversation state event, consult call)
· interaction.focuschanged
interaction.consulttransfer (Telephony only)
Attempts to transfer the original call party to the consult call party. If successful, both conversations will end for this agent and the two parties will be connected together. A failure is generated if a consult call is not connected or the call cannot be transferred.
Request
{
"command": "interaction.consulttransfer",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": "interaction.consulttransfer",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.consulttransfer",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing a consult transfer will generate the following secondary events:
· state.updated (conversation state event, original call)
· conversation.disposed (original call)
· interaction.focuschanged
· state.updated (conversation state event, consult call)
· conversation.disposed (consult call)
· interaction.ended
interaction.consultconference (Telephony only)
Attempts to conference the consult call party into the original call. If successful, both parties will be in conference together. A failure is generated if a consult call is not connected or the call cannot be conferenced.
Request
{
"command": "interaction.consultconference",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": "interaction.consultconference",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "interaction.consultconference",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing a consult conference will generate the following secondary events:
· state.updated (conversation state event, consult call)
· conversation.disposed (consult call)
· conversation.memeber.added (original call, consult party)
· state.updated (conversation state event, original call)
· interaction.focuschanged
interaction.request.recording.start (Telephony only)
Attempts to start call recording. If recording is already underway, this should successfully return.
Request
{
"command": "interaction.request.recording.start",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": " interaction.request.recording.start",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": " interaction.request.recording.start",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing start recording will generate the following secondary events:
· state.updated (interaction state event)
interaction.request.recording.stop (Telephony only)
Attempts to stop call recording. If recording is already stopped, this should successfully return.
Request
{
"command": "interaction.request.recording.stop",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": " interaction.request.recording.stop",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": " interaction.request.recording.stop",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing stop recording will generate the following secondary events:
· state.updated (interaction state event)
interaction.request.recording.pause (Telephony only)
Attempts to pause call recording. Not all platforms will support the pause operation and will return an unsupported error.
Request
{
"command": "interaction.request.recording.pause",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": " interaction.request.recording.pause",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": " interaction.request.recording.pause",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing pause recording will generate the following secondary events:
· state.updated (interaction state event)
interaction.request.recording.resume (Telephony only)
Attempts to resume call recording. Not all platforms will support the resume operation and will return an unsupported error.
Request
{
"command": "interaction.request.recording.resume",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"data": {}
}
Success Response
{
"command": " interaction.request.recording.resume",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": " interaction.request.recording.resume",
"target": "<session-id>.<channel-id>.<interaction-id>" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing resume recording will generate the following secondary events:
· state.updated (interaction state event)
conversation.answer (Telephony only)
Answers an inbound phone call. This request also assigns the interaction to the agent as if "interaction.accept" were used. A failure is generated if the call cannot be answered.
Request
{
"command": "conversation.answer",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data": {}
}
Success Response
{
"command": "conversation.answer",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.answer",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Answering an inbound call will generate the following secondary events:
· state.updated (conversation state event)
· interaction.screenpop
· state.updated (interaction state event)
conversation.release (Telephony only)
Disconnects the agent from an active phone call. If a two-party call is released both the agent and other party are disconnected. If a multi-party conference is released, only the agent is removed from conference while the remaining parties stay in conference. A failure is generated if the call cannot be disconnected.
Request
{
"command": "conversation.release",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data": {}
}
Success Response
{
"command": "conversation.release",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.release",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Releasing an active call will generate the following secondary events:
· state.updated (conversation state event)
· conversation.disposed
· interaction.ended (if only conversation is released)
· state.updated (interaction state event)
conversation.hold (Telephony only)
Places the target conversation on hold. A failure is generated if the call cannot be held.
Request
{
"command": "conversation.hold",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data": {}
}
Success Response
{
"command": "conversation.hold",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.hold",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Holding an active call will generate the following secondary events:
· state.updated (conversation state event)
conversation.retrieve (Telephony only)
Retrieves the target conversation from hold. A failure is generated if the call cannot be retrieved.
Request
{
"command": "conversation.retrieve",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data": {}
}
Success Response
{
"command": "conversation.retrieve",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.retrieve",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Retrieving a held call will generate the following secondary events:
· state.updated (conversation state event)
conversation.mute (Telephony only)
Places the target conversation on mute. A failure is generated if the call cannot be muted.
Request
{
"command": "conversation.request.mute",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data": {}
}
Success Response
{
"command": "conversation.request.mute",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.request.mute",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Muting an active call will generate the following secondary events:
· state.updated (conversation state event)
conversation.unmute (Telephony only)
Unmutes the target conversation. A failure is generated if the call cannot be unmuted.
Request
{
"command": "conversation.request.unmute",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data": {}
}
Success Response
{
"command": "conversation.request.unmute",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.request.unmute",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Unmuting a call will generate the following secondary events:
· state.updated (conversation state event)
conversation.senddtmf (Telephony only)
Generates DTMF tones to the other parties on a call. The request is used to produce DTMF tones for navigating automated systems using the client interface. A failure is generated if DTMF cannot be sent.
Request
{
"command": "conversation.retrieve",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data": {}
}
Success Response
{
"command": "conversation.retrieve",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.retrieve",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Sending DTMF tones does not generate any secondary events.
conversation.blindtransfer (Telephony only)
Attempts to transfer the call to the given destination. The call will be disconnected from the agent regardless of whether it is successful. A failure is generated if the call cannot be transferred.
Request
{
"command": "conversation.blindtransfer",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data":
{
"destination": "[number-to-dial]"
}
}
Success Response
{
"command": "conversation.blindtransfer",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.blindtransfer",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing a blind transfer will generate the following secondary events:
· state.updated (conversation state event, original call)
· conversation.disposed (original call)
· interaction.focuschanged
· interaction.ended (if only one call was active)
conversation.blindconference (Telephony only)
Attempts to conference the party at the given destination into the original call. If successful, both parties will be in conference together. A failure is generated if the call cannot be conferenced.
Request
{
"command": "conversation.blindconference",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"data":
{
"destination": "[number-to-dial]"
}
}
Success Response
{
"command": "conversation.blindconference",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "success",
"data":
{
<Same data contents as original request>
}
}
Failure Response
{
"command": "conversation.blindconference",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"result": "failure",
"failure":
{
"code": "<error-code-for-failure>",
"message": "<error-message>",
"context": "<stack-trace-if-applicable>"
}
"original":
<Contains the original request JSON structure>
}
Secondary Events
Performing a blind conference will generate the following secondary events:
· conversation.memeber.added (original call, destination party)
· state.updated (conversation state event, original call)
Telephony and Multimedia Events
interaction.created
Indicates a new interaction has been created. The target property identifies the channel associated with the interaction. This event will appear during session initialization if the agent is already logged into the channel (recovering an active session or through some other mechanism). It will also be raised in response to a successful session.addchannel or session.addchannelgroup request.
{
"messageType": "objectEvent",
"target": "<session_id>.<channel-id>" | "<session_id>.<channelgroup_id>.<channel-id>",
"name": "interaction.created",
"data":
{
"interaction":
{
"id": "<interaction_id>",
"nativeId": "<interaction_native_id>",
"type": "TELEPHONY" | "EMAIL" | "CHAT" | "CALLBACK" | "<custom_type>",
"modelType": "TELEPHONY" | "EMAIL" | "CHAT" | "CALLBACK" | "<custom_type>"
<platform-or-type-specific-interaction-properties>
},
}
}
PureCloud Callback interactions will have an additional property "callbackNumbers" that is an array of string values representing the phone numbers that will be used to initiate outbound callbacks.
channel.externaldispositions.updated
Indicates the allowable set of interaction dispositions for a channel have changed. It will be raised in response to a successful channel.request.externaldispositions request.
{
"messageType": "objectEvent",
"target": "<session_id>.<channel-id>" | "<session_id>.<channelgroup_id>.<channel-id>",
"name": "channel.externaldispositions.updated",
"data":
{
"dispositions":
[
{
"interactionDispositionId":"<disposition-id>",
"value":"<disposition-value>",
"extensions":[],
"labels":
[
{
"language":"en",
"country":"US",
"name":"<disposition-name>",
"description":"<disposition-description"
},
…
]
},
…
]
}
}
conversation.updated
Indicates the data associated with a conversation has changed. The most common use of this event is to notify the client that the native id for the conversation has changed.
{
"messageType": "objectEvent",
"target": "<session-id>.<channel-id>.<interaction-id>.<http://conversation.id >" | "<session-id>.<channel-group-id>.<channel-id>.<interaction-id>.<http://conversation.id >",
"name": "conversation.updated",
"data":
{
<platform-specific-conversation-data>
}
}
0 Comments