Skip to main content
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:

Agents

The people on your team. The app calls them teammates, while the APIs represent them as agents.

Customers

The people your team talks to. Text can associate their records across browsers, devices, and channels.

Bots

Automated participants that act on the agent side. A bot can send messages, close chats, and handle routing.
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, 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 A chat contains threads, which contain events

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.
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 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 to retrieve chat summaries available to the agent and Get chat to retrieve a specific chat. Use RTM pushes when an application must react as events arrive.
3

Deactivate the chat

Deactivate chat closes the active thread. The chat and completed thread remain available as history.
4

Read historical sessions

Use List archives to search the archived view. Use get_thread_transcript when you need one session rather than the entire chat record.
5

Resume the chat

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:

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 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. 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 to retrieve customer data across associated identities.
See Storing custom data 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. 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 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 when you need defined metrics, and interpret each metric according to its dimensions and filters.