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

​
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.
1

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

Chat active

An agent (or bot) is handling the conversation. Events are being exchanged. The thread is open.
3

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

Chat resumed

The customer returns. A new thread opens inside the same chat. The full history from previous threads is still there.
Three methods manage the chat lifecycle:
  • start_chat — creates a new chat and its first thread, returning chat_id, thread_id, and event_id.
  • resume_chat — reopens a closed chat and starts a new thread, returning the new thread_id.
  • deactivate_chat — closes the current thread while leaving the chat itself in history.

​
APIs for the two sides of the conversation

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

Agent Chat API

For anything acting on the agent side — sending messages, closing chats, building bots, pulling chat history.

Customer Chat API

For building a custom chat experience from the customer’s side — a branded widget, a mobile app, or a bridge to another channel.
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

Agent Chat API data structures
Customer Chat API data structures