API version

RTM API Reference

Introduction

Versioning

This document describes the Customer Chat Real-Time Messaging API v3.1. This is the legacy version. We encourage you to migrate to the latest stable version. Read more about versioning...

What is RTM API

Real-Time Messaging API (RTM API) is based on a websocket-like connection. Client can send a request message that results in getting a response message. It's also possible to get push messages.

When to use RTM API

If you're wondering which API to use - Customer Chat RTM API or Web API, keep on reading.

Real-Time Messaging API allows for building stateful integrations that require logging in and maintaining the connection. Since connection maintenance is required, the implementation might be more challenging than with Web API.

Customer Chat RTM API enables communication in real time. It supports pushes like sneak peek, typing indicator, and other. Web API doesn’t have equivalent webhooks, which means you won't be informed about certain events using Web API.

Also, the RTM API will be a better choice if you want to avoid time delays or presume significant traffic.

Not what you're looking for? Perhaps, you need to use Customer Chat Web API instead.

Access

The basics on authorization and server pinging in the Customer Chat RTM API.

Authorization

Customer authorization is handled with access tokens. Find out how to get an access token from Customer authorization flow. You need to authorize within 30 seconds from establishing the connection. Otherwise, the connection will be closed. Given that the connection is continuosly maintained, you only need to authorize once.

Server pinging

After successful authorization, the client needs to ping the server every 15 seconds. Otherwise, the connection will be closed after about 30 seconds of inactivity. Until authorization is completed, ping is a no-op.

Use one of these 2 ways of pinging the server:

  • Protocol message with the ping action

For web applications and backend integrations (e.g. in Python, Go). Send the following request every 15 seconds:

{
  "action": "ping",
  "payload": {}
}

After pinging the server, the client will receive a response with the ping action. Thanks to that, the client can make sure the connection is still alive.

  • The control frame ping in the websocket protocol

For backend integrations; unavailable in web browsers. Read more about the control frame ping.

Data centers

LiveChat system operates in two data centers: dal (USA) and fra (Europe). The default data center is dal.

For backend applications, you can specify the region in the request header. The mechanism is the same as in Customer Chat Web API reference. It doesn't work for frontend applications, though. Instead, frontend apps connect to a region different than the default one by specifying the region suffix in the URL.

fra: wss://api-fra.livechatinc.com/v3.1/customer/rtm/ws

dal: wss://api.livechatinc.com/v3.1/customer/rtm/ws

Data structures

To find sample payloads of events, users, and other common structures such as chats or threads visit the Data structures document.

Methods

In the websocket transport, actions generate pushes. RTM API actions can also trigger webhooks, but they need to be registered first.

The API endpoint
wss://api.livechatinc.com/v3.1/customer/rtm/ws

When connecting to the Customer Chat RTM API, clients have to send over the required query string parameters.

Required parameterData typeNotes
license_idintegerLiveChat account ID

Available methods

Chatsget_chats_summary get_chat_threads_summary get_chat_threads start_chat activate_chat close_thread
Eventssend_event send_rich_message_postback send_sneak_peek
Propertiesupdate_chat_properties delete_chat_properties update_chat_thread_properties delete_chat_thread_properties update_event_properties delete_event_properties
Customersupdate_customer update_customer_page set_customer_fields
Statuslogin get_groups_status
Otherget_form get_predicted_agent get_url_details mark_events_as_seen
GENERAL RTM API REQUEST FORMAT
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "<action>",
  "payload": {
    // optional
  }
}
GENERAL RTM API RESPONSE FORMAT
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "<action>",
  "type": "response",
  "success": true,
  "payload": {
    // optional
  }
}

Chats

Get Chats Summary

It returns summaries of the chats a Customer participated in.

Specifics
Actionget_chats_summary
Web API equivalentget_chats_summary
Push message-
Request
ParameterRequiredTypeNotes
offsetNonumberDefault: 0; maximum: 100
limitNonumberDefault: 10; maximum: 25
REQUEST
Copied!
{
  "action": "get_chats_summary",
  "payload": {}
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_chats_summary",
  "type": "response",
  "success": true,
  "payload": {
    "chats_summary": [
        {
            "id": "PJ0MRSHTDG",
            "order": 1575892853242000,
            "last_thread_id": "K600PKZON8",
            "last_event_per_type": {
                "message": {
                    "thread_id": "K600PKZON9",
                    "thread_order": 1,
                    "event": {
                        "id": "Q298LUVPRH_1",
                        "created_at": "2019-12-09T12:01:18.909000Z",
                        "type": "message",
                        "text": "hello world",
                        "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
                    }
                }
            },
            "users": [
                {
                    "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
                    "type": "customer",
                    "present": true
                },
                {
                    "id": "d5eff798-f8df-4364-8059-649c35c9ed0c",
                    "name": "Agent Name",
                    "type": "agent",
                    "present": true,
                    "avatar": "https://example.com/avatar.png",
                    "job_title": "Support Agent"
                }
            ],
            "access": {
                "group_ids": [0]
            },
            "properties": {
                // "Properties" object
                }
            },
            "active": true
        }
    ],
    "total_chats": 1
  }
}

Get Chat Threads Summary

Specifics
Actionget_chat_threads_summary
Web API equivalentget_chat_threads_summary
Push message-
Request
ParameterRequiredData typeNotes
chat_idYesstring
offsetNonumberDefault: 0.
limitNonumberDefault: 25; maximum: 100.
Response
FieldNotes
threads_summarySorted descendingly by order.
REQUEST
Copied!
{
  "action": "get_chat_threads_summary",
  "payload": {
    "chat_id": "PJ0MRSHTDG"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_chat_threads_summary",
  "type": "response",
  "success": true,
  "payload": {
    "threads_summary": [
        {
            "id": "Q298LUVPRH",
            "order": 1,
            "total_events": 1,
            "active": true
        }
    ],
    "total_threads": 1
  }
}

Get Chat Threads

Specifics
Actionget_chat_threads
Web API equivalentget_chat_threads
Push message-
Request
ParameterRequiredData type
chat_idYesstring
thread_idsYesarray
REQUEST
Copied!
{
  "action": "get_chat_threads",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_ids": ["K600PKZON8"]
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_chat_threads",
  "type": "response",
  "success": true,
  "payload": {
        "chat": {
        "id": "PJ0MRSHTDG",
        "order": 1576569422,
        "threads": [
            {
                "id": "K600PKZON8",
                "active": true,
                "user_ids": [
                    "b7eff798-f8df-4364-8059-649c35c9ed0c",
                    "bbb67d600796e9f277e360e842418833"
                ],
                "events": [
                    {
                        "id": "Q20N9CKRX2_1",
                        "created_at": "2019-12-17T07:57:41.512000Z",
                        "type": "message",
                        "text": "Hello",
                        "author_id": "bbb67d600796e9f277e360e842418833"
                    }
                ],
                "order": 1,
                "properties": {
                  // "Property" object
                },
                "access": {
                    "group_ids": [0]
                }
            }
        ],
        "users": [
            {
                "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
                "type": "customer",
                "present": true
            },
            {
                "id": "bbb67d600796e9f277e360e842418833",
                "name": "Agent Name",
                "type": "agent",
                "present": true,
                "avatar": "https://example.com/avatar.jpg",
                "job_title": "Support Agent"
            }
        ],
        "access": {
            "group_ids": [0]
        },
        "properties": {
          // "Property" object
        }
    }
  }
}

Start Chat

Starts a chat.

Specifics
Actionstart_chat
Web API equivalentstart_chat
Push messageincoming_chat_thread
Request
ParameterRequiredData typeNotes
chatNoobject
chat.propertiesNoobjectInitial chat properties
chat.accessNoobjectChat access to set, default: all agents.
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial chat thread properties
continuousNoboolStarts chat as continuous (online group is not required); default: false.
Response
FieldData typeNotes
chat_idstring
thread_idstring
event_ids[]stringReturned only when the chat was started with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.
REQUEST
Copied!
{
  "action": "start_chat",
  "payload": {}
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "start_chat",
  "type": "response",
  "success": true,
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "PGDGHT5G"
    }
}

Activate Chat

Used to restart an archived chat.

Specifics
Actionactivate_chat
Web API equivalentactivate_chat
Push messageincoming_chat_thread
Request
ParameterRequiredTypeNotes
chatYesobject
chat.idYesstringThe ID of the chat that will be activated.
chat.accessNoobjectChat access to set, default: all agents.
chat.propertiesNoobjectInitial chat properties
chat.threadNoobject
chat.thread.eventsNoarrayInitial chat events array
chat.thread.propertiesNoobjectInitial chat thread properties
continuousNoboolSets a chat to the continuous mode. When unset, leaves the mode unchanged.
Response
FieldData typeNotes
thread_idstring
event_ids[]stringReturned only when the chat was activated with initial events. Returns only the IDs of user-generated events; server-side generated events are not included in the array.
REQUEST
Copied!
{
  "action": "activate_chat",
  "payload": {
    "chat": {
      "id": "PWJ8Y4THAV"
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "activate_chat",
  "type": "response",
  "success": true,
  "payload": {
    "thread_id": "Z8AGR5OUW"
  }
}

Close Thread

Closes the thread. Sending messages to this thread will no longer be possible.

Specifics
Actionclose_thread
Web API equivalentclose_thread
Push messageincoming_event and thread_closed
Request
ParameterRequiredData type
chat_idYesstring
REQUEST
Copied!
{
  "action": "close_thread",
  "payload": {
    "chat_id": "PJ0MRSHTDG"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "close_thread",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Events

Send Event

Sends an Event object. Use this method to send a message by specifing the Message event type in the request.

Specifics
Actionsend_event
Web API equivalentsend_event
Push messageincoming_event
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to send the message to.
eventYesobjectThe Event object
attach_to_last_threadNoboolThe flag is ignored for active chats. For inactive chats: true – the event will be added to the last thread; false – the request will fail. Default: false.
REQUEST
Copied!
{
  "action": "send_event",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "event": {
      "type": "message",
      "text": "hello world",
      "recipients": "all"
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "send_event",
  "type": "response",
  "success": true,
  "payload": {
     "event_id": "K600PKZON8"
  }
}

Send Rich Message Postback

Specifics
Actionsend_rich_message_postback
Web API equivalentsend_rich_message_postback
Push messageincoming_rich_message_postback*

*) incoming_rich_message_postback will be sent only for active threads.

Request
ParameterRequiredData typeNotes
chat_idYesstring
event_idYesstring
postbackYesobject
postback.idYesstringPostback name of the button
postback.toggledYesboolPostback toggled, true or false
thread_idYesstring
REQUEST
Copied!
{
  "action": "send_rich_message_postback",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8",
    "event_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f7",
    "postback": {
      "id": "Method URL_yes",
      "toggled": true
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "send_rich_message_postback",
  "type": "response",
  "success": true,
  "payload": {
    //no response payload
  }
}

Send Sneak Peek

Sends a sneak peek to a chat.

Specifics
Actionsend_sneak_peek
Web API equivalentsend_sneak_peek
Push message-
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat to send a sneak peek to.
sneak_peek_textYesstringSneak peek text
REQUEST
Copied!
{
  "action": "send_sneak_peek",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "sneak_peek_text": "hello world"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "send_sneak_peek",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Properties

Update Chat Properties

Specifics
Actionupdate_chat_properties
Web API equivalentupdate_chat_properties
Push messagechat_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you to set a property for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
REQUEST
Copied!
{
  "action": "update_chat_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "score": 10,
        "comment": "Thank you!"
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_chat_properties",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Delete Chat Properties

Specifics
Actiondelete_chat_properties
Web API equivalentdelete_chat_properties
Push messagechat_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete properties of.
propertiesYesobjectChat properties to delete.
REQUEST
Copied!
{
  "action": "delete_chat_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": ["score", "comment"]
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "delete_chat_properties",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Update Chat Thread Properties

Specifics
Actionupdate_chat_thread_properties
Web API equivalentupdate_chat_thread_properties
Push messagechat_thread_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
REQUEST
Copied!
{
  "action": "update_chat_thread_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "score": 10,
        "comment": "Thank you!"
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_chat_thread_properties",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Delete Chat Thread Properties

Specifics
Actiondelete_chat_thread_properties
Web API equivalentdelete_chat_thread_properties
Push messagechat_thread_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete the properties of.
thread_idYesstringId of the thread you want to delete the properties of.
propertiesYesobjectChat thread properties to delete.
REQUEST
Copied!
{
  "action": "delete_chat_thread_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": ["score", "comment"]
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "delete_chat_thread_properties",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Update Event Properties

Specifics
Actionupdate_event_properties
Web API equivalentupdate_event_properties
Push messageevent_properties_updated
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to set properties for.
thread_idYesstringId of the thread you want to set properties for.
event_idYesstringId of the event you want to set properties for.
propertiesYesobjectChat properties to set. You should stick to the general properties format and include namespace, property name and value.
REQUEST
Copied!
{
  "action": "update_event_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "event_id": "2_EW2WQSA8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "score": 10,
        "comment": "Thank you!"
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_event_properties",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Delete Event Properties

Specifics
Actiondelete_event_properties
Web API equivalentdelete_event_properties
Push messageevent_properties_deleted
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete the properties of.
thread_idYesstringId of the thread you want to delete the properties of.
event_idYesstringId of the event you want to delete the properties of.
propertiesYesobjectEvent properties to delete.
REQUEST
Copied!
{
  "action": "delete_event_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "event_id": "2_EW2WQSA8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "rating": ["score", "comment"]
      }
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "delete_event_properties",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Customers

Update Customer

Specifics
Actionupdate_customer
Web API equivalentupdate_customer
Push messagecustomer_updated
Request
ParameterRequiredData typeNotes
nameNostring
emailNostring
avatarNostringURL of the Customer's avatar.
fieldsNoobjectkey: value format

At least one optional parameter needs to be included in the request payload.

REQUEST
Copied!
{
  "action": "update_customer",
  "payload": {
    "name": "John Doe"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_customer",
  "type": "response",
  "success": true,
  "payload": {
    // "User > Customer" object
  }
}

Update Customer Page

Specifics
Actionupdate_customer_page
Web API equivalent-
Push messagecustomer_page_updated

Agent and referrer are updated by default using the browser’s headers.

Request
ParameterRequiredData type
urlYesstring
titleNostring
REQUEST
Copied!
{
  "action": "update_customer_page",
  "payload": {
    "url": "https://livechatinc.com/pricing"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "update_customer_page",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Set Customer Fields

Specifics
Actionset_customer_fields
Web API equivalentset_customer_fields
Push messagecustomer_updated
Request
ParameterRequiredData typeNotes
fieldsYesobjectkey:value format

Agent and referrer are updated by default using the browser’s headers.

REQUEST
Copied!
{
  "action": "set_customer_fields",
  "payload": {
    "fields": {
      "company_size": "10-100"
    }
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "set_customer_fields",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Status

Login

It returns the initial state of the current Customer.

Specifics
Actionlogin
Web API equivalent-
Push message-
Request
ParameterRequiredData typeNotes
tokenYesstringOAuth token from the Customer's account
customerNoobject
customer.avatarNostringThe URL of the Customer's avatar
customer.emailNostring
customer.nameNostring
customer.fieldsNoobjectA map in the "key": "value" format
customer_page.titleNostring
customer_page.urlNostring
customer_side_storage*NoobjectA map in the "key": "value" format
is_mobileNoboolInforms if logging in is performed from a mobile device.
group_idNonumber
referrerNostring

*) We use customer_side_storage to keep some data on the client side. You should pass a map from the customer_side_storage_updated push payload to this field.

REQUEST
Copied!
{
    "action": "login",
    "payload": {
        "token": "<customer_access_token>"
        }
    }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "login",
  "type": "response",
  "success": true,
  "payload": {
    "customer_id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
    "has_active_thread": true,
    "chats": [{
      "chat_id": "PJ0MRSHTDG",
      "has_unread_events": true
        }],
    "__priv_dynamic_config": {
      "customer_data": {
        "name": "John Doe",
        "last_visit_timestamp": 1473433500,
        "page_views_count": 40,
        "visits_count": 15,
        "chats_count": 2,
        "invitations_shown_count": 20,
        "invitations_accepted_count": 1,
        "client_version": "432423423",
        "fields": "some fields",
        "group_id": 2
      },
      "online_groups_ids": [1, 3],
      "global_properties": {
        "key1": "value1",
        "key2": "value2"
      },
      "customer_groups": {
        "monitoring": {
          "id": 1,
          "static_config_url": "/licence/1520/get_static_config.121.1808829.94.95.39446.4011.2385.398.160.552.58.337.44320.js",
          "language_config_url": "/licence/1520/v2/localization.en.121.004b8e014f50ea0c6ad6227162f7d18f_40d391a9adcdbf190e62fcd21c865bf2.js"
        },
        "chats": {
          "2": {
            "chat_ids": ["PJ0MRSHTDG"],
            "static_config_url": "/licence/1520/get_static_config.121.1808829.94.95.39446.4011.2385.398.160.552.58.337.44320.js",
            "language_config_url": "/licence/1520/v2/localization.en.121.004b8e014f50ea0c6ad6227162f7d18f_40d391a9adcdbf190e62fcd21c865bf2.js"
          }
        }
      },
      "static_config_version": "3435.4545",
      "predicted_agent": {
        "id": "agent1@example.com",
        "name": "Bart",
        "type": "agent",
        "avatar": "cdn.livechatinc.com/avatars/1.png",
        "job_title": "Support Agent"
      },
      "greeting": {
        "id": 342543723,
        "unique_id": "e35a4fb4106d87e550fe1af480639058",
        "text": "some message",
        "agent": {
          "id": "agent1@example.com",
          "name": "Bart",
          "type": "agent",
          "avatar": "cdn.livechatinc.com/avatars/1.png",
          "job_title": "Support Agent",
          "is_bot": false
        },
        "displayed_first_time": true
        }
      }
    }
}

Get Groups Status

Specifics
Actionget_groups_status
Web API equivalentget_groups_status
Push message-
Request
ParameterRequiredData typeNotes
allNoboolIf set to true, you will get statuses of all the groups.
groupsNoarrayA table of a groups' IDs

One of the optional parameters needs to be included in the request payload.

Response
Group Not FoundIf you send group_id of a group that doesn't exists, the id won't be included in the resposne payload.
REQUEST
Copied!
{
  "action": "get_groups_status",
  "payload": {
    "all": true
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_groups_status",
  "type": "response",
  "success": true,
  "payload": {
    "groups_status": {
      //1,2,3 are group ids, online/offline/online_for_queue are statuses of the groups

      1: "online",
      2: "offline",
      3: "online_for_queue"
    }
  }
}

Other

Get Form

Returns an empty ticket form of a prechat or postchat survey.

Specifics
Actionget_form
Web API equivalentget_form
Push message-
Request
ParameterRequiredData typeNotes
group_idYesnumberId of the group from which you want the form.
typeYesstringForm type. Possible values: prechat or postchat.
Response
FieldNotes
enabledIf enabled: false, the form object is not returned. Prechat/postchat survey disabled in the LiveChat Agent App UI.
formThe form object
REQUEST
Copied!
{
  "action": "get_form",
  "payload": {
    "group_id": 0,
    "type": "prechat"
  }
}
Response
Copied!
{
  "payload": {
    "form": {
      "id": "156630109416307809",
      "fields": [
        {
          "id": "15663010941630615",
          "type": "header",
          "label": "Welcome to our LiveChat! Please fill in the form below before starting the chat."
        },
        {
          "id": "156630109416307759",
          "type": "name",
          "label": "Name:",
          "required": false
        },
        {
          "id": "15663010941630515",
          "type": "email",
          "label": "E-mail:",
          "required": false
        }
      ]
    },
    "enabled": true
  }
}

Get Predicted Agent

Gets the predicted Agent - the one the Customer will chat with when the chat starts.

Specifics
Actionget_predicted_agent
Web API equivalentget_predicted_agent
Push message-
REQUEST
Copied!
{
  "action": "get_predicted_agent",
  "payload": {}
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_predicted_agent",
  "type": "response",
  "success": true,
  "payload": {
      "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
      "name": "Name",
      "avatar": "https://example.avatar/example.com",
      "is_bot": false,
      "job_title": "support hero",
      "type": "agent"
  }
}

Get URL Details

It returns the info on a given URL.

Specifics
Actionget_url_details
Web API equivalentget_url_details
Push message-
Request
ParameterRequiredData typeNotes
urlYesstringValid website URL
REQUEST
Copied!
{
  "action": "get_url_details",
  "payload": {
    "url": "https://livechatinc.com"
  }
}
Response
Copied!
{
  "request_id": "<request_id>", // optional
  "action": "get_url_details",
  "type": "response",
  "success": true,
  "payload": {
    "title": "LiveChat | Live Chat Software and Help Desk Software",
    "description": "LiveChat - premium live chat software and help desk software for business. Over 24 000 companies from 150 countries use LiveChat. Try now, chat for free!",
    "image_url": "s3.eu-central-1.amazonaws.com/labs-fraa-livechat-thumbnails/96979c3552cf3fa4ae326086a3048d9354c27324.png",
    "image_width": 200,
    "image_height": 200,
    "url": "https://livechatinc.com"
  }
}

Mark Events As Seen

Specifics
Actionmark_events_as_seen
Web API equivalentmark_events_as_seen
Push messageevents_marked_as_seen
Request
ParameterRequiredData typeNotes
chat_idYesstring
seen_up_toYesstringRFC 3339 date-time format
Response

No response payload (200 OK).

REQUEST
Copied!
{
  "action": "mark_events_as_seen",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "seen_up_to": "2017-10-12T15:19:21.010200Z"
  }
}

Pushes

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.
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_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",
    "order": 343544565,
    "users": [
      // array of "User" objects
    ],
    "properties": {
      // "Properties" object
    },
    "access": {
      // "Access" object
    },
    "thread": {
      // "Thread" object
    }
  }
}
Specifics
Actionincoming_chat_thread
Webhook equivalentincoming_chat_thread

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
}
Specifics
Actionthread_closed
Webhook equivalentthread_closed
Push payload
FieldNotes
user_idMissing if a thread was closed by the router.

Chat access

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]
  }
}
Specifics
Actionaccess_set
Webhook equivalentaccess_set
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",
  "thread_id": "K600PKZON8",
  "requester_id": "cb531744-e6a4-4ded-b3eb-b3eb4ded4ded",
  "type": "agent",
  "ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
}
Specifics
Actionchat_transferred
Webhook equivalent-
Push payload
FieldNotes
typeagent or group
idsAn array of the group or agent IDs

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": "customer"
}
Specifics
Actionchat_user_added
Webhook equivalentchat_user_added
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": "user@example.com",
  "user_type": "customer"
}
Specifics
Actionchat_user_removed
Webhook equivalentchat_user_removed
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": "b7eff798-f8df-4364-8059-649c35c9ed0c"
  }
}
Specifics
Actionincoming_event
Webhook equivalentincoming_event

event_updated

Informs that an event was updated.

Sample push payload
Copied!
{
  "chat_id": "123-123-123-123",
  "thread_id": "E2WDHA8A",
  "event": {
    // "Event" object
  }
}
Specifics
Actionevent_updated
Webhook equivalentevent_updated

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
  }
}
Specifics
Actionincoming_rich_message_postback
Webhook equivalentincoming_rich_message_postback

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!"
      }
    }
    // ...
  }
}
Specifics
Actionchat_properties_updated
Webhook equivalentchat_properties_updated
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": "PJ0MRSHTDG",
    "properties": {
        "rating": ["score", "comment"]
        },
        // ...
    }
}
Specifics
Actionchat_properties_deleted
Webhook equivalentchat_properties_deleted
Push payload
FieldNotes
propertiesNot 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!"
      }
    }
    // ...
  }
}
Specifics
Actionchat_thread_properties_updated
Webhook equivalentchat_thread_properties_updated
Push payload
FieldNotes
propertiesThis is not a full properties object. This push shows only the properties the 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"]
        },
        // ...
    }
}
Specifics
Actionchat_thread_properties_deleted
Webhook equivalentchat_thread_properties_deleted
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": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event_id": "2_E2WDHA8A",
  "properties": {
    "rating": {
      "comment": {
        "value": "Very good!"
      }
    }
  }
}
Specifics
Actionevent_properties_updated
Webhook equivalentevent_properties_updated
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": "PJ0MRSHTDG",
    "thread_id": "K600PKZON8",
    "event_id": "2_E2WDHA8A",
    "properties": {
        "rating": ["score", "comment"]
        },
        // ...
    }
}
Specifics
Actionevent_properties_deleted
Webhook equivalentevent_properties_deleted
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
  }
}
Specifics
Actioncustomer_updated
Webhook equivalent-

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
}
Specifics
Actioncustomer_page_updated
Webhook equivalent-

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"
  }
}
Specifics
Actioncustomer_side_storage_updated
Webhook equivalent-
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"
  }
}
Specifics
Actioncustomer_disconnected
Webhook equivalent-
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 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.

**) 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.

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
  }
}
Specifics
Actionincoming_typing_indicator
Webhook equivalent-

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"
    }
  }
}
Specifics
Actionincoming_multicast
Webhook equivalent-
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"
}
Specifics
Actionevents_marked_as_seen
Webhook equivalentevents_marked_as_seen

Errors

General error format
Copied!
{
  "error": {
    "type": "misdirected_request",
    "message": "Wrong region",
    "data": {
      // optional
      "region": "dal"
    }
  }
}

Possible errors

Error typeDefault messageDescription
authenticationAuthentication errorAn invalid or expired access token.
authorizationAuthorization errorUser is not allowed to perform the action.
customer_bannedCustomer is bannedThe customer had been banned.
greeting_not_foundGreeting not found
group_not_foundGroup not found
group_offlineGroup is offlineThrown in response to Get Predicted Agent.
group_unavailableNo agent available for groupThrown in response to Get Predicted Agent. The group is online, but there are no available Agents.
groups_offlineGroups offline
internalInternal server error
license_expiredLicense expiredThe end of license trial or subcription.
pending_requests_limit_reachedRequests limit reachedThe limit of pending requests within one websocket connection has been reached. The limit is 10.
request_timeoutRequest timed outTimeout threshold is 15 seconds.
too_many_requestsToo many requestsThe request's rate limit was exceeded. It'll be unblocked automatically after some time.
unsupported_versionUnsupported versionUnsupported protocol version.
users_limit_reachedUsers limit reached Displayed on the attempt of logging in. The limit of online Customers for a given license has been reached.
validationWrong format of request
wrong_product_versionWrong product versionLicense is not LiveChat 3 (probably still LiveChat 2).

Contact us

If you found a bug or a typo, you can let us know directly on GitHub. In case of any questions or feedback, don't hesitate to contact us at developers@livechat.com. We'll be happy to hear from you!