Skip to main content
The Customer Chat RTM API provides real-time access to the customer side of conversations over a persistent WebSocket connection. Your client sends request messages and receives responses, while Text can send pushes without a preceding request.

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. Some RTM-only interactions, such as incoming_typing_indicator, have no webhook equivalent.

Connect to the RTM API

To connect to the RTM API, open a WebSocket connection with the following endpoint and required query parameter:

Message format

Requests and responses use a standard JSON structure.
Request
Response
The request_id field is optional. Include the same value in a request to match it with the corresponding response.

Authorize the connection

Call Login with a customer access token within 30 seconds of opening the connection. Otherwise, Text closes the connection. You only need to authorize once while the connection remains open.

Server pinging

After authorization, ping the server every 15 seconds. Text closes the connection after about 30 seconds of inactivity. A ping sent before authorization has no effect.

Protocol message

Web applications and backend integrations can send a protocol message every 15 seconds:
Ping request
The server responds with the ping action, confirming that the connection is active.

WebSocket control frame

Backend integrations can instead send a WebSocket ping control frame. This option is unavailable in web browsers.

Customer Chat RTM resources

The Customer Chat RTM API resources cover operations that a customer-facing interface can perform while connected to Text over WebSocket. For shared chat, thread, event, and user objects, see the Customer Chat RTM API data structures. 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.