Skip to content

Messages

List messages

Returns one page of messages from a conversation. Pages go back in time (the first page holds the newest messages), but the messages inside a page are ordered oldest to newest, ready to render as a chat.

GET/api/conversations/{id}/messages
  • 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

Query parameters

  • limitintegeroptional

    Messages per page.

    Constraints
    1–100. Values of 0 or less, or above 100, are replaced by 50.
    Default
    50
    Example
    50
  • offsetintegeroptional

    Number of newer messages to skip. Ignored when before is set.

    Default
    0
  • beforetimestampoptional

    Only return messages older than this time. Accepts RFC 3339 (2026-10-02T14:31:07Z) or Unix seconds. Pass the timestamp of the oldest message you have to load the previous page.

    Constraints
    Anything else returns 400 with invalid before timestamp.

Response

200 OKapplication/json

  • itemsarray<Message>

    Messages in this page, oldest first.

    Show child attributesHide child attributes15
    • iduuid

      Message id in whatsappx.si.

    • whatsapp_message_idstring

      Message id assigned by WhatsApp.

    • conversation_iduuid

      Conversation the message belongs to.

    • sender_jidstring

      WhatsApp id (JID) of the sender. For your own messages, the connected number.

    • sender_namestring

      Sender display name, when WhatsApp provides one (may be empty).

    • contentstring

      Message text. On numbers linked by QR code, images and documents carry their caption here. On the Cloud API, non-text messages are stored as a placeholder such as [image message].

    • message_typestring

      text, image or document on numbers linked by QR code. Non-text messages received through the Cloud API keep the type name Meta sends (for example image or audio) and have no downloadable media.

    • media_urlstringmay be absent

      Path of the downloaded media file, for example /api/media/<workspace>/<file>. Prefix it with https://whatsappx.si and send your API key to download it.

    • mime_typestringmay be absent

      MIME type of the media file.

    • file_namestringmay be absent

      Original file name of a document.

    • file_sizeintegermay be absent

      Media size in bytes.

    • timestamptimestamp

      When the message was sent on WhatsApp (RFC 3339).

    • from_meboolean

      true for messages sent from the connected number (by your team, the API or an automation).

    • statusenum

      received for incoming messages, sent for outgoing ones. Delivered and read receipts are not tracked.

    • created_attimestamp

      When whatsappx.si stored the message (RFC 3339).

  • totalinteger

    Number of messages matched (all messages, or those older than before).

  • limitinteger

    The page size used.

  • offsetinteger

    The offset used (0 when before is set).

  • has_moreboolean

    Whether older messages exist. With before, it is true when the page is full.

Status codes

  • 200OK. One page of messages.
  • 400Bad request. invalid conversation id or invalid before timestamp.
  • 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, or (for agents signed in to the app) is not assigned to you.
  • 500Server error. The workspace’s WhatsApp connection is offline (whatsapp is not connected), or the messages could not be loaded.

How do I page through history?

  1. Call the endpoint without before to get the newest page.
  2. While has_more is true, call it again with before set to the timestamp of the first (oldest) item you received.

before is safer than offset while new messages keep arriving, because offsets shift when a message is added.

How do I download media?

Images and documents received on a number linked by QR code (up to 25 MiB) are downloaded and stored. Their media_url is a path such as /api/media/<workspace>/<file>; request https://whatsappx.si + media_url with your API key (Authorization: Bearer …) to download the file. The key must belong to the same workspace; without it you get 401, and another workspace's file answers 404. Profile pictures use /api/avatars/<workspace>/<file> the same way. There is no upload endpoint.