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

# Chats

> Text conversations are structured as chats, threads, and events. Understanding this model is the foundation for any Text API integration.

If you've used Text through the app, you already understand conversations intuitively — a customer writes in, an agent replies, the conversation closes. The API exposes the same thing, but as structured data. Understanding how that structure works is the foundation for building anything on top of Text.

Everything in the Text messaging system is built from four entities: **users**, **chats**, **threads**, and **events**. They nest inside each other like this:

> A **chat** contains **threads**. A **thread** contains **events**. **Users** participate in chats and create events.

## Chats

A chat is the persistent, ongoing record of a relationship between a customer and your team. It doesn't disappear when a conversation ends — it stays in history, ready to be continued.

A few things to know about chats:

* A customer can only have **one active chat at a time** on a given account. If they come back after a previous chat was closed, the same chat is resumed.
* A chat includes the list of users participating, when each user last saw it, and all of its threads.

## Threads

A thread is a single conversation session within a chat. When a chat starts, the first thread opens. When the chat is closed, the thread closes. When the customer comes back, a new thread opens inside the same chat.

This is what makes Text conversations feel continuous from the customer's side, while still giving your team clean, distinct session records for reporting and routing.

```
Chat (continuous)
├── Thread 1  ← first session, now closed
├── Thread 2  ← second session, now closed
└── Thread 3  ← current active session
```

## Events

An event is the smallest unit of content in a conversation. Every message sent, every system notification, every file shared — these are all events inside a thread. Each event records its type, content, author, and timestamp.

## Chat lifecycle

A chat moves through a simple set of states during its life.

<Steps>
  <Step title="Chat started" id="chat-started">
    A new chat is created — either by a customer opening the widget, or
    triggered by your systems via the API. The first thread opens automatically.
  </Step>

  <Step title="Chat active" id="chat-active">
    An agent (or bot) is handling the conversation. Events are being exchanged.
    The thread is open.
  </Step>

  <Step title="Chat deactivated" id="chat-deactivated">
    The current thread closes. The chat itself stays in history. The customer
    hasn't gone anywhere — the next time they reach out, the chat will be
    resumed.
  </Step>

  <Step title="Chat resumed" id="chat-resumed">
    The customer returns. A new thread opens inside the same chat. The full
    history from previous threads is still there.
  </Step>
</Steps>

<Accordion icon="code" title="Opening, closing, and resuming chats">
  Three methods manage the chat lifecycle:

  * [`start_chat`](/api/agent-chat/v3.6/chats/start-chat) — creates a new chat and its first thread, returning `chat_id`, `thread_id`, and `event_id`.
  * [`resume_chat`](/api/agent-chat/v3.6/chats/resume-chat) — reopens a closed chat and starts a new thread, returning the new `thread_id`.
  * [`deactivate_chat`](/api/agent-chat/v3.6/chats/deactivate-chat) — closes the current thread while leaving the chat itself in history.
</Accordion>

## APIs for the two sides of the conversation

Choose your API depending on which side of the conversation you're building on.

<CardGroup cols={2}>
  <Card title="Agent Chat API" icon="headset" href="/api/agent-chat/v3.6">
    For anything acting on the agent side — sending messages, closing chats,
    building bots, pulling chat history.
  </Card>

  <Card title="Customer Chat API" icon="user" href="/api/customer-chat/v3.6/">
    For building a custom chat experience from the customer's side — a branded
    widget, a mobile app, or a bridge to another channel.
  </Card>
</CardGroup>

Both those APIs come in two connection modes. The Web API is stateless — you make a request and get a response back. It's the right choice for most integrations: webhooks, automations, reporting tools, anything that reacts to events.

The RTM API keeps a persistent connection open and pushes updates to your client as they happen — it's built for live chat interfaces where latency matters.

***

**Keep exploring**

<p>
  <Icon icon="file" /> [Agent Chat API data
  structures](/api/agent-chat/v3.6/data-structures)

  <br />

  <Icon icon="file" /> [Customer Chat API data
  structures](/api/customer-chat/v3.6/data-structures)
</p>