Pushes

Pushes are generated primarily by RTM API actions, but also by Web API actions. They notify you when specific events occur and are delivered only over the WebSocket transport. You don’t need to register to receive them. Their Web API equivalents are webhooks.

Chats

`incoming_chat`

Indicates a chat coming with a new thread. The push payload contains the whole chat data structure. If the chat was started with initial events, the thread object contains them.

Sample push payload

{
  "requester_id": "b5657aff34dd32e198160d54666df9d8",
  "chat": {
    "id": "PJ0MRSHTDG",
    "users": [],
    "properties": {},
    "access": {},
    "thread": {},
    "transferred_from": {
      "group_ids": [1],
      "agent_ids": ["bbb67d600796e9f277e360e842418833"]
    }
  }
}

`chat_deactivated`

Indicates that a chat was deactivated by closing the currently open thread. Push payload

Field	Notes
`user_id`	Missing if a thread was closed by the router.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}

Chat access

`chat_transferred`

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

Field	Notes
`thread_id`	Present if the chat is active.
`transferred_to`	IDs of groups and agents the chat has been assigned to.
`queue`	Present if the chat is queued after the transfer.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "requester_id": "b5657aff34dd32e198160d54666df9d8",
  "transferred_to": {
    "group_ids": [1],
    "agent_ids": ["b5657aff34dd32e198160d54666df9d8"]
  },
  "queue": {
    "position": 42,
    "wait_time": 1337,
    "queued_at": "2019-12-09T12:01:18.909000Z"
  }
}

Chat users

`user_added_to_chat`

Indicates that a user (customer or agent) was added to a chat. This push can be emitted with user.present set to false when a user writes to a chat without joining it. Push payload

Field	Notes
`thread_id`	Present when a user was added to an active chat.
`reason`	Why the user was added.
`requester_id`	Present if the user was added by an agent.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user": {},
  "reason": "manual",
  "requester_id": "b5657aff34dd32e198160d54666df9d8"
}

`user_removed_from_chat`

Indicates that a user (customer or agent) was removed from a chat. Push payload

Field	Notes
`thread_id`	Present when a user was removed from an active chat.
`reason`	Why the user was removed.
`requester_id`	Present if the user was removed by an agent.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "bbb67d600796e9f277e360e842418833",
  "reason": "manual",
  "requester_id": "b5657aff34dd32e198160d54666df9d8"
}

Events

`incoming_event_preview`

Indicates an incoming event preview sent to a chat.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event": {
    "created_at": "2019-12-05T07:27:08.820000Z",
    "type": "message",
    "text": "Preview of a longer response...",
    "author_id": "b5657aff-34dd-32e1-98160d54666df9d8",
    "custom_id": "31-0C-1C-07-DB-16"
  }
}

`incoming_event`

Indicates an incoming event sent to a chat.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event": {
    "id": "Q20163UAHO_2",
    "created_at": "2019-12-05T07:27:08.820000Z",
    "recipients": "all",
    "type": "message",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string value"
      }
    },
    "text": "Hello",
    "author_id": "b5657aff-34dd-32e1-98160d54666df9d8"
  }
}

`event_deleted`

Indicates that an event was deleted.

Sample push payload

{
  "chat_id": "123-123-123-123",
  "thread_id": "E2WDHA8A",
  "event_id": "E2WDHA8A_4"
}

`event_updated`

Indicates that an event was updated.

Sample push payload

{
  "chat_id": "123-123-123-123",
  "thread_id": "E2WDHA8A",
  "event": {}
}

`incoming_rich_message_postback`

Indicates an incoming rich message postback. The push payload contains the info on the postback itself, as well as the chat it was sent in.

Sample push payload

{
  "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
  "postback": {
    "id": "action_yes",
    "toggled": true,
    "button_type": "url",
    "button_value": "https://www.example.com",
    "ecommerce": {
      "product_id": "12345",
      "option_id": "red-xl",
      "quantity": 1
    }
  }
}

Properties

`chat_properties_updated`

Indicates which chat properties were updated. Push payload

Field	Notes
`properties`	Not a full `properties` object. Contains only the properties that were recently updated.

Sample push payload

{
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Chat property value updated by Customer"
    }
  }
}

`chat_properties_deleted`

Indicates which chat properties were deleted. Push payload

Field	Notes
`properties`	Not a full `properties` object. Contains only the properties that were recently deleted.

Sample push payload

{
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
  }
}

`thread_properties_updated`

Indicates which thread properties were updated. Push payload

Field	Notes
`properties`	Not a full `properties` object. Contains only the properties that were recently updated.

Sample push payload

{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Thread property value updated by Customer"
    }
  }
}

`thread_properties_deleted`

Indicates which thread properties were deleted. Push payload

Field	Notes
`properties`	Not a full `properties` object. Contains only the properties that were recently deleted.

Sample push payload

{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
  }
}

`event_properties_updated`

Indicates which event properties were updated. Push payload

Field	Notes
`properties`	Not a full `properties` object. Contains only the properties that were recently updated.

Sample push payload

{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": {
      "string_property": "Event property value updated by Customer"
    }
  }
}

`event_properties_deleted`

Indicates which event properties were deleted. Push payload

Field	Notes
`properties`	Not a full `properties` object. Contains only the properties that were recently deleted.

Sample push payload

{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
  }
}

Customers

`customer_updated`

Indicates that customer data changed. The push payload contains the updated fields.

Sample push payload

{}

`customer_side_storage_updated`

Indicates that a customer updated the data stored on their side. Push payload

Field	Notes
`customer_side_storage`	A map in the `"key": "value"` format. Keep its content on the client side (e.g. in browser local storage) and pass it via `login`.

Sample push payload

{
  "customer_side_storage": {
    "customer_visits": "1"
  }
}

Status

`customer_disconnected`

Indicates that a customer was disconnected. The payload contains the reason for disconnection. Push payload

Field	Notes
`reason`	The disconnection reason.

Possible reasons

Type	Notes	Suggested behavior
`access_token_revoked`	Access token has been revoked.	Reconnect and generate a new access token.
`access_token_expired`	Access token lifetime has elapsed.	Reconnect and generate a new access token.
`connection_evicted`	The Customer Chat API should be available again soon.	Reconnect.
`connection_timeout`	Has not received `ping` from the client for some time, or it’s been too long since the connection was authorized.	Reconnect.
`internal_error`	Internal error.	Reconnect.
`license_not_found`	The license with the specified ID doesn’t exist.	Don’t reconnect.
`license_expired`	The license has expired.	Don’t reconnect.
`misdirected_connection`**	Customer connected to a server in the wrong region.	Don’t reconnect.
`unsupported_version`	Connecting to an unsupported version of the Customer Chat API.	Don’t reconnect.
`service_temporarily_unavailable`	The Customer Chat API should be available again soon.	Reconnect.
`too_many_connections`	Customer has reached the maximum number of connections.	Don’t reconnect.
`too_many_unauthorized_connections`	The maximum number of unauthorized connections has been reached.	Reconnect.
`logged_out_remotely`	Logged out by the server.	Don’t reconnect.

* The customer_temporarily_blocked reason can also return a timeout in an optional data object, indicating how long the customer should wait before attempting to reconnect. ** The misdirected_connection reason can also return the correct region in an optional data object, indicating where the client should connect.

Sample push payload

{
  "reason": "misdirected_connection",
  "data": {
    "region": "fra"
  }
}

`groups_status_updated`

Indicates that the statuses of groups the customer has access to were updated. The push payload includes only the updated fields. Possible statuses: online, online_for_queue, offline.

Sample push payload

{
  "groups": [
    {
      "id": 0,
      "status": "offline"
    }
  ]
}

Other

`incoming_thinking_indicator`

Indicates that one of the chat users (an agent or a bot agent) is currently preparing a response. The message hasn’t been sent yet.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "author_id": "d17cd570-11a9-45c0-45c0-1b020b7586dc",
  "sent_at": "2025-07-16T12:34:56.909000Z",
  "title": "Thinking...",
  "description": "Fetching data from the Billing API...",
  "custom_id": "31-0C-1C-07-DB-16"
}

`incoming_typing_indicator`

Indicates that one of the chat users (an agent or a bot agent) is currently typing a message. The message hasn’t been sent yet.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "typing_indicator": {
    "author_id": "d17cd570-11a9-45c0-45c0-1b020b7586dc",
    "recipients": "all",
    "timestamp": 1574245378,
    "is_typing": true
  }
}

`incoming_multicast`

Indicates messages sent via the multicast method or by the system. Push payload

Field	Required	Notes
`author_id`	No	Present only if the push was generated by the multicast method and not sent from the server.
`content`	Yes

Sample push payload

{
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "content": {
    "example": {
      "nested": "json"
    }
  }
}

`events_marked_as_seen`

Indicates that a user has seen events up to a specific time.

Sample push payload

{
  "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "chat_id": "PJ0MRSHTDG",
  "seen_up_to": "2017-10-12T15:19:21.010200Z"
}

`incoming_greeting`

Indicates an incoming greeting. Push payload

Field	Notes
`id`	ID of the greeting configured within the license.
`unique_id`	ID of the specific greeting instance that was generated, sent, and cancelled.
`event`	The greeting event (message or rich message).
`displayed_first_time`	If set to `true`: the greeting was generated for the first time.
`agent`	Info about the agent who sent the greeting.
`addon`	Additional greeting property.
`subtype`	Currently, `announcement` is the only greeting subtype.
`is_exit_intent`	If set to `true`: the greeting was created as an exit intent greeting.

Sample push payload

{
  "id": 7,
  "unique_id": "Q10O0N5B5D",
  "displayed_first_time": true,
  "addon": "email",
  "subtype": "announcement",
  "is_exit_intent": false,
  "event": {},
  "agent": {
    "name": "Agent Smith",
    "id": "b5657aff34dd32e198160d54666df9d8",
    "avatar": "https://example.com/image25.png",
    "job_title": "Support Agent",
    "is_bot": false
  }
}

`greeting_accepted`

Indicates a greeting accepted by the customer. Push payload

Field	Notes
`unique_id`	ID of the greeting that was generated, sent, and accepted.

Sample push payload

{
  "unique_id": "Q40R0832IN"
}

`greeting_canceled`

Indicates a greeting rejected by the customer. Also sent when a new greeting automatically cancels the currently displayed one. Push payload

Field	Notes
`unique_id`	ID of the greeting that was generated, sent, and rejected.

Sample push payload

{
  "unique_id": "Q10O0N5B5D"
}

`incoming_welcome_message`

Indicates an incoming welcome message. Push payload

Field	Notes
`id`	The welcome message ID.
`event`	The welcome message event object.

Sample push payload

{
  "id": "540eb790-17c1-47f9-9e2c-dca5a0960ab5",
  "event": {
    "created_at": "2019-12-05T07:27:08.820000Z",
    "type": "message",
    "text": "Welcome! How can I help you today?",
    "author_id": "b5657aff34dd32e198160d54666df9d8"
  }
}

`queue_position_updated`

Indicates an updated position in the queue and the estimated wait time.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "queue": {
    "position": 42,
    "wait_time": 1337
  }
}

Overview

Methods

Chats

`incoming_chat`

`chat_deactivated`

Chat access

`chat_transferred`

Chat users

`user_added_to_chat`

`user_removed_from_chat`

Events

`incoming_event_preview`

`incoming_event`

`event_deleted`

`event_updated`

`incoming_rich_message_postback`

Properties

`chat_properties_updated`

`chat_properties_deleted`

`thread_properties_updated`

`thread_properties_deleted`

`event_properties_updated`

`event_properties_deleted`

Customers

`customer_updated`

`customer_side_storage_updated`

Status

`customer_disconnected`

`groups_status_updated`

Other

`incoming_thinking_indicator`

`incoming_typing_indicator`

`incoming_multicast`

`events_marked_as_seen`

`incoming_greeting`

`greeting_accepted`

`greeting_canceled`

`incoming_welcome_message`

`queue_position_updated`

​Chats

​incoming_chat

​chat_deactivated

​Chat access

​chat_transferred

​Chat users

​user_added_to_chat

​user_removed_from_chat

​Events

​incoming_event_preview

​incoming_event

​event_deleted

​event_updated

​incoming_rich_message_postback

​Properties

​chat_properties_updated

​chat_properties_deleted

​thread_properties_updated

​thread_properties_deleted

​event_properties_updated

​event_properties_deleted

​Customers

​customer_updated

​customer_side_storage_updated

​Status

​customer_disconnected

​groups_status_updated

​Other

​incoming_thinking_indicator

​incoming_typing_indicator

​incoming_multicast

​events_marked_as_seen

​incoming_greeting

​greeting_accepted

​greeting_canceled

​incoming_welcome_message

​queue_position_updated

Chats

`incoming_chat`

`chat_deactivated`

Chat access

`chat_transferred`

Chat users

`user_added_to_chat`

`user_removed_from_chat`

Events

`incoming_event_preview`

`incoming_event`

`event_deleted`

`event_updated`

`incoming_rich_message_postback`

Properties

`chat_properties_updated`

`chat_properties_deleted`

`thread_properties_updated`

`thread_properties_deleted`

`event_properties_updated`

`event_properties_deleted`

Customers

`customer_updated`

`customer_side_storage_updated`

Status

`customer_disconnected`

`groups_status_updated`

Other

`incoming_thinking_indicator`

`incoming_typing_indicator`

`incoming_multicast`

`events_marked_as_seen`

`incoming_greeting`

`greeting_accepted`

`greeting_canceled`

`incoming_welcome_message`

`queue_position_updated`