Detailed Description

Webhook callback

Overview

As part of configuring client applications, a webhook callback URL must be registered with ECE application. Once registered, messages from ECE application for an ongoing conversation will be posted to the registered webhook callback URL. This section explains the payload that will be posted to the webhook callback URL. Refer Asynchronous messaging for more details.
One or more messages will be posted in a single request. A maximum of 1000 messages can be posted in a single request.
For the messages to be posted onto the callback webhook URL:

The callback webhook URL must be in active state. Refer to the section Deactivation of webhook callback URL for more details.

Note: Callback webhook URL supports SSL or TLS. Refer 'SSL Configuration' section in 'ECE Installation Guide' for more details.

Since: 12.0 ES1

APIs

N/A

Authentication

Authentication is configured in admin console.

Request

Request headers

Name	Description	Allowed values	Default value
Authorization	Authentication mechanism used by callback API. Authentication mechanism needs to be configured in admin console. Value could be none, basic authentication or oAuth2 configuration	Authentication scheme	N/A
Content-Type	Media type send by server, value is configured in admin console.	`application/xml` or `application/json`	N/A

Request Body

The request body is mandatory. Request body can be either XML or JSON format.

Elements required in request body

Name	Description
id	ID of the message.
sender.type	Type of the sender of the message. Possible values are as below: user: if sender is user. system: if sender is system.
sender.user	Details of user who sent the message. This attribute will be sent only if sender.type is 'user'.
conversation.id	ID of the conversation of the message.
type.value	The type of the message being sent. Allowed values are below: text/plain - Text message from the agent. text/html - Html message from the agent. startTyping - Agent started typing a message. endTyping - Agent stopped typing a message. assigned - Agent assigned to the conversation. complete - Agent ended the conversation while customer was still in session. pagePush - Agent sent a link to end user. transfer - Agent transferred the chat to another agent/queue. uploadAttachment - Agent uploaded an attachment. acceptAttachment - Agent accepted the attachment. rejectAttachment - Agent rejected the attachment. Note: Messages of type 'startTyping' and 'endTyping' will be sent only if query parameter 'sendTypingNotification' was sent as 'yes' while starting the conversation.
timeStamp	Time when message was sent by agent.

Optional elements allowed in request body

Name

Description

content

Content to be sent.
This is sent when type.value is one of the below:

text/plain
text/html
assigned
transfer
complete

attachments.attachment

Attachment details while uploading or accepting or rejecting the attachment.
This is sent when type.value is one of the below:

uploadAttachment
acceptAttachment
rejectAttachment
text (in case of KB article with attachment)

Please refer Attachment specific information section for the representation of attachment.
Please refer Message type specific attributes section for supported attachment attributes based on type of the message.

Attachment specific information

Note: 'text' in Message Type column is applicable when attachment are sent along with KB article

Name	Description
id	ID of the attachment.
fileName	Name of the attachment.
contentType	Type of the attachment.
size	Size of the attachment in bytes.
messageText	Text sent with message.
contentUrl	URL from where attachment can be downloaded.

Message type specific attributes

Attributes are not supported for the below message types:

startTyping
endTyping

For the other message types, the supported attributes are below:

Message Type	Attribute Name	Description	Always provided
text/plain or text/html	content	Content of the message	Yes
	attachments.attachment.fileName	Name of the attachment file.	Only when KB article with attachment is sent
	attachments.attachment.size	Size of the attachment in bytes	Only when KB article with attachment is sent
	attachments.attachment.contentType	Type of the attachment	Only when KB article with attachment is sent
	attachments.attachment.contentUrl	URL to download attachment.	Only when KB article with attachment is sent
	attachments.attachment.messageText	System message text showing agent has sent an attachment.	Only when KB article with attachment is sent
assigned	user.name	Name of the agent to whom the activity is assigned.	Yes
	user.screenName	Screen name of the agent to whom the activity is assigned.	Yes
	content	System message text showing agent has picked the chat activity.	Yes
pagePush	url	URL to a page which agent wants to share with customer	Yes
transfer	transfer.type	Type of transfer. Allowed values are as below: queue: if transferred to queue. agent: if transferred to agent.	Yes
	transfer.user.name	Name of agent to whom activity is transferred	Only when transfer.type is 'agent'
	transfer.queue.name	Name of queue to which activity is transferred	Only when transfer.type is 'queue'
	transfer.queue.channels.chat.attachmentSettings.isEnabledForCustomer	Indicates whether attachment is allowed or not. This is applicable for upload and download. Allowed values are as below: true: attachments are allowed. false: attachments are not allowed.	Yes
	content	System message text showing agent has transferred the chat activity	Yes
uploadAttachment	attachments.attachment.id	ID of the attachment that is initiated	Yes
	attachments.attachment.fileName	Name of the attachment file.	Yes
	attachments.attachment.size	Size of the attachment in bytes	Yes
	attachments.attachment.contentType	Type of the attachment	Yes
	attachments.attachment.messageText	System message text showing agent has initiated chat attachment	Yes
acceptAttachment	attachments.attachment.id	ID of the attachment that is accepted	Yes
	attachments.attachment.contentUrl	URL to download attachment.	Yes
rejectAttachment	attachments.attachment.id	ID of the attachment that is rejected	Yes
complete	content	System message text showing agent has completed the chat activity	Yes

Request body XML schemas:

v19-schema-interaction-activity-Message

Supported API specific query parameters

None

Deactivation of webhook callback URL

A message posted to webhook callback URL is considered "failed" if any of the below conditions are true:

The response is not returned within 30 seconds.
The response code is not 2XX (where X is a digit).

If posting a message fails, the application reattempts to post the messages 3 times at intervals:

2 minutes after the first failure.
5 minutes after the second failure.
20 minutes after the third failure.

If posting the message fails in all 3 attempts, the application will:

Deactivate the failed webhook callback URL for the client application.
Terminate all conversations started from the client application.
Send notification to configured email address for client application.

Note: Once the webhook callback URL is deactivated, new conversations cannot be started by that client application. The administrator has to re-activate the webhook callback URL of the client application before new conversation can be started. Refer section 'Integration Using Chat Messaging APIs' in 'ECE Administrator’s Guide to Chat and Collaboration Resources' for more details.

Examples:

Example 1 - Conversation is assigned to an advisor
Example 2 - Agent sends mesage of type 'startTyping'
Example 3 - Agent sends mesage of type 'endTyping'
Example 4 - Agent sends message of type 'text/html'
Example 5 - Agent sends mesage of type 'uploadAttachment'
Example 6 - Agent sends mesage of type 'acceptAttachment'
Example 7 - Agent sends mesage of type 'rejectAttachment'
Example 8 - Agent transfers conversation to queue
Example 9 - Agent transfers conversation to user
Example 10 - Agent sends message of type 'pagePush'
Example 11 - Agent sends message of type 'text/html' having KB article with attachment
Example 12 - Agent completes the conversation