Webhook API Comparison

New

Field

Renamed

Field

Deleted Field

Notification APIs

Summary of changes:

The path has changed (base path + API path). "accountId" is mandatory in path of each API
"channelProviderId" which had to be passed as path parameter is now part of request payload
Timestamps have changed from Epoch timestamp (int64) to
'yyyy-MM-dd'T'HH:mm:ss[.SSS]Z' format
Earlier each webhookId could have multiple subscriptions. Now each subscriptions can be directly accessed by subscriptionId.
Few new 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/webhook/

Create Subscription

POST /v1/channel-providers/{channelProviderId}/webhooks

POST /v1beta/accounts/{accountId}/subscriptions

Fields Mandatory Comment Fields Mandatory Comment

Path Parameters channelProviderId Y accountId Y

Request Payload Subscription Y Array of Subscription
object channelProviderId Y

callbackUrl Y Supports only https urls

eventTypes Y

Response webhookId Y Use subscriptionId instead subscriptionId Y

Subscription Array of Subscription
object channelProviderId Y

callbackUrl Y

eventTypes Y

Sample request

                                  [
    {
      "callbackUrl": "https://myserver.com/send/callback/here",
      "eventTypes": [
        "MESSAGES"
      ]
    }
  ]

                                      {
    "channelProviderId": "ChatProvider01",
    "callbackUrl": "https://www.example.com/send/callback/here",
    "eventTypes": [
      "MESSAGES"
    ]
  }

Sample Response

                                      {
    "webhookId": "2581e39b-fe84-4e38-87f4-63a1d037f39a",
    "subscriptions": [
      {
        "callbackUrl": "https://myserver.com/send/callback/here",
        "eventTypes": [
          "MESSAGES"
        ]
      }
    ]
  }

                                      {
    "subscriptionId": "2581e39b-fe84-4e38-87f4-63a1d037f39a",
    "channelProviderId": "ChatProvider01",
    "callbackUrl": "https://www.example.com/send/callback/here",
    "eventTypes": [
      "MESSAGES"
    ]
  }

Get Subscription(s)

GET /v1/channel-providers/{channelProviderId}/webhooks

GET /v1beta/accounts/{accountId}/subscriptions

Fields Mandatory Comment Fields Mandatory Comment

Path Parameters channelProviderId Y accountId Y

Response

webhookId

Use subscriptionId instead

subscriptionId

subscriptions

Array of Subscription
object

channelProviderId

callbackUrl

eventTypes

Sample Response

                                      [
    {
      "webhookId": "2581e39b-fe84-4e38-87f4-63a1d037f39a",
      "subscriptions": [
        {
          "callbackUrl": "https://myserver.com/send/callback/here",
          "eventTypes": [
            "MESSAGES"
          ]
        }
      ]
    }
  ]

                                      [
    {
      "subscriptionId": "2581e39b-fe84-4e38-87f4-63a1d037f39a",
      "channelProviderId": "ChatProvider01",
      "callbackUrl": "https://www.example.com/send/callback/here",
      "eventTypes": [
        "MESSAGES"
      ]
    }
  ]

Get Subscription

GET /v1/channel-providers/{channelProviderId}/webhooks/{webhookId}

GET /v1beta/accounts/{accountId}/subscriptions/{subscriptionId}

Fields Mandatory Comment Fields Mandatory Comment

Path Parameters channelProviderId Y accountId Y

webhookId Y Use subscriptionId instead subscriptionId Y

Response

webhookId

subscriptionId

subscriptions

Array of Subscription
object

channelProviderId

callbackUrl

eventTypes

Sample Response

                                      [
    {
      "callbackUrl": "https://myserver.com/send/callback/here",
      "eventTypes": [
        "MESSAGES"
      ]
    }
  ]

                                      {
    "subscriptionId": "2581e39b-fe84-4e38-87f4-63a1d037f39a",
    "channelProviderId": "ChatProvider01",
    "callbackUrl": "https://www.example.com/send/callback/here",
    "eventTypes": [
      "MESSAGES"
    ]
  }

Update Subscription

PUT /v1/channel-providers/{channelProviderId}/webhooks/{webhookId}

PUT /v1beta/accounts/{accountId}/subscriptions/{subscriptionId}

Fields Mandatory Comment Fields Mandatory Comment

Path Parameters channelProviderId Y accountId Y

webhookId Y Use subscriptionId instead subscriptionId Y

Request Payload subscriptions Subscription
object channelProviderId Y

callbackUrl

Supports only https URLs

eventTypes

Response webhookId Y Use subscriptionId instead subscriptionId Y

Subscription Y Array of Subscription
object channelProviderId

callbackUrl

eventTypes

Sample Request

                                      [
    {
      "callbackUrl": "https://myserver.com/send/callback/here",
      "eventTypes": [
        "MESSAGES"
      ]
    }
  ]

                                      {
    "channelProviderId": "ChatProvider01",
    "callbackUrl": "https://www.example.com/send/callback/here/instead",
    "eventTypes": [
      "ALL"
    ]
  }

Sample response

                                      {
    "webhookId": "2581e39b-fe84-4e38-87f4-63a1d037f39a",
    "subscriptions": [
      {
        "callbackUrl": "https://myserver.com/send/callback/here",
        "eventTypes": [
          "MESSAGES"
        ]
      }
    ]
  }

                                      {
    "subscriptionId": "2581e39b-fe84-4e38-87f4-63a1d037f39a",
    "channelProviderId": "ChatProvider01",
    "https://www.example.com/send/callback/here/instead",
    "eventTypes": [
      "ALL"
    ]
  }

Delete Subscription

DELETE /v1/channel-providers/{channelProviderId}/webhooks/{webhookId}

DELETE /v1beta/accounts/{accountId}/subscriptions/{subscriptionId}

Fields Mandatory Comment Fields Mandatory Comment

Path parameters channelProviderId Y accountId Y

webhookId Y Use subscriptionId instead subscriptionId Y

Response 200 OK 204 No content

Subscription Model

API Version	/v1
Model Name	Subscription
	Field	Mandatory	Comments
1	callbackUrl	Y
2	eventType	Y	[MESSAGES, PARTICIPANT_ADDED, PARTICIPANT_DISCONNECTED, ENGAGEMENT_CREATED, ENGAGEMENT_ERROR, ALL ]

Callback Response Model

EngagementCreatedEvent

API Version	/v1			/v1beta
Model Name	EngagementCreatedEvent			EngagementCreatedEvent
	Field	Mandatory	Comments	Field	Mandatory	Comments
1	eventType	Y		eventType	Y
2	correlationId			correlationId	Y
3	engagementId	Y		engagementId	Y
4	tenantId	Y		accountId	Y
5	channelProviderId	Y		channelProviderId	Y
6	providerDialogId			providerDialogId
7	dialogId	Y		dialogId	Y
8	sessionId			sessionId
9	createdTimestamp			eventDate	Y
10	customerIdentifiers			customerIdentifiers
11	conversation			conversation
12	EngagementParameters			engagementParameters
13	channelId			businessAccountName
14	sessionParameters			initiatorParticipantId	Y

ParticipantEvent

API Version	/v1			/v1beta
Model Name	ParticipantEvent			ParticipantEvent
	Field	Mandatory	Comments	Field	Mandatory	Comments
1	eventType	Y		eventType	Y
2	engagementId	Y		engagementId	Y
3	tenantId	Y		accountId	Y
4	channelProviderId	Y		channelProviderId	Y
5	providerDialogId			providerDialogId
6	dialogId	Y		dialogId	Y
7	sessionId			sessionId
8	createdTimestamp			eventDate	Y
9	connectionId	Y		connectionId	Y
10	participantId			participantId
11	displayName			displayName
12	participantType			participantType
13	providerParticipantId			providerParticipantId
14				correlationId	Y
15				channelId

MessageEvent

API Version	/v1			/v1beta
Model Name	MessageEvent			MessageEvent
	Field	Mandatory	Comments	Field	Mandatory	Comments
1	eventType	Y		eventType	Y
2	correlationId			correlationId	Y
3	messageId	Y		messageId
4	tenantId	Y		accountId	Y
5	sessionId			sessionId
6	dialogId	Y		dialogId
7	engagementId	Y		engagementId
8	messageIndex	Y		messageIndex
9	status		Enum [ NONE, SENT, DELIVERED, READ, FAILED, DELETED]	status	Y	Enum [ NONE, SENT, DELIVERED, READ, FAILED, DELETED]
10	businessAccountName	Y		businessAccountName
11	channelProviderId	Y		channelProviderId	Y
12	channelId	Y		channelId	Y
13	providerDialogId			providerDialogId
14	providerSenderId			providerSenderId
15	recipientParticipants	Y	Array of objectParticipant	recipientParticipants		Array of objectParticipant
16	senderName	Y		senderParticipantName	Y
17	senderType			senderParticipantType	Y
18	providerMessageId			providerMessageId
19	body	Y	Object ofBodyElement	body	Y	Object ofBodyElement
20	fallbackText			fallbackText
21	header		Object ofMessageHeaders	headers		Object ofMessageHeaders
22	attachments		Array of objectAttachment	attachments		Array of object Attachment
23	customData			customData
24	contextParameters			engagementParameters
25	receivedTimestamp			receivedAt
26	lastUpdatedTimestamp			eventDate
27	parentMessageId			parentMessageId
28	providerParentMessageId			providerParentMessageId
29				senderParticipantId	Y
30				eventDate

BodyElement (No Change)

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

EngagementErrorEvent

API Version	/v1			/v1beta
Model Name	EngagementErrorEvent			EngagementErrorEvent
	Field	Mandatory	Comments	Field	Mandatory	Comments
1	eventType	Y		eventType	Y
2	type	Y		type	Y
3	title	Y		title	Y
4	detail			detail
5	engagementId			engagementId
6	dialogId			dialogId
7	sessionId			sessionId
8	providerDialogId			providerDialogId
9	channelProviderId	Y		channelProviderId	Y
10	channelId			channelId
11	tenantId			accountId
12	correlationId	Y		correlationId	Y
13	timestamp			eventDate	Y