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
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
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.Related APIs
For a broader comparison, see Messaging APIs.
Pagination
Uselimit 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.