API version

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.1, 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

Chatsincoming_chat_thread thread_closed
Chat accessaccess_granted access_revoked access_set
Chat userschat_user_added chat_user_removed
Eventsincoming_event event_updated incoming_rich_message_postback
Propertieschat_properties_updated chat_properties_deleted chat_thread_properties_deleted chat_thread_properties_updated event_properties_updated event_properties_deleted
Thread tagschat_thread_tagged chat_thread_untagged
Statusagent_status_changed agent_deleted
Customerscustomer_created
Otherevents_marked_as_seen

Chats

incoming_chat_thread

Informs about a new thread coming in the chat. The webhook payload contains not only the new thread, but the whole chat data structure. If the chat was started with some initial events, the thread object contains them.

Specifics
Actionincoming_chat_thread
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
chatChat data structure
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "incoming_chat_thread",
  "payload": {
    "chat": {
        "id": "PJ0MRSHTDG",
        "users": [
            // array of "User" objects
        ],
        "properties": {
            "source": {
                "type": "facebook"
            },
            ...
        },
        "thread": {
            // "Thread" object
          }
      }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

thread_closed

Informs that a thread was closed.

Specifics
Actionthread_closed
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
user_idMissing if a thread was closed by the router.
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "thread_closed",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

Chat access

access_granted

Informs that new, single access to a resource was granted. The existing access isn't overwritten.

Specifics
Actionaccess_granted
Push equivalent inAgent Chat API
Webhook payload
FieldNotes
accessThe entities that were granted access to the specified resource
resourceResource type
idResource id
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "access_granted",
  "payload": {
    "resource": "chat",
    "id": "PJ0MRSHTDG",
    "access": {
      "group_ids": [1] // Agents from group 1 were granted access to the chat with id PJ0MRSHTDG
    }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

access_revoked

Informs that access to a certain resource was revoked.

Specifics
Actionaccess_revoked
Push equivalent inAgent Chat API
Webhook payload
FieldNotes
accessThe entities that lost access to the specified resource
resourceResource type
idResource Id
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "access_revoked",
  "payload": {
    "resource": "chat",
    "id": "PJ0MRSHTDG",
    "access": {
      "group_ids": [1] // Agents from group 1 lost access to the chat with id PJ0MRSHTDG
    }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

access_set

Informs that new, single access to a resource was set. The existing access is overwritten.

Specifics
Actionaccess_set
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
accessThe entities that were given access to the specified resource
resourceResource type
idResource id
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "access_set",
  "payload": {
    "resource": "chat",
    "id": "PJ0MRSHTDG",
    "access": {
      "group_ids": [1] // Agents from group 1 were granted given to the chat with id PJ0MRSHTDG
    }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

Chat users

chat_user_added

Informs that a user (Customer or Agent) was added to a chat.

Specifics
Actionchat_user_added
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
user_typePossible values: agent, customer
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "chat_user_added",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "user": {
        // "User > Customer" or "User > Agent" object
          },
      "user_type": "agent"
    },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

chat_user_removed

Informs that a user (Customer or Agent) was removed from a chat.

Specifics
Actionchat_user_removed
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
user_typePossible values: agent, customer
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "chat_user_removed",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "user_id": "agent1@example.com",
      "user_type": "agent"
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

Events

incoming_event

Informs about an incoming event sent to a chat.

Specifics
Actionincoming_event
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "incoming_event",
  "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
Actionevent_updated
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "event_updated",
  "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
Actionincoming_rich_message_postback
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "incoming_rich_message_postback",
  "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
Actionchat_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
propertiesNot 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",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "properties": {
        "rating": {
            "score": 1,
            "comment": "Very good, very good"
        }
      }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

chat_properties_deleted

Informs about those chat properties that were deleted.

Specifics
Actionchat_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
propertiesNot 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",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "properties": {
          "rating": ["score", "comment"]
        }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

chat_thread_properties_updated

Informs about those chat thread properties that were updated.

Specifics
Actionchat_thread_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
propertiesNot 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_thread_properties_updated",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "properties": {
        "rating": {
            "score": 1,
            "comment": "Very good, very good"
        }
      }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

chat_thread_properties_deleted

Informs about those chat thread properties that were deleted.

Specifics
Actionchat_thread_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
propertiesNot 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_thread_properties_deleted",
  "payload": {
      "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "properties": {
        "rating": ["score", "comment"]
          }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

event_properties_updated

Informs about those event properties that were updated.

Specifics
Actionevent_properties_updated
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
propertiesThis 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",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8",
    "event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
    "properties": {
      "rating": {
        "score": 1,
        "comment": "Very good, very good"
      }
    }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

event_properties_deleted

Informs about those event properties that were deleted.

Specifics
Actionevent_properties_deleted
Push equivalent inAgent Chat API Customer Chat API
Webhook payload
FieldNotes
propertiesThis 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",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "event_id": "0affb00a-82d6-4e07-ae61-56ba5c36f743",
      "properties": {
        "rating": ["score", "comment"]
        },
        // ...
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

Thread tags

chat_thread_tagged

Informs that a chat thread was tagged.

Specifics
Actionchat_thread_tagged
Push equivalent inAgent Chat API
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "chat_thread_tagged",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "tag": "bug_report"
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

chat_thread_untagged

Informs that a chat thread was untagged.

Specifics
Actionchat_thread_untagged
Push equivalent inAgent Chat API
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "chat_thread_untagged",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
      "thread_id": "K600PKZON8",
      "tag": "bug_report"
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

Status

agent_status_changed

Informs that an Agent's status changed.

Specifics
Actionagent_status_changed
Push equivalent inAgent Chat API
Webhook payload
FieldNotes
statusPossible values: accepting chats, not accepting chats, offline
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "agent_status_changed",
  "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
Actionagent_deleted
Push equivalent in-
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "agent_deleted",
  "payload": {
    "agent_id": "agent1@example.com"
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    }
  }
}

Customers

customer_created

Informs that a new Customer registered.

Specifics
Actioncustomer_created
Push equivalent inAgent Chat API
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "customer_created",
  "payload": {
    // "User > Customer" object
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "created_at": "2019-11-14T14:27:24.410018Z",
    "email": "customer1@example.com",
    "avatar": "https://example.com/avatars/1.jpg",
    "fields": {
        "some_key": "some_value"
    }
  },
  "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
Actionevents_marked_as_seen
Push equivalent inAgent Chat API Customer Chat API
Sample webhook
Copied!
{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "events_marked_as_seen",
  "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
    }
  }
}