RTM API Reference

4 minutes reading time • last modified 10/15/2019

Introduction

Versioning

This document describes the Customer Chat Real-Time Messaging API v3.1.

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.

Authentication

Customer authentication is handled by access tokens. Find out how to get an access token from Customer authorization flow within 30 seconds, otherwise the connection will be closed.

After successful authorization, client should ping the server each 15 seconds, otherwise the connection will be closed after about 30 seconds of inactivity. If the control frame ping, client should use a protocol message with the ping action. Until authorization is completed, ping is a no-op.

If a method requires particular authorization scopes, you'll find them included in the method description.

Given that the connection is continuosly maintained, you only need to authorize once.

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

Events

One of the data structures are events. They are sent to a chat via the send_event method. Apart from events, there are also Properties, Users, and Other common data structures.

These are the available event types:

File

File event informs about a file being uploaded.

FieldReq./Opt.Note
content_typerequiredSupported image types: image/png, image/jpeg, image/gif
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
custom_idoptional-
propertiesoptional-
recipientsrequiredPossible values: all (default), agents
system_message_typerequired-
width, height, thumbnail_url, thumbnail2x_urloptionalOnly for images
Sample File event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "file",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "recipients": "all",
  "properties": {
    // "Properties" object
  },
  "name": "image25.png", // generated server-side
  "url": "https://domain.com/asdsfdsf.png",
  "thumbnail_url": "https://domain.com/thumbnail.png", // generated server-side
  "thumbnail2x_url": "https://domain.com/thumbnail2x.png", // generated server-side
  "content_type": "image/png", // generated server-side
  "size": 123444, // generated server-side
  "width": 640, // generated server-side
  "height": 480 // generated server-side
}

Filled form

Filled form event contains data from a form.

FieldReq./OptNote
custom_idoptional-
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
propertiesoptional-
recipientsrequiredPossible values: all (default), agents
name, email, question, textareaoptionalFor open questions (text answer)
radio, selectoptionalFor single-choice questions
checkboxoptionalFor multiple-choice questions
group_chooseroptionalFor group-choice questions
Sample Filled form event
{
	"id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
	"custom_id": "31-0C-1C-07-DB-16",
	"created_at": "2017-10-12T15:19:21.010200Z",  // generated server-side
	"type": "filled_form",
	"author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
	"recipients": "all",
	"properties": {
		// "Properties" object
	},
	"form_id": "1473433500211",
	"fields": [{
		"type": "name",
		"id": "154417206262603539",
		"label": "Your name",
		"answer": "John Doe"
	}, {
		"type": "email",
		"id": "154417206262601584",
		"label": "Your email",
		"answer": "customer1@example.com"
	}, {
		"type": "radio",
		"id": "154417206262602571",
		"label": "Chat purpose",
		"answer": {
				"id": "0",
				"label": "Support"
		}
	}, {
		"type": "checkbox",
		"id": "154417206262604640",
		"label": "Company industry",
		"answers": [{
			"id": "0"
			"label": "automotive"
		}, {
			"id": "1"
			"label": "it"
		}]
	}, {
		"type": "group_chooser",
		"id": "154417206262605324",
		"label": "Choose department",
		"answer": {
			"group_id": 1,
			"label": "Marketing"
		}
	}]
}

Message

Message event contains text message to other chat users.

FieldReq./Opt.Notes
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
recipientsrequiredPossible values: all (default), agents
textrequiredMax. raw text size is 16 KB (one UTF-8 char like emoji 😁 can use up to 4 B); to send more, split text into several messages.
custom_idoptional
postbackoptionalAppears in the message event only when triggered by a rich message.
postback.typeoptionalRequired only if postback.value is present.
postback.valueoptionalRequired only if postback.type is present.
propertiesoptionalThe properties object
Sample Message event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "text": "hello there",
  "postback": {
    "id": "action_call",
    "thread_id": "K600PKZON8",
    "event_id": "75a90b82-e6a4-4ded-b3eb-cb531741ee0d",
    "type": "phone",
    "value": "790034890"
  },
  "recipients": "all",
  "properties": {
    // "Properties" object
  }
}

Rich message

Rich message event contains rich message data structure.

FieldReq./Opt.Notes
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
recipientsrequiredPossible values: all (default), agents
template_idrequiredDescribes how the event should be presented in an app.
custom_idoptional
elementsoptionalMay contain 1 - 10 element objects.
elements.buttonsoptionalbuttons may contain 1 - 11 button objects.
elements.buttons.postback_idoptionalRequired only if elements.buttons is present. Describes the action sent via send_rich_message_postback. Multiple buttons (even from different elements) can contain the same postback_id. Calling send_rich_message_postback with this id will add a user to all those buttons at once.
elements.buttons.textoptionalRequired only if elements.buttons is present.
elements.buttons.typeoptionalRequired only if both elements.buttons and elements.buttons.value are present.
elements.buttons.user_idsoptionalRequired only if elements.buttons is present. Describes users that sent the postback with "toggled": true.
elements.buttons.valueoptionalRequired only if both elements.buttons and elements.buttons.type are present.
elements.buttons.webview_heightoptionalPossible values: compact, full, tall
elements.imageoptionalimage properties are optional: name, url, content_type, size, width, height.
elements.subtitleoptional
elements.titleoptional
propertiesoptionalThe properties object
Sample Message event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "rich_message",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "recipients": "all",
  "properties": {
    // "Properties" object
  },
  "template_id": "cards",
  "elements": [
    {
      "title": "Lorem ipsum dolor.",
      "subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "image": {
        "name": "image25.png",
        "url": "https://domain.com/asdsfdsf.png",
        "content_type": "image/png",
        "size": 123444,
        "width": 640,
        "height": 480
      },
      "buttons": [
        {
          "text": "yes",
          "postback_id": "action_yes",
          "user_ids": ["b7eff798-f8df-4364-8059-649c35c9ed0c"]
        },
        {
          "text": "no",
          "postback_id": "action_no",
          "user_ids": []
        },
        {
          "type": "phone",
          "text": "value",
          "value": "790034890",
          "webview_height": "tall", // optional, one of compact, tall, full
          "postback_id": "action_call",
          "user_ids": []
        }
      ]
    },
    {
      "title": "Lorem ipsum dolor 2."
    }
  ]
}

Custom

Custom event is an event with customizable payload.

FieldReq./Opt.Note
custom_idoptional-
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
propertiesoptional-
recipientsrequiredPossible values: all (default), agents
Sample Rich message event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "custom",
  "author_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "content": {
    "custom": {
      "nested": "json"
    }
  },
  "recipients": "all",
  "properties": {
    // "Properties" object
  }
}

System message

System message event is a native system event sent in specific situations.

FieldReq./Opt.Note
custom_idoptional-
created_atrequiredDate & time format with a resolution of microseconds, UTC string.
recipientsrequiredPossible values: all (default for system events), agents (for the events sent via send_event)
system_message_typerequired-
Sample System message event
{
  "id": "0affb00a-82d6-4e07-ae61-56ba5c36f743", // generated server-side
  "custom_id": "31-0C-1C-07-DB-16",
  "created_at": "2017-10-12T15:19:21.010200Z", // generated server-side
  "type": "system_message",
  "text": "hello there",
  "system_message_type": "routing.assigned",
  "text_vars": {
    "agent": "John Doe"
  }
}

Here's the list of all system messages you might come across as a Customer:

agent_added

ContentGenerated when
%initiator% added %agent% to the chatAgent was added to chat via the add_user_to_chat request and is not the first Agent in that chat.

agent_removed

ContentGenerated when
%initiator% removed %agent% from the chatAgent was removed from chat via the remove_user_from_chat request.

archived_customer_disconnected

ContentGenerated when
%customer% left the chatChat ended after Customer left the website.

chat_transferred

ContentGenerated when
%initiator% transferred the chat to %targets%Chat was transferred via the transfer_chat request.

customer_added

ContentGenerated when
%initiator% added %customer% to the chatCustomer was added to chat via the add_user_to_chat request.

customer_banned

ContentGenerated when
Chat archived because customer was banned by %agent% for %duration% day(s)Chat ended becaus Customer was banned via the ban_customer request.

customer_removed

ContentGenerated when
%initiator% removed %customer% from the chatCustomer was removed from chat via the remove_user_from_chat request.

manual_archived_agent

ContentGenerated when
%agent% archived the chatAgent closed chat via the close_thread request.

manual_archived_customer

ContentGenerated when
%customer% archived the chatCustomer closed chat via the close_thread request.

rating.chat_commented

ContentGenerated when
%customer% left the following comment: %comment%Chat was commented by Customer.

rating.chat_rated

ContentGenerated when
%customer% rated the chat as %score%Chat was rated by Customer.

rating.chat_rating_canceled

ContentGenerated when
%customer% canceled the chat ratingChat rating was cancelled by Customer.

routing.archived_deleted

ContentGenerated when
The chat was closed because %agent% account had been deletedChat was archived after Agent was removed from the license. No other Agent could be selected, and queues were disabled.

routing.archived_disconnected

ContentGenerated when
The chat was closed because %agent% had lost internet connectionChat was archived after Agent unexpectedly lost connection. No other Agent could be selected, and queues were disabled.

routing.archived_inactive

ContentGenerated when
Chat archived due to %duration% minutes of inactivityNo new messages were posted for an extended amount of time.

routing.archived_offline

ContentGenerated when
Chat archived due to no available agentsNo Agent could be selected after chat was placed in the queue.

routing.archived_other

ContentGenerated when
The chat was closedChat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.

routing.archived_remotely_signed_out

ContentGenerated when
The chat was closed because %agent% had been remotely signed outChat was archived after an Agent was logged out. No other Agent could be selected and queues were disabled.

routing.archived_signed_out

ContentGenerated when
The chat was closed because %agent% had signed outChat was archived after Agent logged out. No other Agent could be selected, and queues were disabled.

routing.assigned_deleted

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% account had been deletedChat was assigned to a new Agent after the previous one was removed from the license.

routing.assigned_disconnected

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% had lost internet connectionChat was assigned to a new Agent after the previous one unexpectedly lost connection.

routing.assigned_inactive

ContentGenerated when
Chat assigned to %agent_added% because %agent_removed% hasn't replied in %duration% minutesChat was assigned to a new Agent after the previous one failed to response in a timely manner.

routing.assigned_other

ContentGenerated when
The chat was closedChat was archived after Agent was removed from chat for other reasons. No other Agent could be selected, and queues were disabled.

routing.assigned_remotely_signed_out

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% had been remotely signed outChat was assigned to a new Agent after the previous one was logged out.

routing.assigned_signed_out

ContentGenerated when
Chat assigned to %addedAgent% because %removedAgent% had signed outChat was assigned to a new Agent after the previous one logged out.

routing.unassigned_deleted

ContentGenerated when
Customer was queued because %agent% account has been deletedChat was queued after Agent was removed from the license.

routing.unassigned_disconnected

ContentGenerated when
Customer was queued because %agent% had lost internet connectionChat was queued after Agent unexpectedly lost connection.

routing.unassigned_other

ContentGenerated when
Chat is unassignedChat was queued after Agent was removed from chat for other reasons.

routing.unassigned_remotely_signed_out

ContentGenerated when
Customer was queued because %agent% had been remotely signed outChat was queued after Agent was logged out.

routing.unassigned_signed_out

ContentGenerated when
Customer was queued because %agent% had signed outChat was queued after Agent logged out.

system_archived

ContentGenerated when
Chat archivedLicense was moved to another lc_serv instance while there were still active chats.

transcript_requested

ContentGenerated when
%customer% requested the chat transcript to be sent to %email%Customer enables transcript.

Users

Users are another important data structure. Within this data structure type, we can distinguish:

Customer

Sample Customer data structure
{
  "id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "type": "customer",
  "name": "John Smith",
  "email": "customer1@example.com",
  "avatar": "https://domain.com/avatars/1.jpg",
  "fields": {
    "custom field name": "custom field value"
  },
  "present": true,
  "events_seen_up_to": 1473433500
}
FieldReq./Opt.
avataroptional
fieldsoptional

Agent

Sample Agent data structure
{
  "id": "agent1@example.com",
  "type": "agent",
  "name": "Support Team",
  "avatar": "cdn.livechatinc.com/avatars/1.png",
  "present": true,
  "events_seen_up_to": 1473433500
}

Other common structures

Apart from Events and Users, there are also other common data structures you might work with. Those are:

Access

Sample Access data structure
{
  "access": {
    "group_ids": [1, 2]
  }
}
FieldReq./Opt.Note
group_idsrequiredgroup 0 means that all agents can see it.

Chats

Sample Chat data structure
{
  "id": "PJ0MRSHTDG",
  "users": [
    // array of "User" objects
  ],
  "threads": [
    // optional
    // "Thread" object
  ],
  "threads_summary": [
    {
      "thread_id": "K600PKZON8",
      "order": 129846129847
    },
    {
      "thread_id": "K600PKZON8",
      "order": 129846129848
    }
  ],
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": true
}
FieldReq./Opt.
propertiesoptional
accessoptional

Chat summaries

Chat summary is similar to the Chat data structure. The difference is that Chat contains a thread object, while Chat summary includes last_thread_summary and last_event_per_type.

Sample Chat summary data structure
{
  "id": "PJ0MRSHTDG",
  "users": [
    // array of "User" objects
  ],
  "last_event_per_type": {
    // last event of each type in chat
    "message": {
      "thread_id": "K600PKZON8",
      "thread_order": 3,
      "event": {
        // "restricted_access": true
        // or
        // "Event > Message" object
      }
    },
    "system_message": {
      "thread_id": "K600PKZON6",
      "thread_order": 1,
      "event": {
        // "restricted_access": true
        // or
        // "Event > System message" object
      }
    }
    // ...
  },
  "last_thread_summary": {
    "id": "K600PKZON8",
    "order": 3,
    "timestamp": 1473433500,
    "user_ids": ["agent1@example.com"],
    "properites": {
      // "Properites" object
    },
    "tags": ["bug_report"]
  },
  "properites": {
    // "Properites" object
  },
  "access": {
    // "Access" object
  },
  "is_followed": false
}

Properties

Properties are key-value storages. They can be set within a chat, a thread, or an event. You can read more about properties in the Configuration API document.

Sample Properties data structure
{
  "properties": {
    "rating": {
      // <property_namespace>
      "score": {
        // <property_name>
        "value": 1 // <property_value>
      },
      "comment": {
        "value": "rated good!"
      }
    },
    "routing": {
      "idle": {
        "value": false
      }
    }
  }
}

Threads

Sample Thread data structure
{
  "id": "K600PKZON8",
  "timestamp": 1473433500,
  "active": true,
  "user_ids": ["agent1@example.com"],
  "restricted_access": true,
  "events": [
    // array of "Event" objects
  ],
  "order": 112057129857,
  "properties": {
    // "Properties" object
  },
  "access": {
    // "Access" object
  }
}
FieldReq./Opt.Note
accessoptional
activerequiredPossible values: true (thread is still active) or false(thread no longer active).
eventsoptionalDoesn't exists if restricted_access is true.
propertiesoptional
restricted_accessoptional

Methods

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
{
  "request_id": "<request_id>", // optional
  "action": "<action>",
  "payload": {
    // optional
  }
}
GENERAL RTM API RESPONSE FORMAT
{
  "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
{
  "action": "get_chats_summary",
  "payload": {}
}
Response
{
  "request_id": "<request_id>", // optional
  "action": "get_chats_summary",
  "type": "response",
  "success": true,
  "payload": {
    "chats_summary": [
      {
        "id": "123",
        "order": 343544565,
        "last_thread_id": "xyz",
        "users": [
          // array of "User" objects
        ],
        "properties": {
          // "Properties" object
        },
        "access": {
          // "Access" object
        },
        "last_event_per_type": {
          // last event of each type in chat
          "message": {
            "thread_id": "K600PKZON8",
            "thread_order": 3,
            "event": {
              // "Event > Message" object
            }
          },
          "system_message": {
            "thread_id": "K600PKZON8",
            "thread_order": 3,
            "event": {
              // "Event > System message" object
            }
          }
          // ...
        }
      }
    ],
    "total_chats": 20
  }
}

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
ParameterNotes
threads_summarySorted descendingly by order.
REQUEST
{
  "action": "get_chat_threads_summary",
  "payload": {
    "chat_id": "PJ0MRSHTDG"
  }
}
Response
{
  "request_id": "<request_id>", // optional
  "action": "get_chat_threads_summary",
  "type": "response",
  "success": true,
  "payload": {
    "threads_summary": [
      {
        "id": "a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5",
        "order": 2,
        "total_events": 1
      },
      {
        "id": "b0c22fdd-fb71-40b5-bfc6-a8a0bc3117f6",
        "order": 1,
        "total_events": 0
      }
    ],
    "total_threads": 4
  }
}

Get Chat Threads

Specifics
Actionget_chat_threads
Web API equivalentget_chat_threads
Push message-
Request
ParameterRequiredData type
chat_idYesstring
thread_idsNoarray
REQUEST
{
  "action": "get_chat_threads",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "thread_ids": ["a0c22fdd-fb71-40b5-bfc6-a8a0bc3117f5"]
  }
}
Response
{
  "request_id": "<request_id>", // optional
  "action": "get_chat_threads",
  "type": "response",
  "success": true,
  "payload": {
    "chat": {
      "id": "PJ0MRSHTDG",
      "order": 343544565,
      "users": [
        // array of "User" objects
      ],
      "properties": {
        // "Properties" object
      },
      "access": {
        // "Access" object
      },
      "threads": [
        // array of "Thread" objects
      ]
    }
  }
}

Start Chat

Starts a chat.

Specifics
Actionstart_chat
Web API equivalentstart_chat
Push messageincoming_chat_thread
Request
ParametersRequiredData typeNotes
chatNoobject
chat.propertiesNoobjectInitial chat properties
chat.accessNoobjectChat access to set, default: all agents.
chat.usersNoarrayList of existing users. Only one user is allowed (type customer).
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
ParameterData 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
{
  "action": "start_chat",
  "payload": {}
}
Response
{
  "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
Request objectRequiredTypeNotes
chatYesobject
chat.idYesstringThe ID of the chat that will be activated.
chat.accessNoobjectChat access to set, defaul: 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
ParameterData 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
{
  "action": "activate_chat",
  "payload": {
    "chat": {
      "id": "PWJ8Y4THAV"
    }
  }
}
Response
{
  "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
{
  "action": "close_thread",
  "payload": {
    "chat_id": "PJ0MRSHTDG"
  }
}
Response
{
  "request_id": "<request_id>", // optional
  "action": "close_thread",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Events

Send Event

Specifics
Actionsend_event
Web API equivalentsend_event
Push messageincoming_event
Request
ParametersRequiredData typeNotes
chat_idYesstringId of the chat you want to send the message to.
eventYesobjectThe Event object
attach_to_last_threadNoboolIf true, adds an event to the last (inactive) thread. Otherwise, it doesn't create a new one, default: false.
REQUEST
{
  "action": "send_event",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "event": {
      "type": "message",
      "text": "hello world",
      "recipients": "all"
    }
  }
}
Response
{
  "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
{
  "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
{
  "request_id": "<request_id>", // optional
  "action": "send_rich_message_postback",
  "type": "response",
  "success": true,
  "payload": {
    //no response payload
  }
}

Send Sneak Peek

Specifics
Actionsend_sneak_peek
Web API equivalentsend_sneak_peek
Push message-
Request
ParameterRequiredData typeNotes
chat_idYesstringIdd of the chat you to set a sneak peek to.
sneak_peek_textYesstringSneak peek text
REQUEST
{
  "action": "send_sneak_peek",
  "payload": {
    "chat_id": "PJ0MRSHTDG",
    "sneak_peek_text": "hello world"
  }
}
Response
{
  "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
{
  "action": "update_chat_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "score": 10,
        "comment": "Thank you!"
      }
    }
  }
}
Response
{
  "request_id": "<request_id>", // optional
  "action": "update_chat_properties",
  "type": "response",
  "success": true,
  "payload": {
    // no response payload
  }
}

Delete Chat Properties

Specifics
Actiondelete_chat_properties
Required scopes*chats.conversation--all:write chats.conversation--my:write
Web API equivalentdelete_chat_properties
Push messagechat_properties_deleted

*)

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats the requester belongs to
Request
ParameterRequiredData typeNotes
chat_idYesstringId of the chat you want to delete properties of.
propertiesYesobjectChat properties to delete. You should stick to the general properties format and include namespace, property name and value.
REQUEST
{
  "action": "delete_chat_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": ["score", "comment"]
    }
  }
}
Response
{
  "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
{
  "action": "update_chat_thread_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "score": 10,
        "comment": "Thank you!"
      }
    }
  }
}
Response
{
  "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
Required scopes*chats.conversation--all:write chats.conversation--my:write
Web API equivalentdelete_chat_thread_properties
Push messagechat_thread_properties_deleted

*)

  • chats.conversation--all:write - write access for conversation data of all license chats
  • chats.conversation--my:write - write access for conversation data of chats the requester belongs to
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. You should stick to the general properties format and include namespace, property name and value.
REQUEST
{
  "action": "delete_chat_thread_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": ["score", "comment"]
    }
  }
}
Response
{
  "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
{
  "action": "update_event_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "event_id": "2_EW2WQSA8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "score": 10,
        "comment": "Thank you!"
      }
    }
  }
}
Response
{
  "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. You should stick to the general properties format and include namespace, property name and value.
REQUEST
{
  "action": "delete_event_properties",
  "payload": {
    "chat_id": "PW94SJTGW6",
    "thread_id": "K600PKZON8",
    "event_id": "2_EW2WQSA8",
    "properties": {
      "bb9e5b2f1ab480e4a715977b7b1b4279": {
        "rating": ["score", "comment"]
      }
    }
  }
}
Response
{
  "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.
fieldsNoobjectA "key": "value" object

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

REQUEST
{
  "action": "update_customer",
  "payload": {
    "name": "John Doe"
  }
}
Response
{
  "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
{
  "action": "update_customer_page",
  "payload": {
    "url": "https://livechatinc.com/pricing"
  }
}
Response
{
  "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 equivalentget_customers
Push messagecustomer_updated
Request
ParameterRequiredData typeNotes
fieldsYesstringA key:value object

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

REQUEST
{
  "action": "set_customer_fields",
  "payload": {
    "fields": {
      "company_size": "10-100"
    }
  }
}
Response
{
  "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
{
	"action": "login",
	"payload": {
		"token": "Bearer dal:S2V0s1fgTbfXmgthj4cZSA"
		}
	}
}
Response
{
	"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

At least one optional parameter 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
{
  "action": "get_groups_status",
  "payload": {
    "all": true
  }
}
Response
{
  "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

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
ParameterNotes
formIf form is disabled, theform object won't be returned in the response.
headersFor headers; the field has no answer and is not sent in the filled_form event.
name, email, question, textareaFor open questions (text area)
radio, select, checkboxFor single/multiple-choice questions
group_chooserFor group-choice questions
ratingFor rating; the field isn't sent in the filled_form event.
REQUEST
{
  "action": "get_form",
  "payload": {
    "group_id": 0,
    "type": "prechat"
  }
}
Response
{
  "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
{
  "action": "get_predicted_agent",
  "payload": {}
}
Response
{
  "request_id": "<request_id>", // optional
  "action": "get_predicted_agent",
  "type": "response",
  "success": true,
  "payload": {
    "agent": {
      "id": "agent1@example.com",
      "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
{
  "action": "get_url_details",
  "payload": {
    "url": "https://livechatinc.com"
  }
}
Response
{
  "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 messagelast_seen_timestamp_updated
Request
ParameterRequiredData type
chat_idYesstring
seen_up_toYes`UTC string
Response

No response payload (200 OK).

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

Pushes

Pushes are server - client methods used for keeping the application state up-to-date. They are available only in the websocket transport. The Customer Chat Web API uses webhooks. The majority of pushes have their webhook equivalents.

The general push format
{
  "request_id": "<request_id>", // optional, applies only to the requester
  "action": "<action>",
  "type": "push",
  "payload": {
    // optional payload
  }
}

Chats

incoming_chat_thread

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

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

Chat access

access_set

Sample push payload
{
  "resource": "chat",
  "id": "PJ0MRSHTDG",
  "access": {
    "group_ids": [1]
  }
}
Specifics
Actionaccess_set
Webhook equivalentaccess_set
Push payload
ObjectNotes
resourceResource type
idResource id

chat_transferred

Sample push payload
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "requester_id": "cb531744-e6a4-4ded-b3eb-b3eb4ded4ded",
  "type": "customer",
  "ids": ["user@example.com"]
}
Specifics
Actionchat_transferred
Webhook equivalent-
Push payload
ObjectNotes
typeagent or group
idsAn array of the group or agent IDs

Chat users

chat_user_added

Sample push payload
{
  "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
ObjectNotes
user_typePossible values: agent, customer

chat_user_removed

Sample push payload
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "user_id": "user@example.com",
  "user_type": "customer"
}
Specifics
Actionchat_user_removed
Webhook equivalentchat_user_removed
Push payload
ObjectNotes
user_typePossible values: agent, customer

Events

incoming_event

Sample push payload
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "event": {
    // "Event" object
  }
}
Specifics
Actionincoming_event
Webhook equivalentincoming_event

event_updated

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

incoming_rich_message_postback

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

Sample push payload
{
  "chat_id": "PJ0MRSHTDG",
  "properties": {
    "rating": {
      "score": {
        "value": 1
      },
      "comment": {
        "value": "Very good!"
      }
    }
    // ...
  }
}
Specifics
Actionchat_properties_updated
Webhook equivalentchat_properties_updated
Push payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.

chat_properties_deleted

Sample push payload
{
	"chat_id": "PJ0MRSHTDG",
	"properties": {
		"rating": ["score", "comment"]
		},
		// ...
	}
}
Specifics
Actionchat_properties_deleted
Webhook equivalentchat_properties_deleted
Push payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.

chat_thread_properties_updated

Sample push payload
{
  "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
ObjectNotes
propertiesThis is not a full properties object. This push shows only the properties the have been recently updated.

chat_thread_properties_deleted

Sample push payload
{
	"chat_id": "PJ0MRSHTDG",
	"thread_id": "K600PKZON8",
	"properties": {
		"rating": ["score", "comment"]
		},
		// ...
	}
}
Specifics
Actionchat_thread_properties_deleted
Webhook equivalentchat_thread_properties_deleted
Push payload
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.

event_properties_updated

Sample push payload
{
  "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
ObjectNotes
propertiesNot a full properties object. This push shows only the properties that have been recently updated.

event_properties_deleted

Sample push payload
{
	"chat_id": "PJ0MRSHTDG",
	"thread_id": "K600PKZON8",
	"event_id": "2_E2WDHA8A",
	"properties": {
		"rating": ["score", "comment"]
		},
		// ...
	}
}
Specifics
Actionevent_properties_deleted
Webhook equivalentevent_properties_deleted
Push payload
ObjectNotes
propertiesThis is not a full properties object. This push shows only the properties that have been recently updated.

Customers

customer_updated

Sample push payload
{
  "customer": {
    // "User > Customer" object
  }
}
Specifics
Actioncustomer_updated
Webhook equivalent-

customer_page_updated

Sample push payload
{
  "url": "https://livechatinc.com/pricing",
  "title": "pricing",
  "timestamp": 123456789
}
Specifics
Actioncustomer_page_updated
Webhook equivalent-

customer_side_storage_updated

Sample push payload
{
  "customer_side_storage": {
    "customer_visits": "1"
  }
}
Specifics
Actioncustomer_side_storage_updated
Webhook equivalent-
Push payload
ObjectNotes
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

Sample push payload
{
  "reason": "misdirected_connection",
  "data": {
    // optional
    "region": "fra"
  }
}
Specifics
Actioncustomer_disconnected
Webhook equivalent-
Push payload
ObjectNotes
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 error
license_not_foundThe license with the specified ID doesn't exist.
misdirected_connection **Customer connected to a server in the wrong region.
product_version_changedThe product version has changed.
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

Sample push payload
{
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "typing_indicator": {
    // "Typing indicator" object
  }
}
Specifics
Actionincoming_typing_indicator
Webhook equivalent-

incoming_multicast

Sample push payload
{
  "author_id": "agent1@example.com",
  "content": {
    "example": {
      "nested": "json"
    }
  }
}
Specifics
Actionincoming_multicast
Webhook equivalent-

last_seen_timestamp_updated

Sample push payload
{
  "user_id": "b7eff798-f8df-4364-8059-649c35c9ed0c",
  "chat_id": "PJ0MRSHTDG",
  "thread_id": "K600PKZON8",
  "timestamp": 123456789
}
Specifics
Actionlast_seen_timestamp_updated
Webhook equivalentlast_seen_timestamp_updated

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@livechatinc.com. We'll be happy to hear from you!