This document is dedicated to a set of Messaging APIs, which consists of the Agent Chat API, Customer Chat API, and the Configuration API. It also explains some key concepts, such as the definition of a chat and a thread, the flow between services, or chat routing. Understanding them is a prerequisite to the efficient usage of our APIs.
This document is a great starting point if you plan on using our APIs. You'll learn what use cases can be covered with each API. For hands-on examples, we encourage you to check the documentation specific to each API.
By looking at the chat structure, you notice that each chat is is divided into threads. Every thread contains events, for example sent messages. You can think of a chat as a whole conversation, while threads are separate conversation topics.
Consider the example of an online store. A customer starts a chat to ask about the shoes he bought. If he hasn't got any previous chat history, a new chat is started. Within this chat, a new thread is created (conversation topic). The messages he exchanges with the customer service assistant are received by the thread as events. After solving the problem, the customer says goodbye and closes the chat, which automatically closes the thread. Let's say the customer is rude and leaves without saying goodbye. In this case, the thread closes after 30 minutes of inactivity (time periods are configurable). The chat doesn't end, though.
The next day, customer returns to ask about his other purchase. A new thread starts in the context of the chat, which has been continuously open. Each time customer returns and starts a new conversation topic, he needs to click start a chat. If we stuck to our naming convention, that would have to be start a thread, because this is what he actually does behind the scenes.
A message or rich message are not the only event types, though. There are also special events for specific actions, like: file, filled form, system and custom messages.
Here are some general rules, which summarize the previous section and add new info.
When a new chat is started, a new active thread is created within this chat. New threads within a single chat are created on the server side.
There's always only one active thread. Only the last thread can be the active one. Events are always added to the active thread.
There can be time gaps between threads in a chat, but once a chat is started, it's continuously open.
Messages are sent and delivered even when the recipient (both Customer and Agent) is offline.
Multiple Agents can participate in a single chat.
The algorithm that decides how chats are distributed between Agents is called routing. It's documented in the Routing section.
Routing is the process of assigning chats to agents. The primary goal of the routing mechanism is to distribute chats to all available agents who use the same license.
Chats are being assigned to agents either automatically or manually. Our default routing mechanisms are described in Understanding chat routing.
Watch a short video that illustrates the basic flow between services in LiveChat.
For more technical details, analyze the diagrams and read the descriptions below.
The LiveChat communication protocol uses websockets (RTM API). They act like tubes that connect two sides and enable transport between them. In the basic model of the LiveChat services, there are two websocket connections:
- Agent App and the LiveChat's backend
- the LiveChat's backend and Chat Widget
The first connection allows for sending an event, for example, a message, by an agent to the LiveChat's backend. The
send_event action triggers the LiveChat's backend to generate a push. The
incoming_event push is sent to the Chat Widget via the other websocket. The push contains the message written by the agent.
Apart from pushes, actions can also trigger the LiveChat's backend to generate webhooks. To receive a webhook, you need to register it first. That's how you let the LiveChat's backend know you want to be notified about certain actions. The LiveChat's backend will send webhooks to the target webhook URL you specify during webhook registration.
Developers can build integrations that extend LiveChat's messaging capabilities, for example, via a new communication channel. Consider the example of the integration app that connects LiveChat with Facebook Messenger. Keep in mind the flow presented in the diagram below is typical for a new communication channel and it would be different for an app that simply extends the LiveChat UI.
An Agent sends a message via a websocket connection. It triggers the LiveChat's backend to send a webhook to the integration app, informing about the incoming event. In response to the webhook, the integration sends an HTTP request to the external backend (in this case it's Facebook). They use transport of their choice to pass the message to the Customer chatting via Facebook Messenger.
There are two primary Chat APIs:
- Agent Chat API, which serves to join a chat as Agent.
- Customer Chat API, which serves to join a chat as Customer.
The separation of Chat APIs helps you decide which set of methods you should use. It depends on the role of the chat user. Want to join a chat as Agent? Refer to the Agent Chat API. Want to send messages as Customer? Use the Customer Chat API.
To use both APIs, you need to be authorized. This topic is thoroughly explained in the Authorizing API calls document.
Agent Chat API and Customer Chat API can be used either as Real-Time Messaging APIs (RTM APIs) or Web APIs.
To learn about differences between these two API types, see the comparison below:
|Characteristics||RTM API||Web API|
|connection type||stateful e.g. websocket||stateless, via XHR requests|
|finds out about state changes via||pushes||webhooks|
|used by||Agent App, Chat Widget||external apps, integrations|
|documentation||Agent Chat RTM API & Customer Chat RTM API||Agent Chat Web API & Customer Chat Web API|
If you're not sure, which implementation to choose, we suggest reading about particular APIs. You'll find the When to use RTM/Web API section in each document - refer to the table above for links.
The LiveChat Messaging API adopts the following versioning convention:
The latest stable version we encourage developers to use. We don't introduce any new functionalities or breaking changes - only bug fixes are expected.
developer preview (dev preview)
The unstable version giving you a preview of new features. You should never use it for your production apps as it's subject to breaking change. Recommended for experimental use.
The old version we still support but highly encourage you to switch to the latest stable version.
|Agent Chat API||Customer Chat API||Configuration API|
|legacy||3.1, 3.2||3.1, 3.2||2.0, 3.1, 3.2|
The Agent Chat API allows for:
- interactions with the chat as Agent (joining a chat, posting messages)
- interact with the chat by Bot Agents (acting as Agents)
- building a custom Agent App
- browsing chat archives
- banning Customers
- and much more
The number of chats an Agent can participate in is not limited. It can be configured in the Agent App by the license Owner or Admin.
The Customer Chat API allows for:
- interacting with the chat as Customer (join a chat, post messages)
- building a custom Chat Widget
- implementing new conversation channels (Facebook Messenger or Twitter)
By default, a Customer can only have one chat started, unless he chats with Agents who use different licences. The licence Owner or Admin can change that default value, modifying the
routing.max_customer_chats_count property. However, in order to support this functionality, you would need to build a custom Chat Widget. For now, the LiveChat Chat Widget doesn't support it. You can build a Chat Widget from the ground up using the Chat Widget Customer SDK.
Chats are continuous so Customers can always preview their chats' history. Yet, with multiple concurrent chats Customers can sort their chats out thematically, making sure they know what each chat is about.
The Configuration API allows for:
- storing license configurations
- creating chat, thread, and event properties
- managing webhooks, for example registering and unregistering
- managing Bots, for example creating and removing
In the near future, it will allow for groups configuration. For now, refer to Configuration API v2 to manage groups properties.
Properties are key-value storages. They can be set within a chat, a thread, or an event. You can create properties within a license and configure them using the Configuration API. It's possible to configure the property type, location, and domain.
In general, actions invoked by the use of Messaging APIs result in events. You can be notified about those events with webhooks. LiveChat provides a number of webhooks, which you can register and manage via the Configuration API.
We distinguish global webhooks and bot-specific webhooks. Once global webhooks are set up, you will always receive them. Bot-specific webhooks are strongly coupled with the bot's status (
not accepting chats,
offline). If the bot is offline, webhooks won't be received.
Webhook equivalents in the websocket transport (RTM API) are pushes.
Bots are similar to their human counterparts. They can join chats and post messages, but they also have a special feature: you can attach webhooks to them.
Bots are authorized with the use of the Agent's token. Using Bots requires sending the
X-Author-Id header for the Web API Reference and the
author_id property for the websocket connection.
They can listen for incoming webhooks (or pushes) and react to them.
If you still can't find the answer you're looking for, don't hesitate to contact us at email@example.com! We're also open for you suggestions and feedback on the document itself.