Using the Customer Chat API - Text Documentation

Use the Customer Chat API to build a custom customer-side chat experience. Every request is authenticated as the customer identified by the customer access token, so the API only exposes chats and data available to them.

Before you start

For customer access requirements and API version support, see:

Customer authorization
API versioning

Choose Web API or RTM API

The Customer 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 where some response latency is acceptable.	Webhooks
RTM API	Maintains a WebSocket connection. Use it when a customer interface needs conversation changes as they happen.	Pushes

Customer Chat resources

The Customer Chat Web API resources cover operations that a customer-facing interface can perform on behalf of a customer. For shared chat, thread, event, and user objects, see the Customer Chat API data structures.

Resource	Description
Chats	Access the authenticated customer’s chat history. Start, resume, or deactivate chats, and retrieve their threads.
Configuration	Retrieve the group configuration needed to build a customer chat interface. The dynamic configuration provides the version numbers needed to request configuration and localization data.
Events	Send messages, files, rich message postbacks, and message previews. You can also delete events sent through the customer interface.
Localization	Retrieve translated phrases for a customer chat interface based on its group, language, and configuration version.
Properties	Manage custom properties attached to chats, threads, and events. You can also read organization and group property values exposed to the customer.
Customers	Access and update the authenticated customer’s profile and session fields.
Status	Check the availability of groups the customer can access before starting or routing a chat.
Other	Supports customer-side interactions outside the main resources, including greetings, forms, read state, welcome messages, predicted agents, URL information, goals, and email verification.

If you need to	Use
Interact with conversations as an agent or bot	Agent Chat API
Issue, inspect, transfer, or revoke customer access tokens	Customer Accounts API
Customize the standard Chat Widget without building a new interface	Chat Widget JavaScript API

For a broader comparison, see Messaging APIs.

Pagination

Use limit to control the page size and sort_order to return the oldest or newest records first. 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 limit and sort_order, so those parameters 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

​Customer Chat resources

​Related APIs

​Pagination

Before you start

Choose Web API or RTM API

Customer Chat resources

Related APIs

Pagination