> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Customer Chat RTM API

> Keep a customer-facing chat interface connected to Text over WebSocket and receive conversation updates as they happen.

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:

&#x20;[Customer authorization](https://www.text.com/docs/authentication/customer-tokens.md)

&#x20;[API versioning](https://www.text.com/docs/key-concepts/api-versioning.md)

## 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](https://www.text.com/docs/api/customer-chat/v3.6.md) | Sends an HTTP request for each action. Use it for stateless integrations where some response latency is acceptable. | [Webhooks](https://www.text.com/docs/api/webhooks/v3.6.md) |
| RTM API | Maintains a WebSocket connection. Use it when a customer interface needs conversation changes as they happen. | [Pushes](https://www.text.com/docs/api/customer-chat/v3.6/rtm/pushes.md) |

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:

| Endpoint | Query parameter |
| - | - |
| `wss://api.livechatinc.com/v3.6/customer/rtm/ws` | `organization_id` (string) |

### Message format

Requests and responses use a standard JSON structure.

```json title="Request" theme={null}
{
  "action": "<action>",
  "request_id": "<request_id>",
  "payload": {}
}
```

```json title="Response" theme={null}
{
  "request_id": "<request_id>",
  "action": "<action>",
  "type": "response",
  "success": true,
  "payload": {}
}
```

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](https://www.text.com/docs/api/customer-chat/v3.6/rtm/status.md#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:

```json title="Ping request" theme={null}
{
  "action": "ping",
  "payload": {}
}
```

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](https://tools.ietf.org/html/rfc6455#section-5.5.2). 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](https://www.text.com/docs/api/customer-chat/v3.6/rtm/data-structures.md).

| Resource | Description |
| - | - |
| [Chats](https://www.text.com/docs/api/customer-chat/v3.6/rtm/chats.md) | Access the authenticated customer's chat history. Start, resume, or deactivate chats, and retrieve their threads. |
| [Events](https://www.text.com/docs/api/customer-chat/v3.6/rtm/events.md) | Send messages, rich message postbacks, and message previews. You can also delete events sent through the customer interface. |
| [Properties](https://www.text.com/docs/api/customer-chat/v3.6/rtm/properties.md) | Manage custom properties attached to chats, threads, and events. |
| [Customers](https://www.text.com/docs/api/customer-chat/v3.6/rtm/customers.md) | Access and update the authenticated customer's profile and session fields. Report page changes so Text can update the customer's group assignment. |
| [Status](https://www.text.com/docs/api/customer-chat/v3.6/rtm/status.md) | Authorize the connection, provide its initial customer context and push subscriptions, and check the availability of groups the customer can access. |
| [Other](https://www.text.com/docs/api/customer-chat/v3.6/rtm/other.md) | Supports customer-side interactions outside the main resources, including forms, predicted agents, URL information, read state, greetings, and welcome messages. |

## Related APIs

| If you need to | Use |
| - | - |
| Interact as a customer without maintaining a WebSocket connection | [Customer Chat Web API](https://www.text.com/docs/api/customer-chat/v3.6.md) |
| Interact with conversations as an agent over WebSocket | [Agent Chat RTM API](https://www.text.com/docs/api/agent-chat/v3.6/rtm.md) |
| Issue, inspect, transfer, or revoke customer access tokens | [Customer Accounts API](https://www.text.com/docs/api/customer-accounts.md) |
| Customize the standard Chat Widget without building a new interface | [Chat Widget JavaScript API](https://www.text.com/docs/api/chat-widget-js-api.md) |

For a broader comparison, see [Messaging APIs](https://www.text.com/docs/api-overview/messaging-apis.md).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.