Webhooks
Webhooks are automated notifications sent between applications when specific events occur, enabling real-time communication by transmitting data through HTTP requests.
Conversations webhooks provide instant access to conversation details and the latest message information, allowing you to manage customer inquiries efficiently. They support real-time integrations to automate workflows for message routing, escalation, and analytics, enhancing operational reporting with comprehensive conversation and message-level metadata.
With these webhooks, you can receive notifications for incoming messages and conversational events through the Subscriptions Management.
On our web interface, go to Subscriptions Management → Create subscription. Choose the Customer engagement option in the Channel menu, and select the events you want to subscribe to.
Additionally, you can use the Subscriptions Management API endpoints (opens in a new tab) to create the wanted subscriptions.
Check the sections below for more information about the events.
Supported events
The webhook currently supports a range of event types that allow you to stay informed about key activities in real time. The supported events are:
- Messaging
- Inbound Message Received (MO message)
- Outbound Message Sent (MT message)
- Message Updated
- Message Deleted
- Conversation lifecycle
- Conversation Created
- Conversation Assignment Changed
- Conversation Priority Changed
- Conversation Status Changed
- Conversation Queue Changed
- Conversation Form Changed
- Conversation Form Field Changed
- Conversation SLA Policy Changed
- Conversation Customer Changed
- Conversation Summary Changed
- Conversation Topic Changed
- Conversation Tag Added
- Conversation Tag Removed
- Agent
- Agent Status Changed
Event structure
An event is represented as a multilevel JSON object sent to client endpoints.
Root JSON element
The root of the payload contains three key event fields:
type: Defines the type of event being delivered.payload: Contains the event-specific data.timestamp: Date and time of the event.
Webhook integrators can filter and process incoming events based on the type field to handle only the relevant ones.
| JSON field | Type | Description | Supported values |
|---|---|---|---|
type | Enumeration | Event type value | INBOUND_MESSAGEOUTBOUND_MESSAGEINBOUND_MESSAGE_UPDATEDCONVERSATION_DELETEDCONVERSATION_CREATEDCONVERSATION_STATUS_UPDATEDCONVERSATION_ASSIGNMENT_UPDATEDCONVERSATION_FORM_UPDATEDCONVERSATION_QUEUE_UPDATEDCONVERSATION_TAG_ADDEDCONVERSATION_TAG_REMOVEDCONVERSATION_NOTE_ADDEDCONVERSATION_NOTE_UPDATEDCONVERSATION_NOTE_REMOVEDCONVERSATION_PRIORITY_UPDATEDCONVERSATION_CUSTOMER_UPDATEDCONVERSATION_TOPIC_UPDATEDCONVERSATION_SUMMARY_UPDATEDCONVERSATION_FORM_FIELD_UPDATEDCONVERSATION_SLA_POLICY_UPDATEDCONVERSATION_AGENT_STATUS_CHANGED |
payload | Nested object | Event payload | See the Payload structure. |
timestamp | Timestamp | Event timestamp | Timestamp in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format. |
Example
{
"type": "CONVERSATION_CREATED",
"payload": { ... },
"timestamp": "2023-06-20T16:44:24.572+00:00"
}Payload structure
When a webhook is triggered, it sends a payload containing key data about the event. In this case, the payload consists of two main event categories that provide the essential information needed to process the event effectively. These elements are:
- Agent events: Events related to agent activity, such as availability status.
- Conversation lifecycle events: Events that track the various stages of a conversation, including when it starts, updates, or ends.
Each of these elements plays a specific role in ensuring that the receiving system has all the context it needs.
Agent events payload
This event structure applies to the CONVERSATION_AGENT_STATUS_CHANGED event.
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Unique agent ID. | UUID v4 value. |
userId | String | Unique encrypted user ID. | |
email | String | Agent email address. | |
role | Enumeration | Agent role. | AGENTSUPERVISORBOT |
status | Nested object | Agent status details. | See below. |
invoker | Nested object | Invoker (the entity that made the change). | See below. |
Status
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Unique status ID. | UUID v4 value. |
name | String | Status name. | Read more about agent statuses. |
group | Enumeration | Status group. | ACTIVEBUSYINVISIBLEAWAY |
Conversation events payload
Conversation events generally follow a uniform structure. All events share a set of standard fields that provide core conversation data, such as ID, status, and timestamp. Depending on the event type, additional fields may be included to provide more context or data.
In other words, all conversation events share a common base structure. Some event types build on this by including additional fields relevant to their specific function. Keep in mind that not every field listed in the table appears in all events.
Refer to the table below for more details about the Conversation event types.
| JSON field | Type | Event type availability | Description | Supported values |
|---|---|---|---|---|
id | String | All events. | Unique conversation ID. | UUID v4 value. |
status | Enumeration | All events. | Conversation status. | OPENWAITINGSOLVEDPENDING (available only in certain cases)CLOSED |
queue | Nested object | All events. | Conversation queue data. | See below. |
priority | Enumeration | All events. | Conversation priority. | LOWNORMALHIGHURGENT |
channel | Enumeration | All events. | Conversation channel. | See the list of supported Conversations channels. |
direction | Enumeration | All events. | Conversation direction. | INBOUNDOUTBOUND |
assignee | Nested object | All events. | Conversation assignee data. | See below. |
customer | Nested object | All events. | Conversation customer data. | See below. |
form | Nested object | All events. | Conversation form data. | See below. |
topic | String | All events. | Conversation topic. | |
summary | String | All events. | Conversation summary. | |
timestamp | Timestamp | All events. | Event timestamp. Note that the same timestamp is also part of root structure. | Timestamp in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format. |
invoker | Nested object | All events. | Invoker (the entity that made the change). | See below. |
tags | Nested object | All events. | List of all associated conversation tags. | See below. |
lastMessage | Nested object | Only available in:CONVERSATION_CREATEDCONVERSATION_STATUS_UPDATEDCONVERSATION_ASSIGNMENT_UPDATEDCONVERSATION_FORM_UPDATEDCONVERSATION_QUEUE_UPDATEDCONVERSATION_TAG_ADDEDCONVERSATION_TAG_REMOVEDCONVERSATION_NOTE_ADDEDCONVERSATION_NOTE_UPDATEDCONVERSATION_NOTE_REMOVEDCONVERSATION_PRIORITY_UPDATEDCONVERSATION_CUSTOMER_UPDATEDCONVERSATION_TOPIC_UPDATEDCONVERSATION_SUMMARY_UPDATEDCONVERSATION_FORM_FIELD_UPDATEDCONVERSATION_SLA_POLICY_UPDATED | Last message info that can be used for additional conversation information fetching. | See below. |
message | Nested object | Only available in:INBOUND_MESSAGEOUTBOUND_MESSAGECONVERSATION_MESSAGE_UPDATEDCONVERSATION_DELETED | Full message data. | See below. |
sentiment | Number | Only available in the CONVERSATION_STATUS_UPDATED event type when the status is CLOSED. | Final conversation sentiment (after the conversation is closed). | -1.0 to 1.0 |
formFields | List of nested objects | Only available in the CONVERSATION_STATUS_UPDATED event type when the status is CLOSED. | List of final conversation form fields with their respective values (after the conversation is closed). | See below. |
field | Nested object | Only available in the CONVERSATION_FORM_FIELD_UPDATED event type. | Contains field name and value. | See below. |
note | Nested object | Only available in:CONVERSATION_NOTE_ADDEDCONVERSATION_NOTE_UPDATEDCONVERSATION_NOTE_DELETED | Conversation note data. | See below. |
policy | Nested object | Only available in the CONVERSATION_SLA_POLICY_UPDATED event type. | Conversation SLA policy data. | See below. |
addedTag | Nested object | Only available in the CONVERSATION_TAG_ADDED event type. | Data about the recently added tag. | See below. |
removedTag | Nested object | Only available in the CONVERSATION_TAG_REMOVED event type. | Data about the recently removed tag. | See below. |
socialContext | Nested object | Only available in the INBOUND_MESSAGE event type. | Contains social media context (sent only for Facebook Posts and Instagram Posts). | See below. |
Payload elements
Refer to the following tables for details about different payload elements.
Assignee
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Agent ID. | UUID v4 value. |
name | String | Agent name. | |
email | String | Agent email address. | |
role | Enumeration | Agent role. | AGENTSUPERVISORBOT |
Customer
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Customer ID. | UUID v4 value. |
name | String | Customer name. | |
personId | Number | Associated People Person ID. |
Form
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Form ID. | UUID v4 value. |
name | String | Form name. |
Form fields
List of fields (see below).
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Field ID. | UUID v4 value. |
name | String | Field name. | |
value | String | Field value. |
Note
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Note ID. | UUID v4 value. |
type | Enumeration | Note type. | INTERNAL, JIRA_COMMENT, ATTACHMENT |
content | Object | Note content. |
Policy
| JSON field | Type | Description | Supported values |
|---|---|---|---|
policyId | String | SLA policy ID. | UUID v4 value. |
policyName | String | SLA policy name. | |
severityId | String | SLA severity ID. | UUID v4 value. |
severityName | String | SLA severity name. |
Tags
List of tags (see below).
Tag, Added Tag, Removed Tag
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Tag ID. | UUID v4 value. |
name | String | Tag name. |
Queue
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Queue ID. | UUID v4 value. |
name | String | Queue name. |
Last message
| JSON field | Type | Description | Supported values |
|---|---|---|---|
from | String | Message sender (who/what sent the message). | Ranges from alphanumeric to UUID v4 values, depending on the channel. |
to | String | Message destination (who/what received the message). | Ranges from alphanumeric to UUID v4 values, depending on the channel. |
direction | Enumeration | Message direction. | INBOUND, OUTBOUND |
channel | Enumeration | Last message channel. | Supported Conversations channels. |
Message
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Unique message ID. | UUID v4 value. |
messageId | String | Unique platform message ID. | Ranges from alphanumeric to UUID v4 values, depending on the channel. |
from | String | Message sender (who/what sent the message). | Ranges from alphanumeric to UUID v4 values, depending on the channel. |
to | String | Message destination (who/what received the message). | Ranges from alphanumeric to UUID v4 values, depending on the channel. |
channel | Enumeration | Last message channel. | Supported Conversations channels. |
conversationId | String | Unique ID of the conversation the message belongs to. | UUID v4 value. |
createdAt | Timestamp | Message creation timestamp. | Timestamp in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format. |
updatedAt | Timestamp | Message updated at timestamp. | Timestamp in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format. |
Social context
| JSON field | Type | Description | Supported values |
|---|---|---|---|
username | String | Social media username. |
General data shared in all payloads
Invoker
| JSON field | Type | Description | Supported values |
|---|---|---|---|
id | String | Invoker ID. | For the AGENT invoker type, the value is agentId. For the SYSTEM invoker type, the value is null. |
name | String | Invoker name. | For the AGENT invoker type, the value is agent name. For the SYSTEM invoker type, the value is null. |
type | Enumeration | Invoker type. | AGENT, SYSTEM |
Webhook examples
Review the following webhook examples to understand the structure and data involved. These examples will help clarify how the events are represented and how to handle them effectively in your integration.