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_thread thread_closed
Chat accessaccess_granted access_revoked access_set chat_transferred
Chat userschat_user_added chat_user_removed
Eventsincoming_event event_updatedincoming_rich_message_postback
Propertieschat_properties_updated chat_properties_deleted chat_thread_properties_updated chat_thread_properties_deleted event_properties_updated event_properties_deleted
Thread tagschat_thread_tagged chat_thread_untagged
Customerscustomer_visit_started customer_created customer_updated customer_page_updated customer_banned customer_visit_ended
Statusagent_updated agent_disconnected
Otherevents_marked_as_seen incoming_sneak_peek incoming_typing_indicator incoming_multicast
general push format
Copied!
{
  "request_id": "<request_id>", // optional, applies only to the requester
  "action": "<action>",
  "type": "push",
  "payload": {
    // optional payload
  }
}

Chats

incoming_chat_thread

Informs about a new thread coming in the chat. The push payload contains not only the new thread, but the whole chat data structure. If the chat was started with some initial events, the thread object contains them.

Sample push payload
Copied!
{
  "chat": {
    "id": "PJ0MRSHTDG",
    "users": [
      // array of "User" objects
    ],
    "properties": {
      "source": {
        "type": "facebook"
      }
      // ...
    },
    "thread": {
      // "Thread" object
    }
  }
}

thread_closed

Informs that a thread was closed.

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

access_granted

Informs that new, single access to a resource was granted. The existing access isn't overwritten.

Sample push payload
Copied!
{
  "resource": "chat",
  "id": "PJ0MRSHTDG",
  "access": {
    "group_ids": [1]
  }
}
Push payload
FieldNotes
resourceResource type
idResource id

access_revoked

Informs that access to a certain resource was revoked.

Sample push payload
Copied!
{
  "resource": "chat",
  "id": "PJ0MRSHTDG",
  "access": {
    "group_ids": [1]
  }
}
Push payload
FieldNotes
resourceResource type
idResource Id

access_set

Informs that new, single access to a resource was set. The existing access is overwritten.

Sample push payload
Copied!
{
  "resource": "chat",
  "id": "PJ0MRSHTDG",
  "access": {
    "group_ids": [1]
  }
}
Push payload
FieldNotes
resourceResource type
idResource Id

chat_transferred

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

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "requester_id": "cb531744-e6a4-4ded-b3eb-b3eb4ded4ded",
  "type": "agent",
  "ids": ["agent1@example.com"]
}
Push payload
FieldNotes
typeagent or group
idsgroup or agent IDs array

Chat users

chat_user_added

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
  },
  "user_type": "agent"
}
Push payload
FieldNotes
user_typePossible values: agent, customer
thread_idEmpty if a user was added to an inactive chat.

chat_user_removed

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

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "agent1@example.com",
  "user_type": "agent"
}
Push payload
FieldNotes
user_typePossible values: agent, customer
thread_idEmpty if a user was removed from an inactive chat.

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": {
                "value": "string value"
              }
          }
      },
      "text": "Hello",
      "author_id": "author@example.com"
  }
}

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": {
        "value": 1
      },
      "comment": {
        "value": "Very good, veeeery good"
      }
    }
    // ...
  }
}
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.

chat_thread_properties_updated

Informs about those chat thread properties that were updated.

Sample push payload
Copied!
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "properties": {
    "rating": {
      "value": {
        "value": 1
      },
      "comment": {
        "value": "Very good, veeeery good"
      }
    }
    // ...
  }
}
Push payload
FieldNotes
propertiesThis is not a full properties object. This push shows only the properties that have been recently updated.

chat_thread_properties_deleted

Informs about those chat 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": {
      "comment": {
        "value": "goooood"
      }
    }
  }
}
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

chat_thread_tagged

Informs that a chat thread was tagged.

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

chat_thread_untagged

Informs that a chat thread was untagged.

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

Customers

customer_visit_started

Informs that a Customer entered the tracked website.

Sample push payload
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "visit_id": 42,
  "started_at": "2017-10-12T15:19:21.010200Z",
  "ip": "<ip>",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36",
  "geolocation": {
    "latitude": "55.0805",
    "longitude": "16.0211",
    "country": "Poland",
    "country_code": "PL",
    "region": "Dolnoslaskie",
    "city": "Wroclaw",
    "timezone": "Europe/Warsaw"
  }
}

customer_created

Informs that a new Customer registered.

Sample push payload
Copied!
{
  "customer": {
    // "User > Customer" object
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "created_at": "2019-11-14T14:27:24.410018Z",
    "email": "customer1@example.com",
    "avatar": "https://example.com/avatars/1.jpg",
    "fields": {
        "some_key": "some_value"
    }
  }
}

customer_updated

Informs that Customer's data was updated.

Sample push payload
Copied!
{
  "customer": {
    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
    "name": "John Doe",
    "email": "john@doe.me",
    "avatar": "https://example.com/avatars/1.jpg",
    "type": "customer",
    "present": false,
    "banned": false,
    "fields": {
      "custom field name": "custom field 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_visit_ended

Informs that a Customer left the tracked website.

Sample push payload
Copied!
{
  "customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "visit_id": 42,
  "ended_at": "2017-10-12T15:19:21.010200Z"
}

Status

agent_updated

Informs that an Agent's status was updated.

Sample push payload
Copied!
{
  "agent_id": "agent1@example.com",
  "routing_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
TypeNotes
access_token_revokedAgent access token has been revoked.
access_token_expiredAccess token life time has elapsed.
license_expiredLicense has expired.
agent_deletedAgent account has been deleted.
agent_logged_out_remotelyAgent has been logged out remotely.
agent_disconnected_by_serverAgent has been disconnected by the server.
unsupported_versionConnecting to an unsupported version of the Agent API.
ping_timeoutNot receiving ping for some time from the Customer.
internal_errorInternal error
too_many_connectionsAgent reached the max. number of connections.
misdirected_request *Agent connected to the server in the wrong region.
product_version_changedProduct version has been changed.
license_not_foundLicense with the specified ID doesn't exist.

*) Also, misdirected_request 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.

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_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": "d17cd570-11a9-45c0-45c0-1b020b7586dc",
    "recipients": "all",
    "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": "agent1@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