Search conversations
updated_since, they come in the order they last changed, oldest first. To read what was said, get the conversation.
Matches the customer’s name, phone number, or email, or words in the title, summary, or category. Up to 100 characters.
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.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.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.Conversation fields
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.The latest message, or
started_at when there were no later messages. null only when both are missing.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.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.The phone line (location) that took the conversation:
id, name, and phone_number. name and phone_number can be null.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
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.Questions the customer asked, each with the
question, the answer given, and whether it was answered. answer can be null.The task this conversation created, in the same shape as Get a task, with its
description. null when it created no task.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.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.How many older notes were left out because the conversation has more notes than fit. The newest notes are always kept.
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 withbefore 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
before. The call transcript is not paged.
Download a call recording
Content-Type header.
Optional. Request part of the file, such as
bytes=0-1048575. The response is then 206 with a Content-Range header.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
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.
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.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.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.400.
This example tells Dana Ruiz that her membership is cancelled:
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.errorsays why.unknown. The provider did not answer. Check the conversation later.
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 sameidempotency_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.