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. In order to receive webhooks, you need to register them first.

💡 Not what you're looking for? Try these instead:

Available webhooks


Chats	`incoming_chat` `chat_deactivated`
Chat access	`chat_access_granted` `chat_access_revoked` `chat_transferred`
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	`incoming_customer` `customer_session_fields_updated`
Other	`events_marked_as_seen`

Chats

`incoming_chat`

Indicates 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_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`chat_deactivated`

Indicates 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_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Chat access

`chat_access_granted`

Indicates 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_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`chat_access_revoked`

Indicates 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_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`chat_transferred`

Indicates that a chat was transferred to a different group or to an agent.

Specifics


Action	`chat_transferred`
Push equivalent in	`Agent Chat API`

Webhook payload

Field	Notes
`thread_id`	Present if the chat is active.
`transferred_to`	IDs of the groups and agents the chat is assigned to after the transfer.
`reason` *	Indicates why the chat was transferred.
`queue`	Present if the chat is queued after the transfer.

*) Possible reasons: manual, inactive, assigned, unassigned, other.

Sample webhook

Copied!

{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "chat_access_revoked",
  "license_id": 104130623,
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8",
    "requester_id": "jones@example.com",
    "reason": "manual",
    "transferred_to": {
      "group_ids": [ 19 ],
      "agent_ids": ["smith@example.com"],
    },
    "queue": {
      "position": 42,
      "wait_time": 1337,
      "queued_at_us": "2019-12-09T12:01:18.909000Z"
    }
  }
}

Chat users

`user_added_to_chat`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`user_removed_from_chat`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Events

`incoming_event`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`event_updated`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`incoming_rich_message_postback`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Properties

`chat_properties_updated`

Indicates 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_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`chat_properties_deleted`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`thread_properties_updated`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`thread_properties_deleted`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`event_properties_updated`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`event_properties_deleted`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Thread tags

`thread_tagged`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`thread_untagged`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Status

`routing_status_set`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`agent_deleted`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Customers

`incoming_customer`

Indicates that a new customer registered.

Specifics


Action	`incoming_customer`
Push equivalent in	`Agent Chat API`

Sample webhook

Copied!

{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "incoming_customer",
  "license_id": 104130623,
  "payload": {
    "customer": {
    // "User > Customer" object
    }
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

`customer_session_fields_updated`

Indicates that a chatting customer's session fields were updated. The webhook will be sent for each active chat the customer has.

Specifics


Action	`customer_session_fields_updated`

Sample webhook

Copied!

{
  "webhook_id": "<webhook_id>",
  "secret_key": "<secret_key>",
  "action": "customer_session_fields_updated",
  "license_id": 104130623,
  "payload": {
    "id": "5280e68c-9692-4212-4ba9-85f7d8af55cd",
    "active_chat": {
        "chat_id": "PJ0MRSHTDG",
        "thread_id": "K600PKZON8"
    },
    "session_fields": [
      {
        "key": "value"
      }
    ]
  },
  "additional_data": {
    "chat_properties": { //optional
        // chat properties
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Other

`events_marked_as_seen`

Indicates 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
    },
    "chat_presence_user_ids": [ //optional
      // User IDs
    ]
  }
}

Webhooks.css-1g0dr3m{margin-top:8px;}.css-1g0dr3m > label{margin:0 0 5px 0;}.css-1g0dr3m label + div{-webkit-box-pack:end;-webkit-justify-content:flex-end;-ms-flex-pack:end;justify-content:flex-end;}

Chats

incoming_chat

Specifics

Webhook payload

chat_deactivated

Specifics

Webhook payload

Chat access

chat_access_granted

Specifics

Webhook payload

chat_access_revoked

Specifics

Webhook payload

chat_transferred

Specifics

Webhook payload

Chat users

user_added_to_chat

Specifics

Webhook payload

user_removed_from_chat

Specifics

Webhook payload

Events

incoming_event

Specifics

event_updated

Specifics

incoming_rich_message_postback

Specifics

Properties

chat_properties_updated

Specifics

Webhook payload

chat_properties_deleted

Specifics

Webhook payload

thread_properties_updated

Specifics

Webhook payload

thread_properties_deleted

Specifics

Webhook payload

event_properties_updated

Specifics

Webhook payload

event_properties_deleted

Specifics

Webhook payload

Thread tags

thread_tagged

Specifics

thread_untagged

Specifics

Status

routing_status_set

Specifics

Webhook payload

agent_deleted

Specifics

Customers

incoming_customer

Specifics

customer_session_fields_updated

Specifics

Other

events_marked_as_seen

Specifics

Webhooks

`incoming_chat`

`chat_deactivated`

`chat_access_granted`

`chat_access_revoked`

`chat_transferred`

`user_added_to_chat`

`user_removed_from_chat`

`incoming_event`

`event_updated`

`incoming_rich_message_postback`

`chat_properties_updated`

`chat_properties_deleted`

`thread_properties_updated`

`thread_properties_deleted`

`event_properties_updated`

`event_properties_deleted`

`thread_tagged`

`thread_untagged`

`routing_status_set`

`agent_deleted`

`incoming_customer`

`customer_session_fields_updated`

`events_marked_as_seen`