The processor bridge creates a conversation destination for each call leg of a telephony interaction. There are most two conversations per interaction: a primary conversation and an optional consult conversation. The destination is used to monitor and control the conversation’s CTI state. The conversation destination adds support for most telephony features:
Answer
Release (Hang up)
Hold/Retrieve
Blind Transfer
Blind Conference
Send DTMF tones
As with the processor control destination, the conversation destination follows the same lifecycle of setup, initialization, and tear down. The following figure depicts the initialization phase of a conversation destination:
It is important to note that with all CTI resource related communication destinations, no event messages should be raised prior to receiving and responding to the initialization query message.
Queries & Responses
This section defines the possible query messages the processor bridge may send over the conversation destination and the format of any expected result messages.
conversation.query.init
This query retrieves information about the conversation’s current state within the CTI. The response to this query carries a JSON payload describing the current state.
Query Headers
Key | Value | Notes |
|---|---|---|
type | cti.query | Query messages will always have this value |
name | conversation.query.init | Name of this query type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Query Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.query.init | Name of the original query |
result | SUCCESS | FAILURE | Result of the query |
errorMessage | String | A human readable description of the error that caused this query to fail. This message will be logged and may be displayed to the agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Response JSON
Below is an example of the JSON returned in the response message:
{
"conversation-state" : "CONVERSATION_STATE",
"parties" :
[
{
"number" : "PARTY_NUMBER",
"name" : "PARTY_NAME"
},
…
]
}The conversation state must one of the standard states:
RINGING – Inbound call is ringing waiting for agent to answer
DIALING – Outbound call is waiting for other party to answer
TALKING – The call is connected and not on hold
HELD – The call is connected but on hold
RELEASED – The call has ended, either through the agent or other party disconnecting
The parties array must be present and must contain at least one party child object. If the conversation represents a multi-party conference, all known parties should have a party object.
Special Considerations
Any conversation related events sent to the destination remain in queue until the conversation is fully initialized. Once this is complete, any waiting events are processed in the order they arrived.
Requests
This section defines the possible requests the processor bridge may make to the conversation destination. The client will always generate a response message as a result of these requests. Some requests require the client to perform actions in a particular order. These constraints will be detailed in the description of the request.
conversation.request.answer
Requests the client answer the inbound call and assign the interaction to this agent. This request will not be used in most cases. The interaction level request interaction.request.accept will be used instead. This request is included in the API in an effort to be comprehensive.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.answer | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.answer | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.release
Requests the client disconnects from this phone call. If this conversation is the primary call leg and the interaction is still in the ALERTING or DIALING state, the interaction level request interaction.request.reject will be issued in place of this request. This request will be used at all other times to disconnect the call.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.release | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.release | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.removeparty
Requests the client remove the indicated party from this conference.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.removeparty | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
number | String | The number of the party to remove from conference |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.release | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.hold
Requests the client place this call on hold. If the call is already in the HELD state, no action should be taken, and a successful response issued.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.hold | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.hold | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.retrieve
Requests the client retrieve this call from the HELD state and return to the TALKING state. If the call is already in the TALKING state, no action should be taken, and a successful response issued
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.retrieve | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.retrieve | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to the agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.mute
Requests the client place this call on mute. If the call is already in the MUTE state, no action should be taken, and a successful response issued.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.mute | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.mute | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.unmute
Requests the client unmute this call from the MUTE state and return to the TALKING state. If the call is already in the TALKING state, no action should be taken, and a successful response issued
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.unmute | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.unmute | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to the agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.transfer
Requests the client blind transfer this call to the provided destination number. The destination may be an internal extension or an external DID.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.transfer | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
destination | String | Transfer destination |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.transfer | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.conference
Requests the client blind conference the party at the provided destination number into this call. The destination may be an internal extension or an external DID.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.conference | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
destination | String | Transfer destination |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.conference | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
conversation.request.senddtmf
Requests the client generate the provided digits as DTMF tones on this call.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.senddtmf | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
digits | String (0-9, *, #) | DTMF digits |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.senddtmf | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Special Considerations
Unlike most other requests, this one should not return a successful response until the tones are generated.
conversation.request.dispose
Notifies the client that the processor bridge is ready to dispose of the conversation and that any underlying CTI resources should be released. The actual disposal of resources should be performed after a response is returned.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | conversation.request.dispose | Name of this request type |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Request Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | conversation.request.dispose | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Client Events
This section describes the possible events the client can send the processor bridge to the conversation destination. In most cases, these events are unsolicited though may be the indirect result of executing a previously received request message.
conversation.ringing
This event indicates that this inbound call is ringing on the agent’s phone. This is used for inbound calls only. Outbound calls must raise the conversation.dialing client event.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.ringing | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.dialing
This event indicates that this outbound call is dialing and waiting for the called party to answer.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.dialing | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.busy
This event indicates that this outbound call has failed because the destination number is busy.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.busy | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.failed
This event indicates that this outbound call has failed due to some reason. Most likely reasons include invalid number, number out of service, or the called party has rejected the call.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.failed | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
reason | String | Agent readable reason for failure |
conversation.held
This event indicates that this call has been placed on hold. This event should be raised regardless of why the call enters the hold state.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.held | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.mute
This event indicates that this call has been placed on mute. This event should be raised regardless of why the call enters the mute state.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.mute | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.talking
This event indicates that this call has entered the TALKING state. This can either be raised as a result of the agent accepting an inbound call, the called party answering an outbound call, a previously held call is retrieved, or a previously muted call is unmuted.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.talking | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.partyadded
This event indicates that a new party has been added to the call. This event should be raised when the call is first answered and any time an additional party joins the call.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.partyadded | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
number | String | Destination number for added party |
name |
|
|
conversation.partyremoved
This event indicates that a party has been removed from the call.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.partyremoved | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
number | String | Destination number for removed party |
conversation.started
This event indicates that the conversation has started. This event should precede any hold, talking or ended events.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.started | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.ended
This event indicates that the conversation has ended. This can be the result of the agent or other party disconnecting from the call.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.ended | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
None |
|
|
conversation.transfer.failed
This event indicates that a previous request for a blind transfer has failed in some way.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.transfer.failed | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
reason | String | Agent readable reason for failure |
conversation.conference.failed
This event indicates that a previous request for a blind conference has failed in some way.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | conversation.conference.failed | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
reason | String | Agent readable reason for failure |