API version

RTM pushes

This document contains a reference of pushes available in the LiveChat Customer 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 customer has seen an event, compare the event's created_at parameter with the customer's events_seen_up_to field.

Available pushes

Chatsincoming_chat chat_deactivated
Chat accesschat_transferred
Chat usersuser_added_to_chat user_removed_from_chat
Eventsincoming_event event_updatedincoming_rich_message_postback
Propertieschat_properties_updated chat_properties_deleted thread_properties_updated thread_properties_deleted event_properties_updated event_properties_deleted
Customerscustomer_updated customer_page_updated customer_side_storage_updated
Statuscustomer_disconnected
Otherincoming_typing_indicator incoming_multicast events_marked_as_seen incoming_greeting greeting_accepted greeting_canceled queue_position_updated
The general push format
Copied!
{
  "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.

Sample push payload
Copied!
{
  "requester_id": "b5657aff34dd32e198160d54666df9d8",
  "chat": {
    "id": "PJ0MRSHTDG",
    "users": [
      // array of "User" objects
    ],
    "properties": {
      // "Properties" object
    },
    "access": {
      // "Access" object
    },
    "thread": {
      // "Thread" object
    },
    "transferred_from": {
      "group_ids": [ 1 ],
      "agent_ids": [ "bbb67d600796e9f277e360e842418833" ]
    }
  }
}

chat_deactivated

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

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c" // optional
}
Push payload
FieldNotes
user_idMissing if a thread was closed by the router.

Chat access

chat_transferred

Informs that a chat was transferred to a different group or to an Agent.

Sample push payload
Copied!
{
  "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"
  }
}
Push payload
FieldNotes
thread_idPresent if the chat is active
transferred_toIDs of groups and Agents the chat has been assigned to
queuePresent if the chat is queued after the transfer

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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user": {
  // "User > Customer" or "User > Agent" object
  },
  "reason": "manual",
  "requester_id": "b5657aff34dd32e198160d54666df9d8"
}
Push payload
FieldNotes
thread_idPresent when a user was added to an active chat.
reasonWhy the user was added.
requester_idPresent if the user was added by an agent.

user_removed_from_chat

Informs that a user (Customer or Agent) was removed from a chat.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "bbb67d600796e9f277e360e842418833",
  "reason": "manual",
  "requester_id": "b5657aff34dd32e198160d54666df9d8"
}
Push payload
FieldNotes
thread_idPresent when a user was removed from an active chat.
reasonWhy the user was removed.
requester_idPresent if the user was removed by an agent.

Events

incoming_event

Informs about an incoming event sent to a chat.

Sample push payload
Copied!
{
  "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_updated

Informs that an event was updated.

Sample push payload
Copied!
{
  "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.

Sample push payload
Copied!
{
  "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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
  "0805e283233042b37f460ed8fbf22160": {
    "string_property": "Chat property value updated by Customer"
    },
  // ...
  }
}
Push payload
FieldNotes
propertiesNot 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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
    },
  // ...
}
Push payload
FieldNotes
propertiesNot 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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "properties": {
  "0805e283233042b37f460ed8fbf22160": {
    "string_property": "Thread property value updated by Customer"
    },
  // ...
  }
}
Push payload
FieldNotes
propertiesThis is not a full properties object. This push shows only the properties the have been recently updated.

thread_properties_deleted

Informs about those thread properties that were deleted.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
    },
  // ...
}
Push payload
FieldNotes
propertiesNot 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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
  "0805e283233042b37f460ed8fbf22160": {
    "string_property": "Event property value updated by Customer"
    }
  }
}
Push payload
FieldNotes
propertiesNot 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.

Sample push payload
Copied!
{
  "chat_id": "Q1GZ3FNAT9",
  "thread_id": "Q1GZ3FNAU9",
  "event_id": "Q1GZ3FNAU9_1",
  "properties": {
    "0805e283233042b37f460ed8fbf22160": ["string_property"]
    },
  // ...
}
Push payload
FieldNotes
propertiesThis is not a full properties object. This push shows only the properties that have been recently updated.

Customers

customer_updated

Informs that Customer's data was updated.

Sample push payload
Copied!
{
  "customer": {
  // "User > Customer" object
  }
}

customer_page_updated

Informs that a Customer changed the website - moved to another page of the website, for example by clicking on a link.

Sample push payload
Copied!
{
  "url": "https://livechatinc.com/pricing",
  "title": "pricing",
  "timestamp": 123456789
}

customer_side_storage_updated

Informs that a Customer updated the data stored on their side.

Sample push payload
Copied!
{
  "customer_side_storage": {
  "customer_visits": "1"
  }
}
Push payload
FieldNotes
customer_side_storageA map in the key : value format. Map content should be kept on the client side (e.g. in browsers local storages) and sent via login.

Status

customer_disconnected

Informs that a Customer was disconnected. The payload contains the reason of Customer's disconnection.

Sample push payload
Copied!
{
  "reason": "misdirected_connection",
  "data": {
  // optional
  "region": "fra"
  }
}
Push payload
FieldNotes
reason
Possible reasons
TypeNotes
access_token_expiredAccess token lifetime has elapsed.
connection_timeoutHas not received ping from the client for some time, or it's been too long since the connection was authorized.
customer_bannedCustomer has been banned.
customer_temporarily_blocked*Customer tried reconnecting too many times after the too_many_connections error had occurred.
inactivity_timeoutCustomer didn't chat or change the page in the past 30 minutes.
internal_errorInternal, unexpected error; reconnecting is advised
license_not_foundThe license with the specified ID doesn't exist.
license_expiredThe license has expired.
misdirected_connection **Customer connected to a server in the wrong region.
product_version_changedThe product version has changed.
service_temporarily_unavailableThe Customer Chat API should be available again soon; reconnecting is advised
too_many_connectionsCustomer has reached the maximum number of connections.
too_many_unauthorized_connectionsThe maximum number of unauthorized connections has been reached.
unsupported_versionConnecting to an unsupported version of the Customer Chat API.

*) The customer_temporarily_blocked reason can also return the correct timeout in an optional data object. With this piece of information, client is able to figure out how much time a customer should wait before attempting to reconnect again.

**) The misdirected_connection reason can also return the correct region in an optional data object. With this piece of information, 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.

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

incoming_multicast

Informs about messages sent via the multicast method or by the system.

Sample push payload
Copied!
{
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "content": {
  "example": {
    "nested": "json"
  }
  }
}
Push payload
FieldRequiredNotes
author_idNoPresent only if the push was generated by the Multicast method and not sent from the server.
contentYes

events_marked_as_seen

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

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

incoming_greeting

Informs about an incoming greeting.

Sample push payload
Copied!
{
  "action": "incoming_greeting",
  "type": "push",
  "payload": {
  "id": 7,
  "unique_id": "Q10O0N5B5D",
  "displayed_first_time": true,
  "addon": "email",
  "event": {
    // "Event > Message" object
    // or
    // "Event > Rich message" object
  },
  "agent": {
    "name": "Agent Smith",
    "id": "b5657aff34dd32e198160d54666df9d8",
    "avatar": "https://example.com/image25.png",
    "job_title": "Support Agent",
    "is_bot": false
  }
  }
}
Push payload
FieldNotes
idID of the greeting configured within the license.
unique_idID of the greeting that was generated, sent, and cancelled.
eventGreeting event (Message or Rich message)
displayed_first_timetrue if the greeting was generated for the first time.
agentInfo about the Agent who sent the greeting.
addonAdditional greeting property

greeting_accepted

Informs about a greeting accepted by the Customer.

Sample push payload
Copied!
{
  "action": "greeting_accepted",
  "type": "push",
  "payload": {
  "unique_id": "Q40R0832IN"
  }
}
Push payload
FieldNotes
unique_idID of the greeting that was generated, sent, and accepted.

greeting_canceled

Informs about a greeting rejected by the Customer. Also, the push is sent when a new greeting automatically cancels the currently displayed one.

Sample push payload
Copied!
{
  "action": "greeting_canceled",
  "type": "push",
  "payload": {
    "unique_id": "Q10O0N5B5D"
  }
}
Push payload
FieldNotes
unique_idID of the greeting that was generated, sent, and rejected.

queue_position_updated

Informs about an updated position in the queue and about the wait time.

Sample push payload
Copied!
{
  "action": "queue_position_updated",
  "type": "push",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8",
    "queue": {
      "position": 42,
      "wait_time": 1337
    }
  }
}