The telephony interaction destination is a specialized type of generic interaction destination for telephony-based interactions. The telephony interaction destination inherits all the basic functionality of the generic interaction destination and adds support for new features:
Dial consult
Transfer to consult
Conference in consult
Alternate
As with the processor control destination, the telephony interaction destination follows the same lifecycle of setup, initialization, and tear down. The following figure depicts the initialization phase of a telephony interaction 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 any deltas between the generic interaction destination queries and those appropriate for the telephony interaction destination.
interaction.query.init
The format and contents of the query message remains the same for the telephony interaction destination. However, the JSON contained in the response message has additional content specific to telephony interactions.
Response JSON
Below is an example of the JSON returned in the response message:
{
"interaction-state" : "INTERACTION_STATE",
"interaction-data" :
{
"DATA_KEY" : "DATA_VALUE",
"DATA_KEY" :
{
"DATA_SUB_KEY" : "DATA_VALUE",
…
},
…
},
"conversations" :
{
"primary" :
{
"id" : "PRIMARY_CONVERSATION_ID"
},
"consult" :
{
"id" : "CONSULT_CONVERSATION_ID"
}
}
}The JSON content is largely the same as for generic interactions. However, a new section, conversations, is included for telephony interactions. The conversations object must be present even if no child objects are provided. The primary object must be present if the interaction is in one of these states: ALERTING, DIALING, or STARTED. The consult object can only be present if the interaction is in the STARTED state and the agent has an active consult call. The conversations object must be empty if the telephony interaction is in the ENDED or COMPLETED state.
Special Considerations
If there are any conversation related elements present, a conversation destination will be created for each one. Any interaction related events sent to the destination remain in queue until these objects are initialized themselves. 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 telephony interaction destination beyond those defined for the generic interaction 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.
interaction.request.createconversation
Instructs the client to prepare a new conversation and register with the conversation destination described in the request message. The request will only occur during the initialization phase or after a successful interaction.request.consult request.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | interaction.request.createconversation | 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 |
|---|---|---|
id | String | Bridge id of the conversation |
nativeid | String | CTI id of the conversation |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | interaction.request.createconversation | 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 |
interaction.request.consult
Requests the client place the primary conversation on hold and place a new outbound consult call. This request is only valid when the interaction is in the STARTED state.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | interaction.request.consult | 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 | The destination number for the consult call |
Response Headers
Key | Value | Notes |
|---|---|---|
type | cti.response | Response messages will always have this value |
name | interaction.request.consult | Name of the original request |
result | SUCCESS | FAILURE | Result of the request |
errorMessage | String | A human readable description of the error that caused this request to fail. This message will be logged and may be displayed to an agent. |
target | String | See generating message targets above |
requestId | {GUID} | Unique identifier for the orginal query |
Response Properties
Key | Value | Notes |
|---|---|---|
nativeid | String | CTI id of the conversation created for the consult call |
Special Considerations
This request triggers a complex set of messages to coordinate the setup and creation of the conversation object and destination associated with this request. The following figure illustrates the steps:
interaction.request.consulttransfer
Requests the client transfers the primary conversation’s parties to the consult conversation’s party. Transfer of conversations already in conference is the responsibility of the client.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | interaction.request.consulttransfer | 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 | interaction.request.reject | 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 |
interaction.request.consultconference
Requests the client bridge all parties of the consult conversation into the primary conversation.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | interaction.request.consultconference | 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 | interaction.request.consultconference | 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 |
interaction.request.alternate
Requests the client alternate between the active and inactive conversations of this interaction. The last conversation to have been in the talking state is considered to be active. If the active conversation is unable to be determined, the primary conversation is considered active.
Request Headers
Key | Value | Notes |
|---|---|---|
type | cti.request | Request messages will always have this value |
name | interaction.request.alternate | 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 | interaction.request.alternate | 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 |
Client Events
This section describes the possible events the client can send the processor bridge over the telephony interaction destination beyond those defined for the generic interaction destination. In most cases, these events are unsolicited though may be the indirect result of executing a previously received request message.
interaction.consult
This event indicates that a consult conversation has been initiated outside of Harmony.
Event Headers
Key | Value | Notes |
|---|---|---|
type | cti.event | Event messages will always have this value |
name | interaction.consult | Name of this event type |
target | String | See generating message targets above |
Event Properties
Key | Value | Notes |
|---|---|---|
nativeid | String | The CTI id of the consult conversation |