Skip to content

Conversations

List conversations

Returns the 30 most recently active conversations of the workspace, newest first. Each item includes a preview of the last message, the unread count and the assigned teammate. There is no pagination: use it to show or poll the top of the inbox, and read older history per conversation with its messages endpoint.

GET/api/conversations
  • Bearer API key
  • Scope: read or write
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Query parameters

  • channel_iduuidoptional

    Only return conversations of this Meta channel (phone number). Useful when a workspace has several Meta numbers.

    Constraints
    Must be a valid UUID, otherwise the request fails with 400 and invalid channel_id.
  • tenantuuidoptional

    Alternative to the X-Tenant-ID header, with the same rules.

Response

200 OKapplication/json

  • itemsarray<Conversation>

    Up to 30 conversations, ordered by last_message_at (newest first; chats without messages last).

    Show child attributesHide child attributes16
    • iduuid

      Conversation id. Use it in /api/conversations/{id} paths.

    • workspace_iduuid

      Workspace the conversation belongs to.

    • whatsapp_jidstring

      WhatsApp chat id (JID), for example 15551234567@s.whatsapp.net for a person or …@g.us for a group.

    • channel_providerenum

      How the number is connected: scan (linked by QR code) or meta (WhatsApp Business Platform, Cloud API).

    • channel_iduuidmay be absent

      The Meta channel (phone number) the chat belongs to. Left out for QR-linked chats.

    • phone_number_idstringmay be absent

      Meta phone number id of the channel. Left out for QR-linked chats.

    • namestring

      Display name: the contact or group name, or +<digits> for a chat started by phone number.

    • typeenum

      individual or group.

    • phonestringmay be absent

      Phone number as digits only, without +.

    • group_subjectstringmay be absent

      Group subject, for group chats.

    • avatar_urlstringmay be absent

      Profile picture URL, when one has been downloaded.

    • last_messagestringnullable

      Preview of the newest message: its text, Photo for an image, or the file name (or Document) for a document. null when the chat has no messages.

    • last_message_attimestampnullable

      Time of the newest message as an RFC 3339 string in UTC. null when the chat has no messages.

    • unread_countinteger

      Unread incoming messages. 0 after the chat is marked as read.

    • assignee_iduuidmay be absent

      User id of the assigned teammate (a user id, not a membership id). Left out when unassigned.

    • assignee_namestringmay be absent

      Name of the assigned teammate.

Status codes

  • 200OK. The conversations, newest first. items is an empty array when there is nothing to show.
  • 400Bad request. channel_id is not a valid UUID (invalid channel_id), or a session request did not select a workspace (workspace required (X-Tenant-ID)).
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The X-Tenant-ID header or tenant query does not match the API key’s workspace (API key belongs to a different workspace), or a signed-in user is not a member of the workspace (forbidden).
  • 500Server error. The conversations could not be loaded. Retry with backoff.

Which conversations are returned?

  • Active connection only. If the workspace has a Meta (Cloud API) channel, the list contains its Meta conversations; otherwise it contains the conversations of the number linked by QR code.
  • Empty while a QR-linked number is offline. For a QR-linked number, the list is empty while the linked session is not connected. Check the session with GET /api/whatsapp/status before treating an empty list as "no chats".
  • Agents see only their chats. A teammate signed in with the agent role only sees conversations assigned to them. API keys always see the whole inbox.
  • At most 30, no paging. The response is capped at 30 conversations ordered by last_message_at; there are no limit or offset parameters.