> ## 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 and tickets

> Understand how chats, threads, events, and tickets connect and which identifiers and APIs retrieve each record.

Chats and tickets both record customer interactions, but they have different structures and lifecycles.

## Chat participants

Three types of users can participate in a chat:

> [card] Agents
>
> The people on your team. The app calls them teammates, while the APIs
> represent them as agents.

> [card] Customers
>
> The people your team talks to. Text can associate their records across
> browsers, devices, and channels.

> [card] Bots
>
> Automated participants that act on the agent side. A bot can send messages,
> close chats, and handle routing.

> [!NOTE]
>
> Bots here are an API-level concept: custom automated participants you connect
> to funnel messages from your own systems into a chat. This is different from
> [AI Agent](https://www.text.com/features/ai-agent/), which you set up and
> manage directly in the Text app.

## Chat structure

Four resources make up a chat: users, chats, threads, and events. A **chat** contains **threads**, a **thread** contains **events**, and **users** participate in the **chat** and create **events**.

![A chat contains threads, which contain events](https://mintcdn.com/text-56a1eab5/w6OUMq7cYmabTZh8/public/images/key-concepts/chat-structure-light.png?fit=max\&auto=format\&n=w6OUMq7cYmabTZh8\&q=85\&s=e34a0b85b3f320edf9caf83c4ac5fe2e)

### Chats

A chat is the container for an ongoing customer interaction. It stores participants, chat-level properties, and all of its threads.

A customer can have only one active chat in an organization. When the customer returns to chat after their conversation ended, the API opens and closes threads within that chat.

### Threads

A thread is one conversation session within a chat. Starting a chat creates its first thread. Deactivating the chat closes its currently active thread.

When the customer returns, Text resumes the deactivated chat and creates another thread in it.

```text theme={null}
Chat
├── Thread 1: completed session
├── Thread 2: completed session
└── Thread 3: active session
```

A transcript belongs to a thread. Reporting and routing can also operate on threads, so a chat ID and a thread ID answer different questions.

### Events

An event is one item within a thread, such as a message, file, form, or system activity. Each event has its own author, timestamp, type, and optional properties.

## Working with chats

### Chat lifecycle

The same chat appears through different reads as its state and your purpose change.

**1. Start a chat**

[Start chat](https://www.text.com/docs/api/agent-chat/v3.6/chats/start-chat.md) creates a chat and its
first thread. Store both the returned `chat_id` and `thread_id`.

**2. Work with the active chat**

Use [List chats](https://www.text.com/docs/api/agent-chat/v3.6/chats/list-chats.md) to retrieve chat
summaries available to the agent and [Get
chat](https://www.text.com/docs/api/agent-chat/v3.6/chats/get-chat.md) to retrieve a specific chat. Use
RTM pushes when an application must react as events arrive.

**3. Deactivate the chat**

[Deactivate chat](https://www.text.com/docs/api/agent-chat/v3.6/chats/deactivate-chat.md) closes the
active thread. The chat and completed thread remain available as history.

**4. Read historical sessions**

Use [List archives](https://www.text.com/docs/api/agent-chat/v3.6/chats/list-archives.md) to search the
archived view. Use
[`get_thread_transcript`](https://www.text.com/docs/api/agent-chat/v3.6/chats/get-thread-transcript)
when you need one session rather than the entire chat record.

**5. Resume the chat**

[`resume_chat`](https://www.text.com/docs/api/agent-chat/v3.6/chats/resume-chat) opens a new thread
in an existing chat. It does not create a second copy of the previous
thread.

`list_chats` returns chat summaries available to the agent. `list_archives` returns archived chats with one thread in each result.

### IDs for chats, threads, and events

Use the identifier for the resource that the operation acts on:

| You need to | Identifier | Example method |
| - | - | - |
| Retrieve a chat with its participants and threads | `chat_id` | [Get chat](https://www.text.com/docs/api/agent-chat/v3.6/chats/get-chat.md) |
| Resume a previous chat with a new thread | `chat_id` | [Resume chat](https://www.text.com/docs/api/agent-chat/v3.6/chats/resume-chat.md) |
| Retrieve one session transcript | `thread_id` | [Get thread transcript](https://www.text.com/docs/api/agent-chat/v3.6/chats/get-thread-transcript.md) |
| Update data attached to a chat | `chat_id` | [Update chat properties](https://www.text.com/docs/api/agent-chat/v3.6/properties/update-chat-properties.md) |
| Update data attached to one session | `thread_id` | [Update thread properties](https://www.text.com/docs/api/agent-chat/v3.6/properties/update-thread-properties.md) |
| Identify one item in a thread | `event_id` | [Agent Chat API data structures](https://www.text.com/docs/api/agent-chat/v3.6/data-structures.md#events) |

## Tickets

A ticket is a separate work record with its own status, assignee, team, events, and custom fields. A ticket can originate from a chat, but it does not contain the complete chat automatically.

When a ticket is connected to a chat, follow its source reference to retrieve the conversation and customer data:

1. Use [Get ticket](https://www.text.com/docs/api/ticketing/tickets/get-ticket.md) to retrieve the ticket and read `source.referenceID`.
2. For a ticket created from a chat, pass `source.referenceID` in `filters.thread_ids` to [List archives](https://www.text.com/docs/api/agent-chat/v3.6/chats/list-archives.md). The result contains the chat, the referenced thread and its events, and the customer participant.
3. Ticket responses do not include a Customer Data Platform customer ID. Pass the customer participant's `id` to [Get merged customer](https://www.text.com/docs/api/customer-data-platform/customers/get-merged-customer.md) to retrieve customer data across associated identities.

See [Storing custom data](https://www.text.com/docs/key-concepts/custom-data.md) for session fields copied into ticket custom fields and the available storage scopes.

## Retrieve chat data and receive updates

Text provides three ways to read chat activity. The right choice depends on whether you need state or notification of a change.

| Interface | Use it for | What to expect |
| - | - | - |
| Web API | Requesting the state of a resource on demand | One request and one response through the [Agent Chat API](https://www.text.com/docs/api/agent-chat/v3.6.md) or [Customer Chat API](https://www.text.com/docs/api/customer-chat/v3.6.md) |
| RTM API | Maintaining an interactive chat client | A persistent connection with pushes from the [Agent Chat RTM API](https://www.text.com/docs/api/agent-chat/v3.6/rtm.md) or [Customer Chat RTM API](https://www.text.com/docs/api/customer-chat/v3.6/rtm.md) |
| Webhooks | Notifying your backend about selected changes | HTTP requests from the [Webhooks API](https://www.text.com/docs/api/webhooks/v3.6.md) governed by the registered webhook, owner, and filters |

An RTM push and a webhook can have similar names without having the same payload or delivery rules. Do not substitute one for the other based on the event name alone. A webhook notification can also contain enough data to process the change or only enough information to retrieve the affected resource.

One change does not always produce one notification for every matching action. For example, an [`incoming_chat`](https://www.text.com/docs/api/webhooks/v3.6/#incoming_chat) webhook includes events that started the first thread. Do not expect a separate `incoming_event` webhook for those same initial events.

## Chat records and report totals

The Agent Chat API and Customer Chat API return chat and thread records. The Reports API returns aggregated metrics produced for a reporting dimension and time range. A report is not a query over the exact result set returned by `list_archives`.

This distinction affects totals. For example, one chat handled by two agents can contribute to each agent's breakdown while contributing once to an overall chat total. As a result, adding per-agent values can produce a number larger than the overall total.

Use the Agent Chat API or Customer Chat API when you need chat or thread records. Use the [Reports API](https://www.text.com/docs/api/reports/v3.6.md) when you need defined metrics, and interpret each metric according to its dimensions and filters.


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