...

API version

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_at parameter with the user's events_seen_up_to field.

Available pushes

Chatsincoming_chat chat_deactivated chat_deleted thread_deleted threads_deleted
Chat accesschat_access_updated chat_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
Thread tagsthread_tagged thread_untagged
Customersincoming_customers incoming_customer customer_updated customer_page_updated customer_banned customer_transferred customer_left
Statusrouting_status_set agent_disconnected
Configurationagent_created agent_approved agent_updated agent_suspended agent_unsuspended agent_deleted auto_access_added auto_access_updated auto_access_deleted bot_created bot_updated bot_deleted group_created group_updated group_deleted
Otherevents_marked_as_seen incoming_sneak_peek incoming_typing_indicator incoming_multicast chat_unfollowed queue_positions_updated customer_unfollowed
general push format
Copied!
{
  "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.

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

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_deleted

Informs that a chat was deleted.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG"
}

thread_deleted

Informs that a thread was deleted.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8"
}

threads_deleted

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

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

Sample push payload
Copied!
{
  "id": "PJ0MRSHTDG",
  "access": {
    "group_ids": [0, 1]
  }
}
Push payload
FieldNotes
idChat ID
accessThe updated chat access data structure

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": "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
FieldNotes
thread_idPresent if the chat is active.
transferred_toIDs of the groups and agents the chat is assigned to after the transfer.
reason *Informs why the chat was transferred.
queuePresent 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user": {
  // "User > Customer" or "User > Agent" object
  },
  "reason": "manual",
  "requester_id": "smith@example.com"
}
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": "agent@example.com",
  "reason": "manual",
  "requester_id": "smith@example.com"
}
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",
    "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.

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": "PJ0MRSHTDG",
  "properties": {
  "rating": {
    "score": 1,
    "comment": "Well done!"
  }
  // ...
  }
}
Push payload
FieldNotes
propertiesThis 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "properties": {
    "rating": ["score", "comment"]
    },
    // ...
  }
Push payload
FieldNotes
propertiesThis 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "properties": {
  "rating": {
    "score": 1,
    "comment": "Well done!"
  }
  // ...
  }
}
Push payload
FieldNotes
propertiesThis 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "properties": {
    "rating": ["score", "comment"]
    },
    // ...
  }
}
Push payload
FieldNotes
propertiesThis 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "2_E2WDHA8A",
  "properties": {
  "rating": {
    "score": 1,
    "comment": "Well done!"
  }
  }
}
Push payload
FieldNotes
propertiesThis 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "2_E2WDHA8A",
  "properties": {
    "rating": ["score", "comment"]
    },
    // ...
  }
Push payload
FieldNotes
propertiesThis 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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "tag": "bug_report"
}

thread_untagged

Informs that a chat thread was untagged.

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

Sample push payload
Copied!
{
  "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).
Sample push payload
Copied!
{
  // "Customer" user object
}

customer_updated

Informs that customer's data changed. The push payload contains the updated fields.

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

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

Sample push payload
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "ban": {
  "days": 5
  }
}

customer_transferred

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

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

customer_left

Informs that a Customer left the tracked website.

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

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

Sample push payload
Copied!
{
  "reason": "misdirected_request",
  "data": {
  // optional
  "region": "fra"
  }
}
Possible reasons

Based on the received reason we suggest a different reaction.

TypeNotesSuggested behavior
agent_disconnected_by_serverAgent has been disconnected by the server.Don't reconnect.
access_token_revokedAgent access token has been revoked.Don't reconnect.
connection_evictedSent 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_expiredAccess token lifetime has elapsed.Reconnect and generate a new access token.
connection_timeoutHas not received ping from the client for some time, or it's been too long since the connection was authorized.Reconnect.
internal_errorInternal error.Reconnect.
license_expiredLicense has expired.Don't reconnect.
license_not_foundLicense 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_versionConnecting to an unsupported version of the Agent API.Don't reconnect.
product_version_changedProduct version has been changed.Don't reconnect.
too_many_connectionsAgent reached the max. number of connections.Don't reconnect.
too_many_unauthorized_connectionsAgent 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.

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.

Sample push payload
Copied!
{
  "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": {
    "monday": {
      "start": "08:30",
      "end": "12:30"
    }
  }
}

agent_approved

Informs that an agent's account was approved and is now active.

Sample push payload
Copied!
{
  "id": "smith@example.com"
}

agent_updated

Informs that an agent's configuration changed. Contains only the updated properties.

Sample push payload
Copied!
{
  "id": "smith@example.com",
  "work_scheduler": {
    "monday": {
      "start": "08:30",
      "end": "12:30"
    },
    "friday": {
      "start": "07:30",
      "end": "21:30"
    }
  }
}

agent_suspended

Informs that an agent's account was suspended.

Sample push payload
Copied!
{
  "id": "smith@example.com"
}

agent_unsuspended

Informs that an agent's account was unsuspended.

Sample push payload
Copied!
{
  "id": "smith@example.com"
}

agent_deleted

Informs that an agent's account was deleted.

Sample push payload
Copied!
{
  "id": "smith@example.com"
}

auto_access_added

Informs that a new auto access rule was added. The payload contains the full state of the auto access rule data structure, including empty fields.

Sample push payload
Copied!
{
  "id": "pqi8oasdjahuakndw9nsad9na",
  "description": "Chats on livechat.com from United States",
  "access": {
    "groups": [ 1 ]
  },
  "conditions": {
    "domain": {
      "values": [
        {
          "value": "livechat.com",
          "exact_match": true
        }
      ]
    },
    "geolocation": {
      "values": [
        {
          "country": "United States",
          "country_code": "US"
        }
      ]
    }
  },
  "next_id": "1faad6f5f1d6e8fdf27e8af9839783b7"
}

auto_access_updated

Informs that the configration of an auto access rule changed. Contains only the updated properties.

Sample push payload
Copied!
{
  "id": "pqi8oasdjahuakndw9nsad9na",
  "access": {
    groups: [ 0, 42 ]
  }
}

auto_access_deleted

Informs that an auto access rule was deleted.

Sample push payload
Copied!
{
  "id": "pqi8oasdjahuakndw9nsad9na"
}

bot_created

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

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

Sample push payload
Copied!
{
  "id": "5c9871d5372c824cbf22d860a707a578",
  "name": "New Bot Name",
}

bot_deleted

Informs that a bot was deleted.

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

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

Sample push payload
Copied!
{
  "id": 42
}

group_updated

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

Sample push payload
Copied!
{
  "id": 42,
  "name": "Sales"
}

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": "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.

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

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

Sample push payload
Copied!
{
  "author_id": "smith@example.com",
  "content": {
  "example": {
    "nested": "json"
  }
  },
  "type": "type1"
}
Push payload
FieldRequiredNotes
author_idNoPresent only if the push was generated by the Multicast method and not sent from the server.
contentYes
typeNo

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.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG"
}

queue_positions_updated

New positions and wait times for queued chats.

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

Sample push payload
Copied!
{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
}

...