--- title: "List conversations" method: GET path: "/conversations" tags: ["Conversations"] --- # List conversations `GET /conversations` ## Request - Base URL: `https://api.axilio.ai/api/v1` - URL: `https://api.axilio.ai/api/v1/conversations` - Auth: API key in header `X-Axilio-Api-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns one page of your dedicated phones' conversations, newest activity first: one per phone and set of people it texts with, each with its participants and latest message. Filter by phone (phone_id, or phone_number, the phone's own number), and search the participants with search, which matches any part of a person's number with formatting ignored. A text sent to a number and the replies from it are one conversation; the same number on two of your phones is two. Filter by what became of your texts with status, error_code and replied, optionally within a period (period_start_at, period_end_at): they look only at texts you sent in that period (the 7 days before period_end_at when the start is unset, the same window rules as GET /messages/metrics), combine with each other and with the other filters, and list a conversation when it passes every one. status and error_code match a conversation with at least one such text, so they list conversations, not texts: GET /messages/metrics counts both, in totals (texts) and conversations.by_outcome and failures[].conversations (conversations). With only a period, it lists the conversations you texted in it. ## Query parameters - `limit` integer: max items per page - `offset` integer: pagination offset - `phone_id` string: only conversations on this phone - `phone_number` string: only conversations on the phone with this own number, E.164 (for example +16282788410) - `status` 'delivered' | 'sent' | 'unconfirmed' | 'failed' | 'queued': only conversations with at least one text of yours, sent in the period, in this status: the same values as a message's status. sent means it left the phone but no delivery report came. A conversation counts once however many of its texts match. More statuses may be added. - `error_code` 'phone_unreachable' | 'no_result' | 'policy_off' | 'expired' | 'no_subscription' | 'no_service' | 'radio_off' | 'carrier_rejected' | 'phone_rate_limited' | 'media_fetch_failed' | 'connection_lost' | 'queue_full' | 'send_failed': only conversations with at least one text of yours, sent in the period, that failed for this reason: the same codes as a message's error_code. A conversation counts once however many of its texts match. More codes may be added. - `replied` 'true' | 'false': true: only conversations you texted in the period where they wrote back within 24 hours of one of those texts (the reply may land after the period ends). false: only the ones you texted that they did not answer that way. The same rule as replied in GET /messages/metrics, so its texted minus replied is the number false lists. - `period_start_at` string, date-time: start of the period (RFC 3339) the status, error_code and replied filters look at your texts in. Unset: 7 days before period_end_at. It may be at most a year before now. - `period_end_at` string, date-time: end of the period (RFC 3339). Unset: now, and a later time is read as now. Must be after period_start_at. - `search` string: free-text search across the conversation's participants: a conversation matches when someone's handle contains this. For a number the digits are compared with formatting ignored, so +1 (415) 555-0123, 4155550123 and 0123 all match +14155550123; other text matches a short code or an alphanumeric sender, case-insensitive. ## Response `200` OK - ConversationListResponse: One page of the organization's conversations. - `conversations` Conversation[], nullable, required: Conversations, newest activity first by last_message_at. - `created_at` string, date-time, required: When the conversation's first message was stored. - `id` string, required: Conversation identifier. Opaque: don't derive it, read it from a conversation or a message's conversation_id. - `is_group` boolean, required: True for a group conversation: more than one other person. - `last_message` PhoneMessage, required: A text message on one of the organization's dedicated phones. - `accepted_at` string, date-time: When the phone reported it had this outgoing message. Absent for a received message, and for one the phone never got. - `api_key_id` string: The API key that sent this message. Absent for a message a signed-in user sent, a received message, and one sent before senders were recorded. - `body` string, required: The message text: every text part, in order, joined with a newline. Empty for a message with no text. - `channel` 'sms' | 'mms' | 'rcs', required: How the message travelled: sms (plain text), mms (multimedia, including group texts and some long texts), or rcs. More channels may be added; treat a value you don't know as a channel you don't handle. - `conversation_id` string, required: The conversation this message is in: GET /conversations/{conversation_id} reads it, and its messages are at GET /conversations/{conversation_id}/messages. - `created_at` string, date-time, required: When the platform stored the message. Lists sort and filter on this time. - `deleted_at` string, date-time: When the message was deleted. Present only on a deleted message, which GET /messages/{message_id} still returns with no body or parts; lists and conversations leave it out. - `delivered_at` string, date-time: When a message this phone sent was delivered. Absent until then, and for a received message. - `direction` 'inbound' | 'outbound', required: inbound for a message the phone received, outbound for one it sent. - `error` string: Why an outbound message failed or is unconfirmed, in words. Empty otherwise. - `error_code` 'phone_unreachable' | 'no_result' | 'policy_off' | 'expired' | 'no_subscription' | 'no_service' | 'radio_off' | 'carrier_rejected' | 'phone_rate_limited' | 'media_fetch_failed' | 'connection_lost' | 'queue_full' | 'send_failed': Why an outbound message failed or is unconfirmed, as a code to branch on: phone_unreachable (the phone never got it before its deadline; it did not go out), no_result (unconfirmed: the phone had it but has not reported), policy_off (the phone's sending switch is off), expired (its deadline passed before the phone could send it), no_subscription (no SIM line), no_service (no mobile service or data), radio_off, carrier_rejected, phone_rate_limited (Android's outgoing-message limit on the phone), media_fetch_failed (the phone could not download the attachment), connection_lost (the phone lost its connection before sending; it did not go out), queue_full (the phone was too busy), or send_failed (any other failure; error has the detail). Empty when error is. Absent on a failure reported by older phone software. - `failed_at` string, date-time: When a message this phone sent failed. Absent unless its status is failed. - `from` string, nullable, required: Sender: an E.164 number, a short code, or an alphanumeric sender id. Null only when the sender is this phone's own SIM and the phone does not know its number. - `id` string, required: Message identifier. - `is_group` boolean, required: True for a group message (more than one recipient). - `parts` PhoneMessagePart[], nullable, required: The message content in order: text and media. A plain SMS has one text part. - `file_id` string: The file holding the media, in the organization's file library, where the file API returns a short-lived download link. Present on media parts. - `mime_type` string: The attachment's content type, for example image/jpeg. Present on media parts. - `name` string: The attachment's filename as the sender's phone named it. Present on media parts. - `size_bytes` integer: The attachment's size in bytes. Present on media parts. - `text` string: The text. Present on text parts. - `type` 'text' | 'media', required: text for a run of message text; media for an attachment. More part types may be added; skip a part whose type you don't know. - `phone_deletion` PhoneMessagePhoneDeletion: What the delete did to the copy on the phone itself. - `next_check_at` string, date-time, nullable, required: When Axilio next checks this delete: it asks the phone again if the phone can delete and the 7 days after the delete aren't over, or settles it. Null once the outcome is final: deleted, not_found, ambiguous, not_matched and not_sent at once, unconfirmed when the 7 days run out; message.phone_deleted or message.phone_delete_failed fires then. - `reason` string, required: A human-readable explanation of status. - `status` 'pending' | 'deleted' | 'not_found' | 'ambiguous' | 'not_default_app' | 'not_matched' | 'failed' | 'unconfirmed' | 'not_sent', required: pending (the phone has been asked and has not answered yet), deleted (the phone deleted its copy), not_found (the phone has no copy), ambiguous (an older text the phone cannot tell apart from an identical one; left on the phone), not_default_app (the phone is not set up to delete messages yet; it is asked once it can), not_matched (the phone stored this message before it became the phone's messaging app and could not identify it; its copy may still be there), failed (the phone tried and failed; it is asked again), unconfirmed (the phone has not confirmed the delete: the request could not be sent, or 7 days passed without an answer; its copy may still be there), or not_sent (the organization no longer rents the phone, so nothing was sent). next_check_at is null once the outcome is final. More values may be added. - `phone_id` string, required: The phone that received or sent the message. - `received_at` string, date-time, nullable, required: When this phone received the message, by the phone's clock, to the millisecond. Null for a message the phone sent. - `sent_at` string, date-time, nullable, required: When the message was sent. For a received message, the sending network's clock (SMS carries whole seconds); for a message this phone sent, when the platform learned the network accepted it. Null for a message not sent yet. - `status` 'queued' | 'sent' | 'delivered' | 'failed' | 'unconfirmed': The delivery state of a message this phone sent: queued (accepted and issued to the phone), sent (the network accepted it), delivered (the recipient acknowledged it), failed, or unconfirmed (the phone had it but has not reported whether it went out; do not resend automatically, it may still turn sent or failed). Empty for a received message. More statuses may be added; treat one you don't know as still in progress. - `to` string[], nullable, required: Every recipient, as E.164 numbers. For a one-to-one inbound message this is the phone's own number; a group message lists every recipient. Empty when the only recipient is this phone's own SIM and the phone does not know its number. - `truncated` boolean, required: True when the text was longer than 5000 characters and was cut to that length. - `user_id` string: The signed-in user who sent this message, from the dashboard or the CLI. Absent for a message sent with an API key, a received message, and one sent before senders were recorded. - `last_message_at` string, date-time, required: When the latest message was stored. Conversations list newest activity first by this time. - `participants` ConversationParticipant[], nullable, required: Everyone on the conversation but your phone. Empty when the sender's number is unknown. - `handle` string, required: How this person is addressed: an E.164 number such as +14155550123, a short code, or an alphanumeric sender id. - `phone_id` string, required: The dedicated phone this conversation is on. - `phone_number` string, nullable, required: That phone's own number in E.164: what its SIM reports, or else the number its latest received text was sent to. Null when neither is known, or when the phone is no longer one your organization rents. - `total` integer, required: Total conversations matching the query. ## Other responses - `422`: Unprocessable Entity - `500`: Internal Server Error ## Changes - **2026-10-24** `ecca093572e0`: 1 info - endpoint added [Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/conversations/get.md) --- [API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)