Resources/The Agent API Atlas/Support/LiveChat

Everything an AI agent can do with the LiveChat API.

A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.

Endpoints36

API versionv3.5

Last updated23 June 2026

Orientation

How the LiveChat API works.

The LiveChat API is how an app or AI agent works with a LiveChat account: listing and reading live chats, sending a reply into a conversation, transferring or ending a chat, and reading or updating customers and agents. Access is granted through a token and a set of scopes that decide what each call can read or write, and an agent is limited to the chats and accounts those scopes reach. The API is split into a messaging side for conversations and a configuration side for agents and groups, and it can push events to a webhook when something happens.

36Endpoints

10Capability groups

11Read

25Write

16Permissions

Authentication

Every call needs a token in an Authorization header. Two kinds exist: an OAuth 2.1 Bearer access token for an app acting on behalf of a user, which carries only the scopes the app declared and the user granted, and a Personal Access Token generated per agent, sent with the Basic scheme as base64-encoded credentials, for quick calls and testing. There is no anonymous access to the agent-side API.

Permissions

Access is governed by granular scopes. The chat scopes come in two reaches: chats--access:ro and chats--access:rw cover only chats the requester has access to, while chats--all:ro and chats--all:rw cover every chat on the license. Other areas have their own scopes, such as customers:ro and customers:rw, agents--all:ro and agents--all:rw, groups--all:ro and groups--all:rw, tags--all:ro and tags--all:rw, and webhooks--all:ro and webhooks--all:rw. Creating an agent needs the broader accounts--all:rw scope, and banning a customer needs customers.ban:rw.

Versioning

LiveChat carries one dated version string in the request path, such as v3.5 or v3.6. The newest stable version is v3.6, released on 7 August 2025, and v3.5, released on 23 November 2022, stays supported alongside it. An integration pins one version in the URL and migrates when it chooses to, rather than being moved automatically.

Data model

The API has two sides. The messaging side, the Agent Chat API, works with chats, the threads inside them, and the events inside those, and is reached over a stateless Web API or a persistent RTM websocket. The configuration side, the Configuration API, manages agents, groups, tags, properties, and webhooks. A chat groups one or more threads, each thread holds events such as messages, and webhooks push these same actions to a receiver URL.

Connect & authenticate

Connection & authentication methods.

How an app or AI agent connects to LiveChat determines what it can reach. There are a few routes, each governed by the token behind it and the scopes that token carries.

Ways to connect

Web API

The Web API is the stateless route, where each method is a POST to its action path, such as /agent/action/send_event. It suits an app or AI agent that calls LiveChat on demand without holding a connection open.

Best forOn-demand calls from an app or AI agent.

Governed byThe token and the scopes it carries.

Docs ↗

RTM API (websocket)

The RTM API holds a websocket connection open, so the same methods are sent over a persistent socket and incoming events arrive as pushes on the same connection. It suits a live agent application that needs realtime updates.

Best forRealtime agent applications.

Governed byThe token and the scopes it carries.

Docs ↗

Webhooks

Webhooks deliver the actions that have been registered to a receiver URL over the Web API route, so a stateless integration is notified of events without holding a socket open.

Best forNotifying a stateless integration of events.

Governed byThe token and the scopes it carries.

Docs ↗

MCP server (Model Context Protocol)

Text, the company behind LiveChat, hosts a remote MCP server at https://mcp.text.com/ that lets an AI assistant call LiveChat through the Model Context Protocol. It exposes search and fetch, chat transcript and tag tools, and ticket tools, all bounded by the signed-in user's existing scopes. Claude and ChatGPT connect to it directly.

Best forConnecting an AI assistant to LiveChat.

Governed byThe signed-in user's identity and existing account scopes.

Docs ↗

Authentication

OAuth 2.1

An app obtains a Bearer access token through one of the OAuth flows, sign in with LiveChat, the authorization code grant for server-side apps, or the implicit grant for browser apps. The token carries only the scopes declared for the app and granted by the user.

TokenOAuth Bearer access token

Best forApps acting on behalf of a user

Docs ↗

Personal Access Token

A Personal Access Token is generated per agent and sent with the Basic authentication scheme, where the credentials are base64 encoded. It suits a quick call or testing an app under construction, tied to that one agent's permissions.

TokenPersonal Access Token (Basic auth)

Best forQuick calls and testing

Docs ↗

Capability map

What an AI agent can do in LiveChat.

The LiveChat API is split into areas an agent can act on, such as live chats, the events inside them, customers, agents, and groups. Each area has its own methods and its own scopes, and some grant access to far more than others.

Chats

7 endpoints

List and read chats and their threads, start and resume a chat, deactivate a chat, and read archived chats.

Writes here start or end real customer conversations.

View endpoints →

Events & messages

3 endpoints

Send a message or other event into a chat, send a rich-message postback, and preview an event before sending.

Writes here post visible messages to a customer.

View endpoints →

Chat access & users

3 endpoints

Transfer a chat to another agent or group, and add or remove a user from a chat.

Writes here move conversations between agents.

View endpoints →

Chat properties & tags

3 endpoints

Update or delete the custom properties on a chat, thread, or event, and tag or untag a thread.

Writes here change stored metadata on a conversation.

View endpoints →

Customers

3 endpoints

Read a customer, update a customer's details, and ban a customer.

Writes here change or block customer records.

View endpoints →

Agents

5 endpoints

Create, read, list, update, and delete the agents on a license.

Writes here change who can staff the help desk.

View endpoints →

Groups

4 endpoints

Create, read, list, update, and delete the groups that route chats.

Writes here change how chats are routed.

View endpoints →

Webhooks

3 endpoints

Writes here change where account events are sent.

View endpoints →

Tags & properties (config)

3 endpoints

Create, list, update, and delete the tags and custom properties defined for a license.

Writes here change the tags and fields available account-wide.

View endpoints →

Routing status

2 endpoints

Set an agent's routing status to accepting or not accepting chats, and list current routing statuses.

Writes here change whether an agent receives chats.

View endpoints →

Endpoint reference

Every LiveChat API method.

Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.

Hide deprecated

Method	Endpoint	What it does	Access	Permission	Version
Chats List and read chats and their threads, start and resume a chat, deactivate a chat, and read archived chats.7
POST	`/agent/action/list_chats`	List chats a requester has access to.	read	`chats--all:ro`	Current
chats--access:ro limits this to chats the requester has access to, where chats--all:ro covers every chat on the license. Acts onchat Permission (capability)`chats--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/list_threads`	List the threads within a single chat.	read	`chats--all:ro`	Current
chats--access:ro restricts the result to threads the requester can access. Acts onthread Permission (capability)`chats--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/get_chat`	Get a single chat, including its events.	read	`chats--all:ro`	Current
Validates access to the requested thread. chats--access:ro suffices for a chat the requester can reach. Acts onchat Permission (capability)`chats--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/list_archives`	List archived chats, with filters such as date range and customer country.	read	`chats--all:ro`	Current
chats--access:ro limits archives to chats the requester had access to. Acts onarchive Permission (capability)`chats--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/start_chat`	Start a new chat, optionally with initial events.	write	`chats--all:rw`	Current
An optional active parameter sets whether the new chat starts active. chats--access:rw also works. Acts onchat Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`incoming_chat` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/resume_chat`	Resume a chat that has been deactivated.	write	`chats--all:rw`	Current
Takes the same optional active parameter as start_chat. chats--access:rw also works. Acts onchat Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`incoming_chat` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/deactivate_chat`	Deactivate a chat, which ends the active conversation.	write	`chats--all:rw`	Current
The chat identifier is sent as id. chats--access:rw also works. Acts onchat Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`chat_deactivated` Rate limitStandard limits apply SourceOfficial documentation ↗
Events & messages Send a message or other event into a chat, send a rich-message postback, and preview an event before sending.3
POST	`/agent/action/send_event`	Send an event, such as a message, into a chat.	write	`chats--all:rw`	Current
Posts a visible message or other event to the customer. chats--access:rw also works. Acts onevent Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`incoming_event` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/send_event_preview`	Send a preview of an event so the customer sees it being composed.	write	`chats--all:rw`	Current
A preview is not stored as a sent message. chats--access:rw also works. Acts onevent Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/send_rich_message_postback`	Send a postback for a rich message button the customer interacted with.	write	`chats--all:rw`	Current
Used with interactive rich-message cards. chats--access:rw also works. Acts onevent Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`incoming_rich_message_postback` Rate limitStandard limits apply SourceOfficial documentation ↗
Chat access & users Transfer a chat to another agent or group, and add or remove a user from a chat.3
POST	`/agent/action/transfer_chat`	Transfer a chat to another agent or group.	write	`chats--all:rw`	Current
Can be used with inactive chats as well as active ones. chats--access:rw also works. Acts onchat Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`chat_transferred` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/add_user_to_chat`	Add an agent or customer to a chat.	write	`chats--all:rw`	Current
chats--access:rw also works. Acts onchat user Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`user_added_to_chat` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/remove_user_from_chat`	Remove an agent or customer from a chat.	write	`chats--all:rw`	Current
chats--access:rw also works. Acts onchat user Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`user_removed_from_chat` Rate limitStandard limits apply SourceOfficial documentation ↗
Chat properties & tags Update or delete the custom properties on a chat, thread, or event, and tag or untag a thread.3
POST	`/agent/action/update_chat_properties`	Update the custom properties stored on a chat.	write	`chats--all:rw`	Current
Properties are namespaced custom fields stored on the chat. chats--access:rw also works. Acts onchat property Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`chat_properties_updated` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/tag_thread`	Add a tag to a thread.	write	`chats--all:rw`	Current
The tag must already exist on the license, defined through the Configuration API. chats--access:rw also works. Acts onthread tag Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`thread_tagged` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/untag_thread`	Remove a tag from a thread.	write	`chats--all:rw`	Current
chats--access:rw also works. Acts onthread tag Permission (capability)`chats--all:rw` VersionAvailable since the API’s base version Webhook event`thread_untagged` Rate limitStandard limits apply SourceOfficial documentation ↗
Customers Read a customer, update a customer's details, and ban a customer.3
POST	`/agent/action/get_customer`	Get a single customer's details.	read	`customers:ro`	Current
Returns customer profile and session fields. Acts oncustomer Permission (capability)`customers:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/update_customer`	Update a customer's details.	write	`customers:rw`	Current
Changes the stored customer record. Acts oncustomer Permission (capability)`customers:rw` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/ban_customer`	Ban a customer for a set number of days.	write	`customers.ban:rw`	Current
Banning blocks the customer from starting new chats for the given period. Acts oncustomer Permission (capability)`customers.ban:rw` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Agents Create, read, list, update, and delete the agents on a license.5
POST	`/configuration/action/create_agent`	Create an agent on the license.	write	`accounts--all:rw`	Current
Creating an agent does not activate it; LiveChat sends an invitation email. Creation needs the accounts--all:rw scope, broader than the agents--all:rw used by the other agent methods. Acts onagent Permission (capability)`accounts--all:rw` VersionAvailable since the API’s base version Webhook event`agent_created` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/get_agent`	Get a single agent's configuration.	read	`agents--all:ro`	Current
Acts onagent Permission (capability)`agents--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/list_agents`	List the agents on the license, with an optional suspended filter.	read	`agents--all:ro`	Current
Acts onagent Permission (capability)`agents--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/update_agent`	Update an agent's configuration.	write	`agents--all:rw`	Current
Acts onagent Permission (capability)`agents--all:rw` VersionAvailable since the API’s base version Webhook event`agent_updated` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/delete_agent`	Delete an agent from the license.	write	`agents--all:rw`	Current
Acts onagent Permission (capability)`agents--all:rw` VersionAvailable since the API’s base version Webhook event`agent_deleted` Rate limitStandard limits apply SourceOfficial documentation ↗
Groups Create, read, list, update, and delete the groups that route chats.4
POST	`/configuration/action/create_group`	Create a group that routes chats to a set of agents.	write	`groups--all:rw`	Current
Acts ongroup Permission (capability)`groups--all:rw` VersionAvailable since the API’s base version Webhook event`group_created` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/list_groups`	List the groups on the license.	read	`groups--all:ro`	Current
Acts ongroup Permission (capability)`groups--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/update_group`	Update a group's configuration.	write	`groups--all:rw`	Current
Acts ongroup Permission (capability)`groups--all:rw` VersionAvailable since the API’s base version Webhook event`group_updated` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/delete_group`	Delete a group from the license.	write	`groups--all:rw`	Current
Acts ongroup Permission (capability)`groups--all:rw` VersionAvailable since the API’s base version Webhook event`group_deleted` Rate limitStandard limits apply SourceOfficial documentation ↗
Webhooks Register, list, and unregister the webhooks that push events to a receiver URL.3
POST	`/configuration/action/register_webhook`	Register a webhook so LiveChat pushes a chosen action to a receiver URL.	write	`webhooks--all:rw`	Current
Webhooks are registered for a client ID and then enabled per license. Registering through this method is equivalent to configuring webhooks in the Developer Console. Acts onwebhook Permission (capability)`webhooks--all:rw` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/list_webhooks`	List the webhooks registered for the client.	read	`webhooks--all:ro`	Current
Acts onwebhook Permission (capability)`webhooks--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/unregister_webhook`	Unregister a webhook so LiveChat stops pushing its action.	write	`webhooks--all:rw`	Current
Acts onwebhook Permission (capability)`webhooks--all:rw` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Tags & properties (config) Create, list, update, and delete the tags and custom properties defined for a license.3
POST	`/configuration/action/create_tag`	Create a tag that agents can apply to threads.	write	`tags--all:rw`	Current
Tags must be defined here before tag_thread can apply them. Acts ontag Permission (capability)`tags--all:rw` VersionAvailable since the API’s base version Webhook event`tag_created` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/list_tags`	List the tags defined for the license.	read	`tags--all:ro`	Current
Acts ontag Permission (capability)`tags--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/configuration/action/register_property`	Register a custom property an integration can store on chats, threads, or events.	write	`properties--all:rw`	Current
Properties are owned by the client ID, not the license. A property must be registered and published before it can hold values. Acts onproperty Permission (capability)`properties--all:rw` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Routing status Set an agent's routing status to accepting or not accepting chats, and list current routing statuses.2
POST	`/agent/action/set_routing_status`	Set an agent's routing status, such as accepting or not accepting chats.	write	`agents--my:rw`	Current
agents--my:rw sets the requester's own status; agents--all:rw sets another agent's. Bot variants agents-bot--my:rw and agents-bot--all:rw apply to bots. Acts onrouting status Permission (capability)`agents--my:rw` VersionAvailable since the API’s base version Webhook event`routing_status_set` Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/agent/action/list_routing_statuses`	List the current routing statuses of agents.	read	`agents--all:ro`	Current
Listing bot statuses additionally needs agents-bot--all:ro. Acts onrouting status Permission (capability)`agents--all:ro` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗

No endpoints match those filters.

Webhooks

Webhook events.

LiveChat can notify an app or AI agent when something happens in an account, instead of the app repeatedly asking. LiveChat posts the event payload to a webhook URL that has been registered for the chosen actions.

Event	What it signals	Triggered by
`incoming_chat`	Fires when a new chat starts, and carries the initial events of the chat.	`/agent/action/start_chat` `/agent/action/resume_chat`
`incoming_event`	Fires when a new event, such as a message, occurs in a chat, and carries its content.	`/agent/action/send_event`
`incoming_rich_message_postback`	Fires when a customer interacts with a rich-message button, sending a postback.	`/agent/action/send_rich_message_postback`
`chat_deactivated`	Fires when a chat is deactivated, which ends the active conversation.	`/agent/action/deactivate_chat`
`chat_transferred`	Fires when a chat is transferred to another agent or group.	`/agent/action/transfer_chat`
`user_added_to_chat`	Fires when an agent or customer is added to a chat.	`/agent/action/add_user_to_chat`
`user_removed_from_chat`	Fires when an agent or customer is removed from a chat.	`/agent/action/remove_user_from_chat`
`chat_properties_updated`	Fires when the custom properties on a chat are updated.	`/agent/action/update_chat_properties`
`thread_tagged`	Fires when a tag is added to a thread.	`/agent/action/tag_thread`
`thread_untagged`	Fires when a tag is removed from a thread.	`/agent/action/untag_thread`
`routing_status_set`	Fires when an agent's routing status changes.	`/agent/action/set_routing_status`
`agent_created`	Fires when an agent is created on the license.	`/configuration/action/create_agent`
`agent_updated`	Fires when an agent's configuration is updated.	`/configuration/action/update_agent`
`agent_deleted`	Fires when an agent is deleted from the license.	`/configuration/action/delete_agent`
`group_created`	Fires when a group is created.	`/configuration/action/create_group`
`group_updated`	Fires when a group is updated.	`/configuration/action/update_group`
`group_deleted`	Fires when a group is deleted.	`/configuration/action/delete_group`
`tag_created`	Fires when a tag is created for the license.	`/configuration/action/create_tag`

No events match that search.

Rate limits & pagination

Rate limits, pagination & request size.

LiveChat limits how fast an app or AI agent can call, through a per-license request quota shared across every token and integration on that license, and returns a too_many_requests error once the quota is spent.

Request rate

LiveChat caps how fast an app or AI agent can call through a request quota tied to the license, and that quota is shared across every token and integration on the same license, so several agents drawing on one license draw down the same allowance. Exceeding it returns a too_many_requests error, at which point the caller should back off and spread requests over time rather than bursting. LiveChat does not publish the exact request-per-window figure in its developer reference, so an integration should read the rate-limit response headers and retry after the period they indicate.

Pagination

List methods page through a limit parameter, which defaults to 10 and tops out at 100, and a page_id that points at the next page. A response returns next_page_id and previous_page_id when more pages exist, and those page identifiers stay valid for up to one month before they have to be regenerated.

Request size

Requests and responses are JSON. Uploaded files go through a separate upload_file method rather than being inlined into an event, and individual list methods cap a page at 100 records through the limit parameter.

Errors

Status codes & error handling.

The status codes an agent should handle, and what to do about each.

Status	Code	Meaning	What to do
200	`authentication`	The access token is missing, invalid, or expired. LiveChat returns the error in a JSON body with an error object holding a type, a message, and optional data, rather than only in the HTTP status.	Refresh or reissue the token, then resend the request with a valid Authorization header.
200	`authorization`	The token is valid but its scopes do not allow the action, such as calling a chats--all method with only chats--access granted.	Grant the missing scope to the app, or call a method the current scopes allow.
200	`validation`	The request was malformed or a field was missing or invalid. The error message names the problem.	Correct the named field and resend.
200	`too_many_requests`	The request quota for the license was exceeded. The quota is shared across every token and integration on that license.	Back off and retry after a short wait, and spread calls across time rather than bursting.
200	`request_timeout`	The request exceeded the 15-second processing threshold before completing.	Retry the request, and narrow the work if it is a large query.
200	`internal`	An unexpected server-side error occurred while handling the request.	Retry after a short wait, and contact support if it persists.

Versioning & freshness

Version history.

LiveChat versions its APIs with a single dated version string in the request path. The newest stable version is v3.6, released on 7 August 2025, and v3.5 stays supported alongside it.

Version history

What changed, and when

Latest versionv3.5

v3.6

Current stable version

v3.6 is the newest stable version of the LiveChat APIs. It added chat access validation and new filters for listing archives, renamed chat summary to chat info, expanded customer data with carts and omnichannel support, added system and deleted event types, introduced thread summaries with auto-summarization, moved bot authorization to tokens instead of an author-id header, and added thinking indicators. It was released on 7 August 2025.

What changed

Chat access validation and new archive listing filters
Chat summary renamed to chat info
Customer data expanded with carts, properties, and omnichannel support
New system and deleted event types with matching pushes
Thread summaries with auto-summarization
Bot authorization moved to tokens, replacing the author-id header
Thinking indicators and error pushes

v3.5Current version

Previous stable version

v3.5 added new archive filters including customer countries, removed the older push-notification configuration methods, and introduced tag management pushes for created, updated, and deleted tags. A follow-up on 7 December 2022 added thread access validation. It was released on 23 November 2022 and remains supported.

What changed

New archive filters including customer countries
Removed push-notification configuration methods
Added tag_created, tag_updated, and tag_deleted pushes
Thread access validation added on 7 December 2022

v3.4

Deletion pushes and configuration integration

v3.4 added deletion-related pushes for chats and threads, richer archive filtering with event-type modifiers, and Configuration API integration with agent and bot pushes. It was released on 22 December 2021.

What changed

New deletion pushes for chats and threads
Archive filtering with event-type modifiers
Configuration API integration with agent and bot pushes

An integration pins one version in the URL and moves up when it chooses to.

LiveChat API changelog ↗

Questions

LiveChat API, answered.

What is the difference between the chats--access and chats--all scopes?+

Both govern chat methods, but they reach different sets of chats. A chats--access scope, read-only or read-write, lets an app act only on chats the requester already has access to, such as chats assigned to that agent. A chats--all scope reaches every chat on the license. For a least-privilege agent that should only handle its own conversations, chats--access is the tighter choice; chats--all is needed to read or act across the whole help desk.

What is the difference between the Web API and the RTM API?+

They expose the same methods through different transports. The Web API is stateless: each method is a single POST to its action path, which suits an app or AI agent that calls LiveChat on demand. The RTM API holds a websocket open, so methods are sent over a persistent connection and incoming events, like a new message, arrive as pushes on that same socket. A realtime agent application uses RTM; a webhook-driven or on-demand integration uses the Web API.

How does authentication work, OAuth or a Personal Access Token?+

Both are supported. OAuth 2.1 issues a Bearer access token for an app acting on behalf of a user, carrying only the scopes the app declared and the user granted, and is the route for a published integration. A Personal Access Token is generated per agent and sent with Basic auth as base64-encoded credentials; it is meant for quick calls and testing, tied to that one agent's permissions. Both are sent in the Authorization header.

How does an app receive events instead of polling?+

Through webhooks. An app registers a webhook for a specific action, such as incoming_chat, incoming_event, chat_deactivated, or thread_tagged, and LiveChat posts the event payload to the receiver URL when that action happens. Webhooks are registered for a client ID and then enabled per license. This is more efficient than repeatedly calling list_chats or get_chat to check for changes.

Why did my call return an error with an HTTP 200?+

The Agent Chat API reports method errors in the response body, not only through the HTTP status. A failed call returns a JSON object with an error field holding a type, such as authentication, authorization, validation, too_many_requests, request_timeout, or internal, plus a message and optional data. An integration should check for that error object rather than relying on the status code alone.

Which version should an integration use, v3.5 or v3.6?+

v3.6 is the newest stable version, released on 7 August 2025, and is the recommended choice for a new integration. v3.5, released on 23 November 2022, remains supported, so an existing integration on v3.5 does not have to migrate immediately. The version is pinned in the request path, so moving up is a deliberate change rather than something LiveChat does automatically.

What is Bollard AI?

Control what every AI agent can do in LiveChat.

Bollard AI sits between a team's AI agents and LiveChat. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.

Set read, write, or full access per agent, never a shared LiveChat token.
Denied by default, so an agent reaches only what has been explicitly allowed.
Every call recorded in plain English: who, what, where, and the decision.

Control LiveChat access in Bollard Browse all APIs →

LiveChat

Support Agent

Read live chats ResourceOffReadFull use

Reply in a chat ActionOffReadFull use

Manage agents & groups ResourceOffReadFull use

Per-agent access, set in Bollard AI, not in LiveChat

How the LiveChat API works.

Connection & authentication methods.

Web API

RTM API (websocket)

Webhooks

MCP server (Model Context Protocol)

OAuth 2.1

Personal Access Token

What an AI agent can do in LiveChat.

Chats

Events & messages

Chat access & users

Chat properties & tags

Customers

Agents

Groups

Webhooks

Tags & properties (config)

Routing status

Every LiveChat API method.

Chats

Events & messages

Chat access & users

Chat properties & tags

Customers

Agents

Groups

Webhooks

Tags & properties (config)

Routing status

Webhook events.

Rate limits, pagination & request size.

Request rate

Pagination

Request size

Status codes & error handling.

Version history.

What changed, and when

LiveChat API, answered.

More support API guides for agents

Gorgias

Dixa

Zendesk

Freshdesk

Crisp

Intercom

Control what every AI agent can do in LiveChat.