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 access
chat_access_granted
Informs that new, single access to a chat was granted. The existing access isn't overwritten.
{
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1]
}
}
Push payload
| Field | Notes |
|---|---|
id | Chat ID |
chat_access_revoked
Informs that access to a certain chat was revoked.
{
"id": "PJ0MRSHTDG",
"access": {
"group_ids": [1]
}
}
Push payload
| Field | Notes |
|---|---|
id | Chat Id |
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.
This push can be emitted with user.present set to false when a user writes to a chat without joining it. You can achieve that via the Send Event method.
{
"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",
"recipients": "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. |
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. |
*)
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.
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",
"recipients": "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",
recipients: "all",
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"
}