AXaxilioai
conversations

List conversations

Changed on

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.

get/conversations

Request

Query parameters

limitinteger

max items per page

offsetinteger

pagination offset

phone_idstring

only conversations on this phone

phone_numberstring

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_atstring 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_atstring date-time

end of the period (RFC 3339). Unset: now, and a later time is read as now. Must be after period_start_at.

searchstring

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

OK

$schemastring uri

A URL to the JSON Schema for this object.

totalinteger required

Total conversations matching the query.

Example response

{
  "$schema": "/api/v1/ConversationListResponse.json",
  "conversations": [
    {
      "$schema": "/api/v1/Conversation.json",
      "last_message": {
        "$schema": "/api/v1/PhoneMessage.json"
      }
    }
  ]
}

Changes