Skip to content
DashboardGet API key

List conversations

View .md
GET

List inbox threads, most recently active first. Filter by from (one of your addresses) and channel. Each conversation carries from, the address it was last handled from.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Query parameters

  • channelstring

    Only threads that have carried this transport.

    One ofsmssms_onewaywhatsapptelegramemailinstagrammessengervoice
  • fromstring

    Keep only threads last handled from this address. Resolved like from on POST /v2/messages, narrowed by channel when given.

  • searchstring

    Identity search (number, email, username). Never message bodies.

    Limitsmax length 120
  • limitinteger
    Default50
    Limitsmax 100
  • cursorstring

    Opaque nextCursor from the previous page.

Responses

200Threads, most recently active first (by relevance when `search` is set).
  • itemsobject[]required
    12 properties
    • idstringrequired
    • contactIdstring

      ID of the contact this thread belongs to. Absent on group threads and on threads whose contact has not been resolved yet.

    • contactIdentifierstringrequired

      The key this thread is filed under: a phone number in E.164, a WhatsApp business-scoped user ID (BSUID), or a numeric chat ID (Telegram/Instagram/Messenger). It is not always a phone number, so do not parse it as one.

    • emailstring

      Email address of the thread, when the contact was reached by email.

    • channelsstring[]required

      Every channel this thread has carried messages on.

    • lastMessageobjectrequired

      Denormalized preview of the most recent message, so a thread list needs no extra fetch.

      5 properties
      • idstringrequired
      • textstringrequired

        Text or caption. Empty when the last message carried no text (e.g. media).

      • channelstringrequired

        A transport a message travels on.

        One ofsmssms_onewaywhatsapptelegramemailinstagrammessengervoice
      • directionstringrequired
        One ofinboundoutbound
      • atstring<date-time>required
    • messageCountintegerrequired
    • unreadCountintegerrequired

      Inbound messages not yet marked read. Reset with POST /v2/conversations/{conversationId}/read.

    • whatsappobject

      WhatsApp identity, present when the contact adopted a username.

      2 properties
      • bsuidstring

        Business-scoped user ID. Can be used as to when sending.

      • usernamestring
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
    • fromstringnullable

      The address this thread was last handled from, on the transport of its last message. Pass the conversation's id as conversationId on POST /v2/messages to reply from it. A thread opened by an API send before /v2 recorded no sender; its from is read off its messages. ?from= on the list matches threads by the recorded sender only, which messages sent through /v2 record.

  • nextCursorstringnullable
400Invalid query.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
404`from` names no address of this project.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring