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` `chat_deactivated`
Chat access	`chat_access_granted` `chat_access_revoked`
Chat users	`user_added_to_chat` `user_removed_from_chat`
Events	`incoming_event` `event_updated` `incoming_rich_message_postback`
Properties	`chat_properties_updated` `chat_properties_deleted` `thread_properties_deleted` `thread_properties_updated` `event_properties_updated` `event_properties_deleted`
Thread tags	`thread_tagged` `thread_untagged`
Status	`routing_status_set` `agent_deleted`
Customers	`customer_created`
Other	`events_marked_as_seen`


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


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


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


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


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


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


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


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


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

Webhooks.css-n33kgz{margin-top:8px;}.css-n33kgz > label{margin:6px 10px 5px 0;}

Webhooks