Engagement API Version Differences
| New Field | Renamed Field | Deleted Field |
Engagement APIs
Summary of changes:
- The path has changed (base path + API path). "accountId" is mandatory in path of each API
- "channelProviderId", "customerIdentifiers", "participantId" not required to be provided in Engagement APIs as the values will be derived from session object referenced by "sessionId"
- Timestamps have changed from Epoch timestamp (int64) to 'yyyy-MM-dd'T'HH:mm:ss[.SSS]Z' format
-
Few fields renamed, added or removed in request and response payload to make the data more consistent
| API Version | /v1 | /v1beta | ||||||
|---|---|---|---|---|---|---|---|---|
| Base Path | https://HOST-REGION.cc.avayacloud.com/api/digital | https://HOST-REGION.cc.avayacloud.com/api/digital/channel | ||||||
Create Engagement |
POST /v1/engagements |
POST /v1beta/accounts/ {accountId} /engagements |
||||||
|
|
Fields | Mandatory | Comment | Fields | Mandatory | Comment | ||
| Path Parameters |
|
|
|
accountId | Y |
|
||
|
|
||||||||
| Request Payload |
sessionId
|
|
|
sessionId | Y |
|
||
|
|
accountId
|
|
Shifted to path parameter |
|
|
|
||
|
|
mediaType
|
|
|
channelId
|
Y |
|
||
|
|
conversation
|
|
|
conversation
|
|
|
||
|
|
correlationId
|
|
|
correlationId |
|
|
||
|
|
contextParameters
|
|
|
engagementParameters
|
|
Renamed Field | ||
|
|
providerDialogId |
|
|
providerDialogId |
|
|
||
|
|
channelProviderId |
|
Information was already provided while creating session |
|
|
|
||
|
|
customerIdentifier |
|
Information was already provided while creating session |
|
|
|
||
|
|
|
|||||||
| Response |
Refer to Create Engagement Response model |
|||||||
|
|
||||||||
|
Sample Request |
|
|
||||||
|
Sample Response |
Refer to Sample Create Engagement response |
|||||||
|
|
||||||||
List Engagements |
GET /v1/engagements
|
GET /v1beta/accounts/
{accountId}
/engagements
|
||||||
|
|
Fields | Mandatory | Comment | Fields | Mandatory | Comment | ||
| Path Parameters |
|
|
|
accountId | Y |
|
||
|
|
||||||||
| Response | Refer to Engagement Response model | |||||||
|
|
||||||||
| Sample response | Refer to Sample List Engagement Response | |||||||
|
|
||||||||
Get Engagement |
GET /v1/engagements/ {engagementId} |
GET /v1beta/accounts/ {accountId} /engagements/ {engagementId} |
||||||
|
|
Fields | Mandatory | Comment | Fields | Mandatory | Comment | ||
| Path Parameters |
|
|
|
accountId | Y |
|
||
| engagementId | Y |
|
engagementId | Y |
|
|||
|
|
||||||||
| Response | Refer to Engagement Response model | |||||||
| Sample response | Refer to Sample Get Engagement response | |||||||
|
|
||||||||
Disconnect Engagement |
POST /v1/engagements/ {engagementId} :disconnect |
POST /v1beta/accounts/ {accountId} /engagements/ {engagementId} :disconnect |
||||||
|
|
Fields | Mandatory | Comment | Fields | Mandatory | Comment | ||
| Path Parameters |
|
|
|
accountId | Y |
|
||
| engagementId | Y |
|
engagementId | Y |
|
|||
|
|
||||||||
| Request Payload |
Refer to Disconnect Engagement response |
|||||||
|
|
||||||||
| Response | 200 OK | 200 OK | ||||||
|
|
||||||||
| Sample Request |
|
|
||||||
| Sample Response |
No response object. |
|
||||||
|
|
||||||||
Join Engagement |
POST /v1/engagements/{engagementId}:join |
POST /v1beta/accounts/{accountId}/engagements/{engagementId}:join |
||||||
|
|
Fields | Mandatory | Comment | Fields | Mandatory | Comment | ||
| Path Parameters |
|
|
|
accountId | Y |
|
||
| engagementId | Y |
|
engagementId | Y |
|
|||
|
|
||||||||
| Request Payload |
Refer to Join Engagement |
|||||||
|
|
||||||||
| Response |
Refer to Engagement Response model |
|||||||
|
|
||||||||
| Sample Request |
|
|
||||||
| Sample Response |
Refer to Sample Get Engagement response |
|||||||
|
|
||||||||
Send Message |
POST /v1/engagements/{engagementId}/messages |
POST /v1beta/accounts/{accountId}/engagements/{engagementId}/messages |
||||||
|
|
Fields | Mandatory | Comment | Fields | Mandatory | Comment | ||
| Path Parameters |
|
|
|
accountId | Y |
|
||
| engagementId | Y |
|
engagementId | Y |
|
|||
|
|
||||||||
| Request Payload | Refer to Send Message | |||||||
|
|
||||||||
| Response | Refer to Message response | |||||||
|
|
||||||||
| Sample Request |
|
|
||||||
|
|
||||||||
| Sample Response | Refer to Sample Send Message response | |||||||
|
|
||||||||
Get/List Messages |
GET /v1/engagements/ {engagementId} /messages |
GET /v1beta/accounts/ {accountId} /engagements/ {engagementId} /messages |
||||||
| Path Parameters |
|
|
|
accountId | Y |
|
||
| engagementId | Y |
|
engagementId | Y |
|
|||
|
|
||||||||
| Query Paramaters | dialogId | Y |
|
dialogId | Y |
|
||
| sessionId | Y |
|
sessionId | Y |
|
|||
|
|
|
|
pageSize |
|
Default : 10 | |||
|
|
|
|
pageNumber |
|
Default : 1 | |||
|
|
||||||||
| Response | Refer to /v1 Message | Refer to MessagePage | ||||||
|
|
||||||||
| Sample Response |
Refer to Sample Get Message response |
|||||||
|
|
||||||||
Retrieve notification events |
GET /v1/engagements/ {engagementId} /notifications |
Not supported in /v1beta | ||||||
|
|
||||||||
Comparison of /v1 and /v1beta models
Create Engagement Response model
| Model |
/v1 |
/v1beta |
||||
|---|---|---|---|---|---|---|
| Model Name | EngagementCreated | Engagement | ||||
|
Response model |
engagementId
|
|
|
engagementId
|
Y |
|
|
accountId
|
|
|
accountId
|
|
|
|
|
conversation
|
|
|
conversation | Y |
|
|
| correlationId |
|
|
correlationId |
|
|
|
| mediType |
|
Moved to Dialog > channelId | url | Y |
|
|
|
dialogId
|
|
Moved to Dialog > dialogId | dialogs | Y | Array of Dialog Model | |
|
sessionId
|
|
Moved to Dialog > Connection > sessionIds |
|
|
|
|
|
customerIdentifier |
|
Removed |
|
|
|
|
|
createTimeMillis
|
|
Moved to Dialog > createdAt |
|
|
|
|
| providerDialogId |
|
Moved to Dialog > providerDialogId |
|
|
|
|
Engagement Response model
| Model |
/v1 |
/v1beta |
||||
|---|---|---|---|---|---|---|
| Model Name | Engagement | Engagement | ||||
|
Response model |
engagementId
|
|
|
engagementId
|
Y |
|
|
accountId
|
|
|
accountId
|
Y |
|
|
|
conversation
|
|
|
conversation |
|
|
|
| uri |
|
|
url | Y |
|
|
|
dialogs
|
|
Array of /v1 Dialog Model | dialogs | Y | Array of /v1beta Dialog Model | |
| correlationId |
|
Removed | correlationId |
|
|
|
| customerIdentifier |
|
Removed |
|
|
|
|
| engagementStatus |
|
Refer Dialog > dialogStatus |
|
|
|
|
|
createTimeMillis
|
|
Moved to Dialog > createdAt
|
|
|
|
|
| updateTimeMillis |
|
Moved to Dialog > lastUpdatedAt |
|
|
|
|
Dialog Model
| API Version | /v1 |
|
|
/v1beta | ||
|---|---|---|---|---|---|---|
| Model Name | Dialog |
|
|
Dialog | ||
|
|
Field | Mandatory | Comments | Field | Mandatory? | Comments |
| 1 | dialogId |
|
|
dialogId | Y |
|
| 2 | dialogStatus |
|
|
dialogStatus | Y | PENDING, ACTIVE, TERMINATING, TERMINATED |
| 3 | mediaType |
|
|
channelId | Y |
|
| 4 | sourceParticipantId |
|
|
initiatorParticipantId | Y |
|
| 5 | connections |
|
Array of
/v1 Participant
Object |
connections | Y | Array of /v1beta Connection Model |
| 6 | contextParameters |
|
|
engagementParameters |
|
|
| 7 |
|
|
|
createdAt | Y |
|
| 8 |
|
|
|
lastUpdatedAt | Y |
|
| 9 | providerDialogId |
|
|
providerDialogId |
|
|
/v1 Participant Model
|
|
Field | Mandatory | Enum values |
|---|---|---|---|
| 1 | connectionId | Y |
|
| 2 | participantId | Y |
|
| 3 | displayName | Y |
|
| 4 | sessionIds |
|
|
| 5 | participantType |
|
CUSTOMER, AGENT, SUPERVISOR, SYSTEM, BOT |
| 6 | connectionState |
|
ACTIVE, INACTIVE, DISCONNECTED |
| 7 | participantMode |
|
PUBLIC, WHISPER_ONLY, LISTEN_ONLY |
| 8 | metadata |
|
|
/v1beta Connection Model
|
|
Field | Mandatory | Enum values |
|---|---|---|---|
| 1 | connectionId | Y |
|
| 2 | participantId | Y |
|
| 3 | participantType | Y | CUSTOMER, AGENT, SUPERVISOR, SYSTEM, BOT |
| 4 | displayName |
|
|
| 5 | sessionIds |
|
|
| 6 | connectionState | Y | CONNECTED, DISCONNECTED |
DisconnectEngagement
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name | DisconnectEngagement |
DisconnectEngagement
|
||||
|
|
Field | Mandatory | Comments | Field | Mandatory? | Comments |
| 1 |
sessionId
|
|
|
sessionId
|
Y |
|
| 2 |
dialogId
|
|
|
dialogId
|
Y |
|
| 3 | reason |
|
UNKNOWN, USER_DISCONNECTED, USER_CLOSED, USER_INACTIVE, SYSTEM_CLOSED | reason |
|
USER_CLOSED, USER_INACTIVE, SYSTEM_CLOSED, UNKNOWN |
| 4 | participantId |
|
Derived from sessionId | correlationId |
|
|
JoinEngagement
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name |
JoinEngagement
|
JoinEngagement | ||||
|
|
Field | Mandatory | Comments | Field | Mandatory? | Comments |
| 1 |
sessionId
|
|
|
sessionId
|
Y |
|
| 2 |
dialogId
|
|
|
dialogId
|
Y |
|
| 3 |
customerIdentifier
|
|
Derived from sessionId |
correlationId
|
|
|
SendMessage
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
|
|
SendMessage
|
SendMessage
|
||||
|
|
Field | Mandatory | Comments | Field | Mandatory? | Comments |
| 1 | correlationId |
|
|
correlationId |
|
|
| 2 | parentMessageId |
|
|
parentMessageId
|
|
|
| 3 | providerMessageId |
|
|
providerMessageId |
|
|
| 4 | providerParentMessageId |
html
|
|
providerParentMessageId |
|
|
| 5 | sessionId | Y |
|
sessionId | Y |
|
| 6 | dialogId | Y |
|
dialogId | Y |
|
| 7 | body | Y | String | body | Y |
Object of \v1beta BodyElement
|
| 8 | senderName |
|
|
senderParticipantName |
|
|
| 9 | fallbackText |
|
|
fallbackText |
|
|
| 10 | headers |
|
Object of MessageHeaders | headers |
|
Object of MessageHeaders |
| 11 | customData |
|
|
customData |
|
|
| 12 | providerSenderId |
|
Derived from sessionId (providerCustomerId) |
|
|
|
| 13 | senderType |
|
Implicit value "CUSTOMER" |
|
|
|
Message
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name | MessageEvent | MessageEvent | ||||
|
|
Field | Mandatory | Comments | Field | Mandatory | Comments |
| 1 | messageId | Y |
|
messageId |
|
|
| 2 | accountId |
|
|
accountId | Y |
|
| 3 | dialogId | Y |
|
dialogId |
|
|
| 4 | engagementId | Y |
|
engagementId |
|
|
| 5 | status | Y |
|
status | Y |
|
| 6 | sessionId |
|
|
sessionId |
|
|
| 7 | senderId |
|
|
senderParticipantId | Y |
|
| 8 | senderName |
|
|
senderParticipantName | Y |
|
| 9 | body |
|
Object of
BodyElement
|
body | Y | Object of BodyElement |
| 10 | attachments |
|
|
attachments |
|
Array of Attachment object |
| 11 | parentMessageId |
|
|
parentMessageId |
|
|
| 12 | correlationId |
|
|
correlationId |
|
|
| 13 |
fallbackText
|
|
|
fallbackText |
|
|
| 14 |
headers
|
|
Object of MessageHeaders | headers |
|
Object of MessageHeaders |
| 15 | createTimeMillis |
|
Removed | recipientParticipants |
|
Array of Participant object |
| 16 |
customData
|
|
Replaced with customData | customData |
|
|
| 17 |
|
|
|
messageIndex |
|
|
| 18 | senderType |
|
|
senderParticipantType | Y |
|
| 19 | businessAccountName | Y |
|
businessAccountName |
|
|
| 20 | channelProviderId | Y |
|
channelProviderId | Y |
|
| 21 | channelId | Y |
|
channelId | Y |
|
| 22 | providerDialogId |
|
|
providerDialogId |
|
|
| 23 | providerSenderId |
|
|
providerSenderId |
|
|
| 24 | providerMessageId |
|
|
providerMessageId |
|
|
| 25 | providerParentMessageId |
|
|
providerParentMessageId |
|
|
| 26 | contextParameters |
|
|
engagementParameters |
|
|
| 27 | receivedTimestamp |
|
|
receivedAt |
|
|
| 28 | lastUpdatedTimestamp |
|
|
lastUpdatedAt |
|
|
BodyElement
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name |
BodyElement
|
BodyElement
|
||||
|
|
Field | Mandatory | Comments | Field | Mandatory | Comments |
| 1 | elementType | Y |
|
elementType | Y |
|
| 2 | elementText |
|
Object of Text | elementText |
|
Object of Text |
| 3 | payload |
|
|
payload |
|
|
Text (No Change)
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name | Text | Text | ||||
|
|
Field | Mandatory | Comments | Field | Mandatory | Comments |
| 1 | text | Y |
|
text | Y |
|
| 2 | textFormat |
|
Enum [ PLAINTEXT, . HTML, MARKDOWN ] |
textFormat |
|
Enum [ PLAINTEXT, HTML, MARKDOWN ] |
MessageHeaders (No Change)
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name | MessageHeaders | MessageHeaders | ||||
|
|
Field | Mandatory | Comments | Field | Mandatory | Comments |
| 1 | priority |
|
|
priority |
|
|
| 2 | sensitivity |
|
|
sensitivity |
|
|
| 3 | encoding |
|
|
encoding |
|
|
| 4 | subject |
|
|
subject |
|
|
| 5 | from |
|
|
from |
|
|
| 6 | to |
|
|
to |
|
|
| 7 | cc |
|
|
cc |
|
|
| 8 | bcc |
|
|
bcc |
|
|
| 9 | replyTo |
|
|
replyTo |
|
|
| 10 | clientDeviceTag |
|
|
clientDeviceTag |
|
|
| 11 | messageSourceServerTag |
|
|
messageSourceServerTag |
|
|
| 12 | providerTimestamp |
|
|
providerTimestamp |
|
|
| 13 | additionalHeaders |
|
|
additionalHeaders |
|
|
Participant
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name | Participant | Participant | ||||
|
|
Field | Mandatory | Comments | Field | Mandatory | Comments |
| 1 | participantId | Y |
|
participantId | Y |
|
| 2 | participantType | Y |
Enum [ CUSTOMER, AGENT, SUPERVISOR, SYSTEM, BOT ] |
participantType | Y |
Enum [ CUSTOMER, AGENT, SUPERVISOR, SYSTEM, BOT ] |
| 3 | participantAddress |
|
Simila | providerParticipantId |
|
|
| 4 | connectionId |
|
|
connectionId |
|
|
| 5 | displayName |
|
|
displayName |
|
|
| 6 |
|
|
|
channelProviderId |
|
|
Attachment
| API Version | /v1 | /v1beta | ||||
|---|---|---|---|---|---|---|
| Model Name | Attachment | Attachment | ||||
|
|
Field | Mandatory | Comments | Field | Mandatory | Comments |
| 1 | id | Y |
|
attachmentId |
|
|
| 2 | name | Y |
|
name | Y |
|
| 3 | size | Y |
|
size | Y |
|
| 4 | contentType | Y |
|
contentType | Y |
|
| 5 | url | Y |
|
url | Y |
|
| 6 | captionText |
|
|
captionText |
|
|
| 7 | thumbnailUrl |
|
|
thumbnailUrl |
|
|
| 8 | additionalProperties |
|
|
additionalProperties |
|
|
| 9 |
|
|
|
contentId |
|
|
MessagePage
| API Version | /v1beta | ||
|---|---|---|---|
| Model Name | MessagePage | ||
|
|
Field | Mandatory | Comments |
| 1 | pagination |
|
pagination |
| 2 | messages |
|
Array of /v1beta Message object |
| 3 | links |
|
Object of Links |
Pagination
| API Version | /v1beta | ||
|---|---|---|---|
| Model Name |
Pagination
|
||
|
|
Field | Mandatory | Comments |
| 1 | prev |
|
|
| 2 | next |
|
|
Links
| API Version | /v1beta | ||
|---|---|---|---|
| Model Name |
Links
|
||
|
|
Field | Mandatory | Comments |
| 1 |
pageNumber
|
|
|
| 2 |
pageSize
|
|
|
| 3 |
total
|
|
|
Sample Response for /v1 and /v1beta
Create Engagement
| API Version | /v1 |
/v1beta |
||
|---|---|---|---|---|
| Model Name | EngagementCreated | Engagement | ||
|
|
|
|
List Engagement
|
API Version |
/v1 |
/v1beta |
||
|---|---|---|---|---|
| Model Name | Engagement | Engagement | ||
|
|
|
|
GET Engagement
|
API Version |
/v1 |
/v1beta |
||
|---|---|---|---|---|
| Model Name | Engagement | Engagement | ||
|
|
|
|
Send Message
|
API Version |
/v1 |
/v1beta |
||
|---|---|---|---|---|
| Model Name | Message |
Message
|
||
|
|
|
|
Get Message
|
API Version |
/v1 |
/v1beta |
||
|---|---|---|---|---|
| Model Name | Message |
MessagePage
|
||
|
|
|
|