Skip to content

Conversations

Get a conversation

Returns a single conversation summary, the same object the list endpoint returns.

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

Path parameters

  • iduuidrequired

    Conversation id.

    Example
    6a1f3c52-8e0b-4d7a-b1f2-93c4d5e6f708

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

Response

200 OKapplication/json

  • 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 conversation.
  • 400Bad request. The id in the path is not a valid UUID.
  • 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).
  • 404Not found. The conversation does not exist in this workspace, belongs to the inactive connection (QR vs Cloud API), or (for agents signed in to the app) is not assigned to you. Also returned while the workspace’s WhatsApp connection is offline.
  • 500Server error. Something went wrong on our side. Retry with backoff.