Webhooks
This document contains a reference of available webhooks. Webhooks are helpful for building applications that execute particular behavior in response to various actions, allowing you to create automated flows.
If you still use webhooks v3.2, we encourgae you to migrate to the current stable version, v3.3. Keep in mind we introduced a significant change in the mechanism of webhook registration in v3.3 (registration per Client ID, not per license). Read more about it in the Changelog or in our webhook tutorial.
💡 Not what you're looking for? See webhook methods instead.
Available webhooks
Chats
incoming_chat
Informs about a chat coming with a new thread. The webhook payload contains the whole chat data structure. If the chat was started with some initial events, the thread object contains them.
Specifics
| Action | incoming_chat |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
chat | Chat data structure |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_chat",
"license_id": 104130623,
"payload": {
"chat": {
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"properties": {
// "Property" object
},
"thread": {
// "Thread" object
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
chat_deactivated
Informs that a chat was deactivated by closing the currently open thread.
Specifics
| Action | chat_deactivated |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
user_id | Missing if a thread was closed by the router. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_deactivated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Chat access
chat_access_granted
Informs that new, single access to a chat was granted. The existing access isn't overwritten.
Specifics
| Action | chat_access_granted |
| Push equivalent in | Agent Chat API |
Webhook payload
| Field | Notes |
|---|---|
id | Chat ID |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_access_granted",
"license_id": 104130623,
"payload": {
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
chat_access_revoked
Informs that access to a certain chat was revoked.
Specifics
| Action | chat_access_revoked |
| Push equivalent in | Agent Chat API |
Webhook payload
| Field | Notes |
|---|---|
id | Chat Id |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_access_revoked",
"license_id": 104130623,
"payload": {
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Chat users
user_added_to_chat
Informs that a user (Customer or Agent) was added to a chat.
Specifics
| Action | user_added_to_chat |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
user_type | Possible values: agent, customer |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "user_added_to_chat",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user": {
// "User > Customer" or "User > Agent" object
},
"reason": "manual",
"requester_id": "smith@example.com"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
user_removed_from_chat
Informs that a user (Customer or Agent) was removed from a chat.
Specifics
| Action | user_removed_from_chat |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
user_type | Possible values: agent, customer |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "user_removed_from_chat",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "agent@example.com",
"reason": "manual",
"requester_id": "smith@example.com"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Events
incoming_event
Informs about an incoming event sent to a chat.
Specifics
| Action | incoming_event |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_event",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event": {
// "Event" object
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
event_updated
Informs that an event was updated.
Specifics
| Action | event_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_updated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event": {
// "Event" object
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
incoming_rich_message_postback
Informs about an incoming rich message postback. The webhook payload contains the info on the postback itself, as well as the chat it was sent in.
Specifics
| Action | incoming_rich_message_postback |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "incoming_rich_message_postback",
"license_id": 104130623,
"payload": {
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"postback": {
"id": "action_yes",
"toggled": true
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Properties
chat_properties_updated
Informs about those chat properties that were updated.
Specifics
| Action | chat_properties_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_properties_updated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
chat_properties_deleted
Informs about those chat properties that were deleted.
Specifics
| Action | chat_properties_deleted |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "chat_properties_deleted",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
thread_properties_updated
Informs about those thread properties that were updated.
Specifics
| Action | thread_properties_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_properties_updated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
thread_properties_deleted
Informs about those thread properties that were deleted.
Specifics
| Action | thread_properties_deleted |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
properties | Not a full properties object. This push shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_properties_deleted",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
event_properties_updated
Informs about those event properties that were updated.
Specifics
| Action | event_properties_updated |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This webhook shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_properties_updated",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "property_value"
}
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
event_properties_deleted
Informs about those event properties that were deleted.
Specifics
| Action | event_properties_deleted |
| Push equivalent in | Agent Chat API Customer Chat API |
Webhook payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This webhook shows only the properties that have been recently updated. |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "event_properties_deleted",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
"properties": {
"0805e283233042b37f460ed8fbf22160": [
"string_property"
]
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Thread tags
thread_tagged
Informs that a thread was tagged.
Specifics
| Action | thread_tagged |
| Push equivalent in | Agent Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_tagged",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
thread_untagged
Informs that a thread was untagged.
Specifics
| Action | thread_untagged |
| Push equivalent in | Agent Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "thread_untagged",
"license_id": 104130623,
"payload": {
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Status
routing_status_set
Informs that an Agent's or Bot's status has changed.
Specifics
| Action | routing_status_set |
| Push equivalent in | Agent Chat API |
Webhook payload
| Field | Notes |
|---|---|
status | Possible values: accepting chats, not accepting chats, offline (for Bots only) |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "routing_status_set",
"license_id": 104130623,
"payload": {
"agent_id":"agent1@example.com",
"status": "accepting chats"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
agent_deleted
Informs that an Agent's account was deleted.
Specifics
| Action | agent_deleted |
| Push equivalent in | - |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "agent_deleted",
"license_id": 104130623,
"payload": {
"agent_id": "agent1@example.com"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Customers
customer_created
Informs that a new Customer registered.
Specifics
| Action | customer_created |
| Push equivalent in | Agent Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "customer_created",
"license_id": 104130623,
"payload": {
"customer": {
// "User > Customer" object
}
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}
Other
events_marked_as_seen
Informs that a user has seen events up to a specific time.
Specifics
| Action | events_marked_as_seen |
| Push equivalent in | Agent Chat API Customer Chat API |
Sample webhook
Copied!
{
"webhook_id": "<webhook_id>",
"secret_key": "<secret_key>",
"action": "events_marked_as_seen",
"license_id": 104130623,
"payload": {
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"chat_id": "PJ0MRSHTDG",
"seen_up_to": "2017-10-12T15:19:21.010200Z"
},
"additional_data": {
"chat_properties": { //optional
// chat properties
}
}
}