Pushes - Text Documentation

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. Pushes and webhooks have similar payloads. There are no retries for pushes. General push format

{
  "version": "<api_version>",
  "request_id": "<request_id>",
  "action": "<action>",
  "type": "push",
  "payload": {}
}

Available pushes


Chats	`incoming_chat` `chat_deactivated` `chat_deleted` `thread_deleted` `threads_deleted`
Chat access	`chat_access_updated` `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_updated` `thread_properties_deleted` `event_properties_updated` `event_properties_deleted`
Thread tags	`thread_tagged` `thread_untagged`
Customers	`incoming_customers` `incoming_customer` `customer_updated` `customer_page_updated` `customer_banned` `customer_transferred` `customer_left`
Status	`routing_status_set` `agent_disconnected`
Configuration	`agent_created` `agent_approved` `agent_updated` `agent_suspended` `agent_unsuspended` `agent_deleted` `auto_accesses_updated` `bot_created` `bot_updated` `bot_deleted` `group_created` `group_updated` `group_deleted` `tag_created` `tag_deleted` `tag_updated` `groups_status_updated`
Other	`events_marked_as_seen` `incoming_sneak_peek` `incoming_typing_indicator` `incoming_multicast` `chat_unfollowed` `queue_positions_updated`

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 some initial events, the thread object contains them.

Sample push payload

{
  "requester_id": "smith@example.com",
  "chat": {
    "id": "PJ0MRSHTDG",
    "users": [],
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string value"
      }
    },
    "thread": {}
  },
  "transferred_from": {
    "group_ids": [1],
    "agent_ids": ["agent@example.com"]
  }
}

`chat_deactivated`

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

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_deleted`

Indicates that a chat was deleted.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG"
}

`thread_deleted`

Indicates that a thread was deleted.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8"
}

`threads_deleted`

Indicates that several threads from a specific date range or with the same tag were deleted.

Sample push payload

{
  "date_from": "2017-10-12T15:19:21.010200Z",
  "date_to": "2019-10-12T15:19:21.010200Z",
  "tag": "bug_report"
}

Chat access

`chat_access_updated`

Indicates an update of a user’s access to a particular chat.

Field	Notes
`id`	Chat ID.
`access`	The updated chat access data structure.

Sample push payload

{
  "id": "PJ0MRSHTDG",
  "access": {
    "group_ids": [0, 1]
  }
}

`chat_transferred`

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

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. Possible values: `manual`, `inactive`, `assigned`, `unassigned`, `other`.
`queue`	Present if the chat is queued after the transfer.

Sample push 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": "2019-12-09T12:01:18.909000Z"
  }
}

Chat users

`user_added_to_chat`

Indicates that a user (customer or agent) was added to a chat.

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": "smith@example.com"
}

`user_removed_from_chat`

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

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": "agent@example.com",
  "reason": "manual",
  "requester_id": "smith@example.com"
}

Events

`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",
    "visibility": "all",
    "type": "message",
    "properties": {
      "0805e283233042b37f460ed8fbf22160": {
        "string_property": "string value"
      }
    },
    "text": "Hello",
    "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}

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

Properties

`chat_properties_updated`

Indicates which chat properties were updated.

Field	Notes
`properties`	Not a full `properties` object — only recently updated properties.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "properties": {
    "rating": {
      "score": 1,
      "comment": "Well done!"
    }
  }
}

`chat_properties_deleted`

Indicates which chat properties were deleted.

Field	Notes
`properties`	Not a full `properties` object — only recently deleted properties.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "properties": {
    "rating": ["score", "comment"]
  }
}

`thread_properties_updated`

Indicates which thread properties were updated.

Field	Notes
`properties`	Not a full `properties` object — only recently updated properties.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "properties": {
    "rating": {
      "score": 1,
      "comment": "Well done!"
    }
  }
}

`thread_properties_deleted`

Indicates which thread properties were deleted.

Field	Notes
`properties`	Not a full `properties` object — only recently deleted properties.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "properties": {
    "rating": ["score", "comment"]
  }
}

`event_properties_updated`

Indicates which event properties were updated.

Field	Notes
`properties`	Not a full `properties` object — only recently updated properties.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "2_E2WDHA8A",
  "properties": {
    "rating": {
      "score": 1,
      "comment": "Well done!"
    }
  }
}

`event_properties_deleted`

Indicates which event properties were deleted.

Field	Notes
`properties`	Not a full `properties` object — only recently deleted properties.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "2_E2WDHA8A",
  "properties": {
    "rating": ["score", "comment"]
  }
}

Thread tags

`thread_tagged`

Indicates that a chat thread was tagged.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "tag": "bug_report"
}

`thread_untagged`

Indicates that a chat thread was untagged.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "tag": "bug_report"
}

Customers

`incoming_customers`

Indicates customers the agent should be aware of. Sent after login.

Sample push payload

{
  "customer_monitoring_level": "invited",
  "customers": []
}

`incoming_customer`

Indicates that a new or returning customer is available to the agent. Sent when:

a new customer registers
a customer who previously left the tracked website returns
a followed customer who was temporarily unavailable becomes available again (e.g., after being transferred between groups)

Sample push payload

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "type": "customer"
}

`customer_updated`

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

Sample push payload

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "name": "Thomas Anderson",
  "email": "t.anderson@example.com",
  "avatar": "https://example.com/avatars/1.jpg",
  "type": "customer",
  "session_fields": [
    {
      "custom_key": "custom_value"
    },
    {
      "another_custom_key": "another_custom_value"
    }
  ]
}

`customer_page_updated`

Indicates that a customer moved to another page of the website.

Sample push payload

{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "visit_id": 42,
  "opened_at": "2017-10-12T15:19:21.010200Z",
  "url": "https://www.text.com/",
  "title": "Text - Homepage"
}

`customer_banned`

Indicates that a customer was banned for a specified number of days.

Sample push payload

{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "ban": {
    "days": 5
  }
}

`customer_transferred`

Indicates that a customer is no longer available to the agent.

Sample push payload

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "transferred_to": {
    "group_ids": [1]
  },
  "followed": true
}

`customer_left`

Indicates that a customer left the tracked website.

Sample push payload

{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "left_at": "2017-10-12T15:19:21.010200Z"
}

Status

`routing_status_set`

Indicates that an agent’s or bot agent’s status was changed.

Sample push payload

{
  "agent_id": "smith@example.com",
  "status": "accepting_chats"
}

`agent_disconnected`

Indicates that an agent was disconnected. The payload contains the reason for the disconnection.

Type	Notes	Suggested behavior
`agent_disconnected_by_server`	Agent has been disconnected by the server.	Don’t reconnect.
`agent_logged_out_remotely`	Agent has been logged out remotely.	Don’t reconnect.
`access_token_revoked`	Agent access token has been revoked.	Don’t reconnect.
`connection_evicted`	Sent to the connection replaced by a newly established one that exceeded the connection limit.	Don’t reconnect.
`access_token_expired`	Access token lifetime has elapsed.	Reconnect and generate a new access token.
`connection_timeout`	No ping received from the client, or too long since the connection was authorized.	Reconnect.
`internal_error`	Internal error.	Reconnect.
`license_expired`	License has expired.	Don’t reconnect.
`license_not_found`	License with the specified ID doesn’t exist.	Don’t reconnect.
`misdirected_connection`	Agent connected to the server in the wrong region. Also returns the correct `region` in the optional `data` object.	Don’t reconnect.
`unsupported_version`	Connecting to an unsupported version of the agent API.	Don’t reconnect.
`too_many_connections`	Agent reached the max. number of connections.	Don’t reconnect.
`too_many_unauthorized_connections`	Agent reached the max. number of unauthorized connections.	Reconnect.

Sample push payload

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

Configuration

`agent_created`

Indicates that a new agent account was created. The payload contains the full state of the agent data structure, including empty fields.

Sample push payload

{
  "id": "smith@example.com",
  "name": "Agent Smith",
  "role": "viceowner",
  "awaiting_approval": false,
  "groups": [
    {
      "id": 5,
      "priority": "first"
    },
    {
      "id": 2,
      "priority": "last"
    },
    {
      "id": 1,
      "priority": "normal"
    }
  ],
  "notifications": ["new_visitor", "new_goal", "visitor_is_typing"],
  "email_subscriptions": ["weekly_summary"],
  "work_scheduler": {
    "timezone": "Europe/Warsaw",
    "schedule": [
      {
        "day": "monday",
        "enabled": true,
        "start": "08:30",
        "end": "12:30"
      },
      {
        "day": "monday",
        "enabled": true,
        "start": "13:30",
        "end": "16:30"
      }
    ]
  }
}

`agent_approved`

Indicates that an agent’s account was approved and is now active.

Sample push payload

{
  "id": "smith@example.com"
}

`agent_updated`

Indicates that an agent’s configuration changed. Contains only the updated properties.

Sample push payload

{
  "id": "smith@example.com",
  "work_scheduler": {
    "timezone": "Europe/Warsaw",
    "schedule": [
      {
        "day": "monday",
        "enabled": true,
        "start": "08:30",
        "end": "12:30"
      },
      {
        "day": "friday",
        "enabled": true,
        "start": "07:30",
        "end": "21:30"
      }
    ]
  }
}

`agent_suspended`

Indicates that an agent’s account was suspended.

Sample push payload

{
  "id": "smith@example.com"
}

`agent_unsuspended`

Indicates that an agent’s account was unsuspended.

Sample push payload

{
  "id": "smith@example.com"
}

`agent_deleted`

Indicates that an agent’s account was deleted.

Sample push payload

{
  "id": "smith@example.com"
}

`auto_accesses_updated`

Indicates that auto access rules were modified. The payload contains an array of all changes resulting from adding, updating, or deleting an auto access rule.

For an added auto access rule: the payload contains the complete state of the rule data structure, including empty fields.
For an updated auto access rule: the payload contains only the updated properties.
For a deleted auto access rule: the payload confirms the deletion.

Sample push payload (rule added)

[
  {
    "id": "dc70916fdc9d02ea0bcdee5b2fa64717",
    "next_id": "b1cd0bfea640f671694110c6ae34356f",
    "status": "updated"
  },
  {
    "id": "b1cd0bfea640f671694110c6ae34356f",
    "description": "",
    "access": {
      "groups": [0]
    },
    "conditions": {
      "url": {
        "values": [
          {
            "value": "https://www.auto-access.test",
            "exact_match": false
          }
        ]
      },
      "domain": {
        "values": [
          {
            "value": "https://www.auto-access.test",
            "exact_match": true
          }
        ]
      },
      "geolocation": {
        "values": [
          {
            "country": "United States",
            "country_code": "US",
            "region": "California",
            "city": "Mountain View"
          }
        ]
      }
    },
    "next_id": "",
    "status": "added"
  }
]

Sample push payload (rule updated)

[
  {
    "id": "b1cd0bfea640f671694110c6ae34356f",
    "description": "Auto access updated",
    "next_id": "dc70916fdc9d02ea0bcdee5b2fa64717",
    "status": "updated"
  },
  {
    "id": "dc70916fdc9d02ea0bcdee5b2fa64717",
    "next_id": "",
    "status": "updated"
  }
]

Sample push payload (rule deleted)

[
  {
    "id": "b1cd0bfea640f671694110c6ae34356f",
    "next_id": "",
    "status": "updated"
  },
  {
    "id": "dc70916fdc9d02ea0bcdee5b2fa64717",
    "status": "deleted"
  }
]

`bot_created`

Indicates that a new bot was added. The payload contains the full state of the bot data structure, including empty fields.

Sample push payload

{
  "id": "5c9871d5372c824cbf22d860a707a578",
  "name": "Bot Name",
  "default_group_priority": "first",
  "groups": [
    {
      "id": 0,
      "priority": "normal"
    }
  ],
  "owner_client_id": "asXdesldiAJSq9padj"
}

`bot_updated`

Indicates that a bot’s configuration changed. Contains only the updated properties.

Sample push payload

{
  "id": "5c9871d5372c824cbf22d860a707a578",
  "name": "New Bot Name"
}

`bot_deleted`

Indicates that a bot was deleted.

Sample push payload

{
  "id": "5c9871d5372c824cbf22d860a707a578"
}

`group_created`

Indicates that a group was created within a license. The payload contains the full state of the group data structure, including empty fields.

Sample push payload

{
  "id": 42,
  "name": "Sales",
  "language_code": "en",
  "agent_priorities": {
    "agent@example.com": "normal",
    "other_agent@example.com": "first"
  }
}

`group_deleted`

Indicates that a group was deleted within a license.

Sample push payload

{
  "id": 42
}

`group_updated`

Indicates that a group was updated within a license. The push payload only includes the updated fields.

Sample push payload

{
  "id": 42,
  "name": "Sales"
}

`tag_created`

Indicates that a tag was created within a license. The payload contains the full state of the tag data structure, including empty fields.

Sample push payload

{
  "name": "docs_feedback",
  "group_ids": [0, 42],
  "created_at": "2019-12-09T12:01:18.909000Z",
  "author_id": "smith@example.com"
}

`tag_deleted`

Indicates that a tag was deleted within a license.

Sample push payload

{
  "name": "docs_feedback"
}

`tag_updated`

Indicates that a tag was updated within a license.

Sample push payload

{
  "name": "docs_feedback",
  "group_ids": [0, 42]
}

`groups_status_updated`

Indicates that the statuses of groups the agent has access to were updated. The push payload only includes the updated fields. Possible statuses: accepting_chats, not_accepting_chats, offline.

Sample push payload

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

Other

`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_sneak_peek`

Indicates the message a customer is currently typing.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "sneak_peek": {
    "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "text": "Hello",
    "timestamp": 1574245378
  }
}

`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": "smith@example.com",
    "visibility": "all",
    "timestamp": 1574245378,
    "is_typing": true
  }
}

`incoming_multicast`

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

Field	Notes
`author_id`	Present only if the push was generated by the multicast method, not sent from the server.
`content`	The message content.
`type`	Optional multicast message type.

Sample push payload

{
  "author_id": "smith@example.com",
  "content": {
    "example": {
      "nested": "json"
    }
  },
  "type": "type1"
}

`chat_unfollowed`

Indicates that a chat has been unfollowed. Useful in multiple connection scenarios, where one app or integration needs to know that another unfollowed the chat.

Sample push payload

{
  "chat_id": "PJ0MRSHTDG"
}

`queue_positions_updated`

New positions and wait times for queued chats.

Sample push payload

[
  {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8",
    "queue": {
      "position": 42,
      "wait_time": 1337
    }
  },
  {
    "chat_id": "PJ0VRSATDS",
    "thread_id": "K60QPKSON9",
    "queue": {
      "position": 43,
      "wait_time": 1373
    }
  }
]

​Available pushes

​Chats

​incoming_chat

​chat_deactivated

​chat_deleted

​thread_deleted

​threads_deleted

​Chat access

​chat_access_updated

​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_updated

​thread_properties_deleted

​event_properties_updated

​event_properties_deleted

​Thread tags

​thread_tagged

​thread_untagged

​Customers

​incoming_customers

​incoming_customer

​customer_updated

​customer_page_updated

​customer_banned

​customer_transferred

​customer_left

​Status

​routing_status_set

​agent_disconnected

​Configuration

​agent_created

​agent_approved

​agent_updated

​agent_suspended

​agent_unsuspended

​agent_deleted

​auto_accesses_updated

​bot_created

​bot_updated

​bot_deleted

​group_created

​group_deleted

​group_updated

​tag_created

​tag_deleted

​tag_updated

​groups_status_updated

​Other

​events_marked_as_seen

​incoming_sneak_peek

​incoming_typing_indicator

​incoming_multicast

​chat_unfollowed

​queue_positions_updated

Available pushes

Chats

`incoming_chat`

`chat_deactivated`

`chat_deleted`

`thread_deleted`

`threads_deleted`

Chat access

`chat_access_updated`

`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_updated`

`thread_properties_deleted`

`event_properties_updated`

`event_properties_deleted`

Thread tags

`thread_tagged`

`thread_untagged`

Customers

`incoming_customers`

`incoming_customer`

`customer_updated`

`customer_page_updated`

`customer_banned`

`customer_transferred`

`customer_left`

Status

`routing_status_set`

`agent_disconnected`

Configuration

`agent_created`

`agent_approved`

`agent_updated`

`agent_suspended`

`agent_unsuspended`

`agent_deleted`

`auto_accesses_updated`

`bot_created`

`bot_updated`

`bot_deleted`

`group_created`

`group_deleted`

`group_updated`

`tag_created`

`tag_deleted`

`tag_updated`

`groups_status_updated`

Other

`events_marked_as_seen`

`incoming_sneak_peek`

`incoming_typing_indicator`

`incoming_multicast`

`chat_unfollowed`

`queue_positions_updated`