RTM pushes
This document contains a reference of pushes available in the LiveChat Agent Chat API. Similarly to webhooks, pushes notify you when specific events occur. They're usually generated as result of RTM API actions, but it's also possible to receive them in result of Web API actions.
Introduction
Here's what you need to know about pushes:
- They are generated primarily by RTM API actions, but also by Web API actions.
- They notify you when specific events occur.
- Can be delivered only in the websocket transport.
- You don't need to register pushes to receive them.
- Their equivalents in Web API are webhooks. Pushes and webhooks have similar payloads.
- There are no retries for pushes. To determine if a user has seen an event, compare the event's
created_atparameter with the user'sevents_seen_up_tofield.
Available pushes
{
"version": "<api_version>",
"request_id": "<request_id>", // optional, applies only to the requester
"action": "<action>",
"type": "push",
"payload": {
// optional payload
}
}
Chats
incoming_chat
Informs about 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.
{
"requester_id": "smith@example.com",
"chat": {
"id": "PJ0MRSHTDG",
"users": [
// array of "User" objects
],
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
// ...
},
"thread": {
// "Thread" object
},
},
"transferred_from": {
"group_ids": [ 1 ],
"agent_ids": [ "agent@example.com" ]
}
}
chat_deactivated
Informs that a chat was deactivated by closing the currently open thread.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
}
Push payload
| Field | Notes |
|---|---|
user_id | Missing if a thread was closed by the router. |
chat_deleted
Informs that a chat was deleted.
{
"chat_id": "PJ0MRSHTDG"
}
thread_deleted
Informs that a thread was deleted.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8"
}
threads_deleted
Informs that several threads from a specific date range or with the same tag were deleted.
{
"date_from": "2017-10-12T15:19:21.010200Z",
"date_to": "2019-10-12T15:19:21.010200Z",
"tag": "bug_report"
}
Chat access
chat_access_updated
Informs about the update of a user's access to a particular chat. It contains the updated access data structure.
{
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [0, 1]
}
}
Push payload
| Field | Notes |
|---|---|
id | Chat ID |
access | The updated chat access data structure |
chat_transferred
Informs that a chat was transferred to a different group or to an agent.
{
"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"
}
}
Push 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 * | Informs why the chat was transferred. |
queue | Present if the chat is queued after the transfer. |
*)
Possible reasons: manual, inactive, assigned, unassigned, other.
Chat users
user_added_to_chat
Informs that a user (Customer or Agent) was added to a chat.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user": {
// "User > Customer" or "User > Agent" object
},
"reason": "manual",
"requester_id": "smith@example.com"
}
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. |
user_removed_from_chat
Informs that a user (Customer or Agent) was removed from a chat.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"user_id": "agent@example.com",
"reason": "manual",
"requester_id": "smith@example.com"
}
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. |
Events
incoming_event
Informs about an incoming event sent to a chat.
{
"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
Informs that an event was updated.
{
"chat_id": "123-123-123-123",
"thread_id": "E2WDHA8A",
"event": {
// "Event" object
}
}
incoming_rich_message_postback
Informs about an incoming rich message postback. The push payload contains the info on the postback itself, as well as the chat it was sent in.
{
"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
Informs about those chat properties that were updated.
{
"chat_id": "PJ0MRSHTDG",
"properties": {
"rating": {
"score": 1,
"comment": "Well done!"
}
// ...
}
}
Push payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This push shows only the properties that have been recently updated. |
chat_properties_deleted
Informs about those chat properties that were deleted.
{
"chat_id": "PJ0MRSHTDG",
"properties": {
"rating": ["score", "comment"]
},
// ...
}
Push payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This push shows only the properties that have been recently updated. |
thread_properties_updated
Informs about those thread properties that were updated.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"rating": {
"score": 1,
"comment": "Well done!"
}
// ...
}
}
Push payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This push shows only the properties that have been recently updated. |
thread_properties_deleted
Informs about those thread properties that were deleted.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"properties": {
"rating": ["score", "comment"]
},
// ...
}
}
Push payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This push shows only the properties that have been recently updated. |
event_properties_updated
Informs about those event properties that were updated.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "2_E2WDHA8A",
"properties": {
"rating": {
"score": 1,
"comment": "Well done!"
}
}
}
Push payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This push shows only the properties that have been recently updated. |
event_properties_deleted
Informs about those event properties that were deleted.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"event_id": "2_E2WDHA8A",
"properties": {
"rating": ["score", "comment"]
},
// ...
}
Push payload
| Field | Notes |
|---|---|
properties | This is not a full properties object. This push shows only the properties that have been recently updated. |
Thread tags
thread_tagged
Informs that a chat thread was tagged.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
}
thread_untagged
Informs that a chat thread was untagged.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"tag": "bug_report"
}
Customers
incoming_customers
Informs about customers the agent should be aware of. It's sent after login.
{
"customer_monitoring_level": "invited",
"customers": [{
// "Customer" user object
}]
}
incoming_customer
Informs that a new or returning customer is available to the agent. It's sent when:
- a new customer registers.
- a customer, who previously left the tracked website, returns.
- an already followed customer, who was temporarily unavailable to the agent, becomes available again (for example, the customer was transferred between groups).
{
// "Customer" user object
}
customer_updated
Informs that customer's data changed. The push payload contains the updated fields.
{
"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
Informs that a Customer moved to another page of the website.
{
"customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"visit_id": 42,
"opened_at": "2017-10-12T15:19:21.010200Z",
"url": "https://www.livechat.com/",
"title": "LiveChat - Homepage"
}
customer_banned
Informs that a Customer was banned for a specified number of days.
{
"customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"ban": {
"days": 5
}
}
customer_transferred
Informs that a customer is no longer available to the agent.
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"transferred_to": {
"group_ids": [1]
},
"followed": true
}
customer_left
Informs that a Customer left the tracked website.
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"left_at": "2017-10-12T15:19:21.010200Z"
}
Status
routing_status_set
Informs that an Agent's or Bot Agent's status was changed.
{
"agent_id": "smith@example.com",
"status": "accepting_chats"
}
agent_disconnected
Informs that an Agent was disconnected. The payload contains the reason of Customer's disconnection.
{
"reason": "misdirected_request",
"data": {
// optional
"region": "fra"
}
}
Possible reasons
Based on the received reason we suggest a different reaction.
| 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 that's replaced by a newly established one, and the new connection exceeded the limit of possible connections. | Don't reconnect. |
access_token_expired | Access token lifetime has elapsed. | Reconnect and generate a new access token. |
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_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. | 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. |
role_permissions_changed | Role permissions have been changed. | Reconnect. |
*)
Also, misdirected_connection returns the correct region value in the optional data object.
With this piece of information, the client is able to figure out where it should be connected.
Configuration
agent_created
Informs that a new agent account was created. The payload contains the full state of the agent data structure, including empty fields.
{
"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
Informs that an agent's account was approved and is now active.
{
"id": "smith@example.com"
}
agent_updated
Informs that an agent's configuration changed. Contains only the updated properties.
{
"id": "smith@example.com",
"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"
},
{
"day": "friday",
"enabled": true,
"start": "07:30",
"end": "21:30"
}
]
}
}
agent_suspended
Informs that an agent's account was suspended.
{
"id": "smith@example.com"
}
agent_unsuspended
Informs that an agent's account was unsuspended.
{
"id": "smith@example.com"
}
agent_deleted
Informs that an agent's account was deleted.
{
"id": "smith@example.com"
}
auto_accesses_updated
Informs that auto access rules were modified. The payload contains an array of all changes done as result of adding, updating, or deleting auto access rule. The resulting payload can contain multiple objects depending on the action:
- for the added auto access rule, the payload contains the complete state of the auto access rule data structure, including empty fields.
- for the updated auto access rule, the payload contains only the updated properties.
- for the deleted auto access rule, the payload confirms the deletion.
[
{
"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"
}
]
[
{
"id": "b1cd0bfea640f671694110c6ae34356f",
"description": "Auto access updated",
"next_id": "dc70916fdc9d02ea0bcdee5b2fa64717",
"status": "updated"
},
{
"id": "dc70916fdc9d02ea0bcdee5b2fa64717",
"next_id": "",
"status": "updated"
}
]
[
{
"id": "b1cd0bfea640f671694110c6ae34356f",
"next_id": "",
"status": "updated"
},
{
"id": "dc70916fdc9d02ea0bcdee5b2fa64717",
"status": "deleted"
}
]
bot_created
Informs that a new bot was added. The payload contains the full state of the bot data structure, including empty fields.
{
"id": "5c9871d5372c824cbf22d860a707a578",
"name": "Bot Name",
"default_group_priority": "first",
"groups": [
{
"id": 0,
"priority": "normal"
}
],
"owner_client_id": "asXdesldiAJSq9padj"
}
bot_updated
Informs that a bot's configuration changed. Contains only the updated properties.
{
"id": "5c9871d5372c824cbf22d860a707a578",
"name": "New Bot Name",
}
bot_deleted
Informs that a bot was deleted.
{
"id": "5c9871d5372c824cbf22d860a707a578"
}
group_created
Informs that a group was created within a license. The payload contains the full state of the group data structure, including empty fields.
{
"id": 42,
"name": "Sales",
"language_code": "en",
"agent_priorities": {
"agent@example.com": "normal",
"other_agent@example.com": "first"
}
}
group_deleted
Informs that a group was deleted within a license.
{
"id": 42
}
group_updated
Informs that a group was updated within a license. The push payload only includes the updated fields.
{
"id": 42,
"name": "Sales"
}
tag_created
Informs that a tag was created within a license. The payload contains the full state of the tag data structure, including empty fields.
{
"name": "docs_feedback",
"group_ids": [ 0, 42 ],
"created_at": "2019-12-09T12:01:18.909000Z",
"author_id": "smith@example.com"
}
tag_deleted
Informs that a tag was deleted within a license.
{
"name": "docs_feedback"
}
tag_updated
Informs that a tag was updated within a license.
{
"name": "docs_feedback",
"group_ids": [ 0, 42 ]
}
groups_status_updated
Informs that the statuses of groups that the agent has access to were updated. The push payload only includes the updated fields.
Possible statuses: accepting_chats, not_accepting_chats, offline.
{
"groups": [
{
"id": 0,
"status": "offline"
}
]
}
license_properties_updated
Informs about those license properties that were updated.
{
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
}
group_properties_updated
Informs about those group properties that were updated.
{
"group_id": 1,
"properties": {
"0805e283233042b37f460ed8fbf22160": {
"string_property": "string value"
}
}
}
Other
incoming_typing_indicator
Informs that one of the chat users is currently typing a message. The message hasn't been sent yet. The push payload contains the typing indicator object.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"typing_indicator": {
"author_id": "smith@example.com",
"visibility": "all",
"timestamp": 1574245378,
"is_typing": true
}
}
incoming_sneak_peek
Informs about the message a Customer is currently typing. The push payload contains the sneak peek object.
{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"sneak_peek": {
"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"text": "Hello",
"timestamp": 1574245378
}
}
events_marked_as_seen
Informs that a user has seen events up to a specific time.
{
"user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
"chat_id": "PJ0MRSHTDG",
"seen_up_to": "2017-10-12T15:19:21.010200Z"
}
incoming_multicast
Informs about messages sent via the multicast method or by the system.
{
"author_id": "smith@example.com",
"content": {
"example": {
"nested": "json"
}
},
"type": "type1"
}
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 | |
type | No |
chat_unfollowed
Informs that a chat has been unfollowed. Useful in multiple connection scenarios, where one app/integration needs to know that another one unfollowed the chat.
{
"chat_id": "PJ0MRSHTDG"
}
queue_positions_updated
New positions and wait times for queued chats.
[{
"chat_id": "PJ0MRSHTDG",
"thread_id": "K600PKZON8",
"queue": {
"position": 42,
"wait_time": 1337
}
}, {
"chat_id": "PJ0VRSATDS",
"thread_id": "K60QPKSON9",
"queue": {
"position": 43,
"wait_time": 1373
}
}]
customer_unfollowed
Informs that a customer was unfollowed. Useful in multiple connection scenarios, where one app/integration needs to know that another one unfollowed the customer.
{
"id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}