Session Resource

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

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

Secondary Events

None.

channelgroup.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

Secondary Events

Activating a channel will generate the following secondary events:

channel.infochanged
state.updated

channel.request.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

Success Response

Failure Response

Secondary Events

Deactivating a channel will generate the following secondary events:

channel.infochanged
state.updated

channel.request.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

Success Response

Failure Response

Secondary Events

Placing an agent into ready status on a channel will generate the following secondary events:

channel.infochanged
state.updated

channel.request.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

Success Response

Failure Response

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.

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.

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.

session.incontact.agentleg.failed

Indicates that the Incontact agent leg failed to connect.

session.incontact.addressbook.updated

Indicates that the Incontact agent leg failed to connect.

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.

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.

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.

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.

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.

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.

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.

directory.updated

Indicates that the directory listing has been updated. This event is triggered by making a request to session.request.getdirectory.

Telephony and Multimedia Requests and Responses

channel.request.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

Success Response

Failure Response

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:

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

Success Response

Failure Response

Secondary Events

Placing an outbound call on a channel will generate the following secondary events:

channel.externaldispositions.updated

interaction.request.incontact.signal (InContact only)

Requests that a signal is sent to the active script for the interaction.

Request

Success Response

Failure Response

Secondary Events

Signaling a script can have any number of side-effects. There may be changes to the call state or the results might be completely hidden from the agent.

interaction.request.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

Success Response

Failure Response

Secondary Events

Accepting an interaction will generate the following secondary events:

interaction.screenpop
state.updated (interaction state event)

interaction.request.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.request.release" request instead. A failure is generated if the agent cannot reject the interaction.

Request

Success Response

Failure Response

Secondary Events

Rejecting an interaction will generate the following secondary events:

interaction.ended
state.updated (interaction state event)

interaction.request.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

Success Response

Failure Response

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

Success Response

Failure Response

Secondary Events

Modifying the interaction disposition does not generate any secondary events.

interaction.request.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

Success Response

Failure Response

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:

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:

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

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

Success Response

Failure Response

Secondary Events

Performing resume recording will generate the following secondary events:

state.updated (interaction state event)

conversation.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.request.hold (Telephony only)

Places the target conversation on hold. A failure is generated if the call cannot be held.

Request

Success Response

Failure Response

Secondary Events

Holding an active call will generate the following secondary events:

state.updated (conversation state event)

conversation.request.retrieve (Telephony only)

Retrieves the target conversation from hold. A failure is generated if the call cannot be retrieved.

Request

Success Response

Failure Response

Secondary Events

Retrieving a held call will generate the following secondary events:

state.updated (conversation state event)

conversation.request.mute (Telephony only)

Places the target conversation on mute. A failure is generated if the call cannot be muted.

Request

Success Response

Failure Response

Secondary Events

Muting an active call will generate the following secondary events:

state.updated (conversation state event)

conversation.request.unmute (Telephony only)

Unmutes the target conversation. A failure is generated if the call cannot be unmuted.

Request

Success Response

Failure Response

Secondary Events

Unmuting a call will generate the following secondary events:

state.updated (conversation state event)

conversation.request.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

Success Response

Failure Response

Secondary Events

Sending DTMF tones does not generate any secondary events.

conversation.request.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

Success Response

Failure Response

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.request.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

Success Response

Failure Response

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.

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.

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.

interaction.incontact.signaladded

Indicates the provided signal is now available to use with the referenced interaction. These signals are accessed through the incontact specific Launch functionality

interaction.incontact.signalremoved

Indicates the provided signal is no longer available to use with the referenced interaction.