Using the Agent Chat API - Text Documentation

The Agent Chat API gives you programmatic access to everything that happens in your Text conversations. Use it to build automations, connect chat to your internal tools, create custom agent interfaces, or deploy bots that handle routine requests.

Before you start

For access requirements and version support, see:

Authorization
Scopes
API versioning

Choose Web API or RTM API

The Agent Chat API is available as a Web API and an RTM API. Choose between them based on how your integration connects and receives updates.

API	Connection and use	Event delivery
Web API	Sends an HTTP request for each action. Use it for stateless integrations and bots.	Webhooks
RTM API	Maintains a WebSocket connection. Use it when an agent interface needs conversation changes as they happen.	Pushes

Agent Chat resources

The Agent Chat Web API resources cover operations that agents and bots can perform when working with customer conversations. For shared chat, thread, event, and user objects, see the Agent Chat API data structures.

Resource	Description
Chats	Access chat history and manage the lifecycle of chats and threads. Following a chat lets an agent receive its updates without joining it.
Chat access	Transfer an active chat to another agent or group.
Chat users	Add or remove participants from active chats.
Events	Send messages, files, rich message postbacks, and message previews to chats.
Properties	Manage custom properties attached to chats, threads, and events.
Thread tags	Apply or remove tags on individual threads. Manage the available tags through the Configuration API.
Customers	Access and update customer data associated with a conversation, inspect segment memberships, or temporarily prevent the customer from connecting.
Status	Control whether an agent or bot accepts chats and inspect agent routing status.
Other	Covers conversation actions outside the other resource groups, including read state, activity indicators, transfer candidates, multicast messages, and thread summaries.

If you need to	Use
Interact with a conversation as a customer	Customer Chat API
Manage agents, bots, groups, tags, and other organization settings	Configuration API
Store customer data from external systems for agents to use during conversations	Customer Data Platform API

For a broader comparison, see Messaging APIs.

Calling the API as a bot

To call the Agent Chat API as a bot, use a bot token created with Issue Bot Token. This authenticates the request as the bot, letting it interact with the API. Bots can only use the Web API.

Rate limits

Method calls are rate-limited. If you exceed a limit, requests return a Too many requests error until the limit resets.

Pagination

Use limit to control the page size and sort_order to return the oldest or newest records first. Provide any filters in the first request. The response contains next_page_id and, where supported, previous_page_id. Pass the appropriate value as page_id to move forward or backward. The API reuses the original filters, limit, and sort_order, which can’t be provided along with page_id. Start a new pagination request to change them. The page_id token expires after 1 month.

​Before you start

​Choose Web API or RTM API

​Agent Chat resources

​Related APIs

​Calling the API as a bot

​Rate limits

​Pagination