Skip to content
DashboardGet API key

List conversations

View .md
GET

List inbox threads, most recently active first. A conversation groups every message with one contact across channels, which is what you need to build an inbox: GET /v1/messages returns a flat log with no thread to hang it on.

Use senderId to scope the list to a single number, and channel to keep only threads that have carried that channel.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Query parameters

  • channelstring

    Keep only threads that have carried this channel.

    One ofsmssms_onewaywhatsappemailtelegraminstagrammessengervoice
  • senderIdstring

    Keep only threads last handled by this sender.

  • searchstring

    Search threads by identity: phone number (any format — +1 (555) 123-4567 and 15551234567 both match), email address (full or local part), WhatsApp username, or BSUID. Matching is by whole word, with prefix matching on the last term, so mar finds maria@example.com and +1555 finds +15551234567; a fragment from the middle or end of a number (4567) does not match.

    It does not search message bodies — only who the thread is with.

    Results come back ranked by relevance rather than by recency, so the usual "most recently active first" ordering does not apply while q is set. senderId and channel still narrow the results, and cursor paginates them as usual. An empty or whitespace-only q returns no items rather than the full list.

    Limitsmin length 1 · max length 120
  • limitinteger
    Default50
    Limitsmax 100
  • cursorstring

    Opaque cursor from a previous response's nextCursor. Do not construct it.

Responses

200List of conversations.
  • 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

        Delivery channel. Use 'auto' for intelligent routing.

        One ofautosmssms_onewaywhatsapptelegramemailinstagrammessengervoice
      • directionstringrequired
        One ofinboundoutbound
      • atstring<date-time>required
    • senderIdstring

      Sender that last handled this thread. Use it as the Zavu-Sender header when replying so the answer leaves from the same number the contact knows.

    • messageCountintegerrequired
    • unreadCountintegerrequired

      Inbound messages not yet marked read. Reset with POST /v1/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
  • nextCursorstringnullable
400Invalid query parameters.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject