Skip to main content
A conversation is one customer contact: a phone call, a text thread, a website chat, or an email thread. When the AI texts a caller during or after a call, those texts belong to the call’s conversation.

Search conversations

Try it in the playground. Returns conversation summaries, most recent activity first. With updated_since, they come in the order they last changed, oldest first. To read what was said, get the conversation.
string
Matches the customer’s name, phone number, or email, or words in the title, summary, or category. Up to 100 characters.
string
One of phone, text, web_chat, or email. Returns conversations that happened on that channel. A call the customer replied to by text matches both phone and text.
string
Created within this window: today, yesterday, 7d, 14d, 30d, 90d, 365d, mtd, or ytd. Every window starts at midnight in your team’s timezone. See time ranges. Leave it out for all time.
string
Returns only conversations whose updated_at is at or after this time. Send an ISO 8601 timestamp with Z or an offset, such as 2026-10-07T14:00:00Z or 2026-10-07T09:00:00-05:00, URL-encoded (a raw + arrives as a space). Any other value returns 400. Results then sort by updated_at, oldest first, then by id. It works with the other filters, and range still filters by when the conversation started.A conversation that is deleted or hidden as spam or no answer drops out of the results instead of coming back, so updated_since alone can’t tell you a conversation is gone.
integer
default:"10"
Results per page, 1 to 50.
integer
default:"1"
Page number. Use next_page from the previous response.

Conversation fields

integer
The conversation ID. Use it to get the conversation or its recording.
string
The conversation in the dashboard.
string | null
The channel the conversation started on: phone, text, web_chat, or email.
string[]
Every channel the conversation happened on. A call the customer replied to by text lists phone and text. Texts the AI sent during or after a call appear in written.messages but don’t add text.
string | null
When the conversation started, as an ISO 8601 UTC timestamp.
string | null
The latest message, or started_at when there were no later messages. null only when both are missing.
string | null
When the conversation last changed, as an ISO 8601 UTC timestamp in whole seconds. Search with updated_since uses this time. A change to its task’s status or assignee moves it. So do the AI’s changes to the title, summary, category, or priority, a merge, new texts, emails, and chat messages, and the AI finishing its review. Some of these changes touch no field the API returns, so a conversation can come back with nothing visibly different.Editing the customer’s name, phone, or email on their contact does not move it. Neither does renaming a phone line or a team member. Notes don’t reliably move it either.
string | null
A short title the AI wrote. Up to 200 characters.
string | null
The AI’s summary. Up to 1,500 characters.
string | null
The conversation category key, such as cancellation, billing, damage_claim, lost_items, sales, scheduling, hours_status, service_status, account_update, general_questions, job_seeking, or other. GET /reports/metrics lists every key with its label under categories. Older conversations can have a retired key that is not in that list.
object
The customer’s name, phone, and email. Any of them can be null.
object | null
The phone line (location) that took the conversation: id, name, and phone_number. name and phone_number can be null.
integer | null
Call length in seconds. null for texts, chats, and emails.
boolean
true when GET /conversations/{conversation_id}/recording has audio to stream for this call. false for texts, chats, emails, and calls that were not recorded. For some calls the recording provider stores the audio and can delete it, so true can still get a 404.

Get a conversation

Try it in the playground. Returns one conversation with every conversation field, plus the questions the customer asked, its task, its internal notes, and the full transcript. A long text, chat, or email thread returns its newest messages. To read the earlier ones, see Read a long thread.
integer
required
The conversation ID.
string
Optional. Pass written.earlier_cursor from the previous response to get the page of messages before it. Omit it to get the newest messages. The cursor is opaque, so pass it back unchanged. A value that is not a cursor returns 400.
object[]
Questions the customer asked, each with the question, the answer given, and whether it was answered. answer can be null.
object | null
The task this conversation created, in the same shape as Get a task, with its description. null when it created no task.
object | null
The spoken transcript of a phone call. null for texts, chats, and emails.
object | null
Texts, chat messages, and emails in the conversation. null when there are none. A phone call with follow-up texts has both transcript and written. A long thread returns its newest page of messages. Every other field in the response is the same with or without before.
object[]
Internal notes on the conversation, oldest first and newest last, in the same shape Add a note returns. Only your team sees them. Each note has id, content, author as id and name, and created_at. author is null when no teammate wrote the note or the author has no name on their profile.
boolean
true when older notes were left out or a very long note was cut.
integer
How many older notes were left out because the conversation has more notes than fit. The newest notes are always kept.
A conversation that does not exist, or that the key’s owner cannot see, returns 404.

Read a long thread

A long text, chat, or email thread returns its newest messages first. To read the whole thread, request the conversation again with before set to written.earlier_cursor until the cursor is null. Each page is the run of messages just before the previous page, so put it in front of what you have.
JavaScript
A message that arrives while you page comes after every cursor, so the earlier pages do not shift and you get no gaps or repeats. To see the new message, request the conversation without before. The call transcript is not paged.

Download a call recording

Try it in the playground. Returns the call audio. The response body is the audio file, not JSON. The format depends on how the call was recorded, such as MP3 or Ogg. Read the Content-Type header.
integer
required
The conversation ID of a phone call.
string
Optional. Request part of the file, such as bytes=0-1048575. The response is then 206 with a Content-Range header.
Returns 404 when the conversation has no recording. Check has_recording on the conversation first. Texts, chats, emails, and calls that were not recorded have none. Recordings come back as MP3 (audio/mpeg) or Ogg (audio/ogg). Read the Content-Type header. A Range header that falls outside the file returns 416 when the recording provider supports byte ranges. Otherwise it returns 404. If the recording provider is down, the API returns 502 or 503 for most recordings and 404 or 500 for some, so retry later before treating a recording as missing.

Reply to a conversation

Try it in the playground. Sends a text or email reply to the customer on an existing conversation, the same as typing a reply in the dashboard and clicking Send. The customer receives it. The reply comes from your team’s usual texting number or email address. It shows in the conversation thread and in Activity under the name of the person who created the key, and the conversation counts as handled by a person.
Each request messages a real customer. Requests from the playground go to production, so Try it with a real key sends a real text or email.
A call can get a text whenever the conversation has a phone number, even when text is not yet in its channels. Otherwise you can reply only on a channel the conversation already uses, as listed in its channels. A website chat with neither text nor email in channels cannot get a reply through the API, and neither can a call with no phone number and no email thread. Reply to those from the dashboard. The API applies the same rules as the dashboard:
  • The person who created the key must be allowed to message this customer in the dashboard. Owners and admins can, and so can managers on the conversation’s phone line.
  • A customer who opted out by replying STOP gets no texts. Email still sends, the same as in the dashboard.
  • A text longer than 10 SMS segments is refused.
  • There is no recipient field. The reply goes only to the conversation’s customer. A text goes to the contact’s current phone number. An email goes to the reply address on the customer’s latest email, or to the contact’s email address.
integer
required
The conversation ID.
string
Optional. text or email. It must be one of the conversation’s channels, or text on a call with a phone number. Leave it out only when the conversation can get just one of text and email.
string
required
The message. 1 to 5,000 characters after leading and trailing spaces are removed. An email reply uses the thread’s subject, such as Re: Cancel monthly membership, the same as in the dashboard. There is no subject field.
string
Optional. 1 to 120 letters, digits, ., _, :, or -. A retry with the same key returns the first message instead of sending again. See Retry without sending twice.
string
Optional. The same key, sent as a header instead of in the body. Sending both returns 400.
Any other key in the body returns 400. This example tells Dana Ruiz that her membership is cancelled:
integer
The message ID.
integer
The conversation the reply belongs to.
string
Always business.
string
text or email.
string
The message as sent.
string
When the reply was sent, as an ISO 8601 UTC timestamp.
string
  • queued. The carrier accepted the reply and has not sent it yet.
  • sent. The provider sent it.
  • delivered. The provider reports that the customer received it.
  • failed. The send failed. error says why.
  • unknown. The provider did not answer. Check the conversation later.
string | null
A plain reason when the send failed. Otherwise null.
A failed send still returns 201, with delivery_status set to failed. Check delivery_status, not only the HTTP status. The failed message shows in the conversation thread in the dashboard, where someone can retry it.

Retry without sending twice

Each request without an idempotency key sends a new message. If a request times out and you send it again, the customer can get the reply twice. To retry safely, send the same idempotency_key with every attempt. An idempotency key is scoped to one person and one conversation. The person is whoever created the API key, so two API keys from the same person share idempotency keys. A retry with the same idempotency key on the same conversation returns the first message, with the same id, and sends nothing. The same idempotency key sent by another person, or on another conversation, sends a new reply. Use a new key for each new reply. Reusing a key with a different body or channel returns 409.

Errors and limits

A reply counts toward the API’s rate limit of 120 requests per minute per person. Replies also have their own limits. One person can send 20 replies per minute, and one conversation can get 5 replies per minute. Over any limit, the API returns 429 with a Retry-After header.