WhatsApp APIAPI

WhatsApp: read conversations through the API

List the conversations of a WhatsApp number and read a contact's messages through the XBASE API, with the 24-hour window of each conversation.

Updated on

With conversation reading, your system or agent sees what the contact wrote, what the company replied and whether the 24-hour window is open, before choosing between a free-form message and a template. Both routes only read: nothing changes in the conversation.

The key needs the whatsapp:read permission (Read WhatsApp conversations on the keys screen).

List the conversations

GET https://api.xbase.app/api/external/v1/whatsapp/conversations?numberId={numberId}
ParameterRequiredRule
numberIdyesWorkspace number (list the numbers)
limitnoHow many conversations, from 1 to 100. Default: 50
beforenoISO 8601 date. Returns the conversations with activity before it (see pagination)
curl "https://api.xbase.app/api/external/v1/whatsapp/conversations?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b&limit=20" \
  -H "Authorization: Bearer $XBASE_API_KEY"

200 response, from the most recent conversation to the oldest:

[
  {
    "threadId": "c1d7f0b2-5a4e-4f3d-9c2b-1a0e9d8c7b6a",
    "phone": "5521999990000",
    "contact": { "id": "8b2f4c1e-3d5a-4e6f-9a8b-7c6d5e4f3a2b", "name": "Maria Souza" },
    "lastActivityAt": "2026-11-07T14:02:11.000Z",
    "lastMessage": {
      "id": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21",
      "messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABIYFDNBMjc1QjE3RjdCNEE1QzlEMjA4AA==",
      "direction": "in",
      "type": "text",
      "text": "Has my order shipped?",
      "at": "2026-11-07T14:02:11.000Z"
    },
    "unansweredCount": 2,
    "window": { "open": true, "expiresAt": "2026-11-08T14:02:11.000Z", "reason": null }
  }
]
FieldDescription
threadIdConversation in XBASE
phoneContact's phone with country code, digits only
contactContact of the conversation (id and name), or null
lastActivityAtLast activity of the conversation. Use it in before to get the next page
lastMessageLast message, in the messages format (without status and author), or null
unansweredCountMessages from the contact after the company's last reply
windowThe conversation's 24-hour window

Read a conversation

GET https://api.xbase.app/api/external/v1/whatsapp/conversations/{phone}?numberId={numberId}

phone is the contact's phone with country code. +, spaces, hyphens and parentheses are removed.

ParameterRequiredRule
numberIdyesWorkspace number
limitnoHow many messages, from 1 to 200. Default: 50 (the most recent)
beforenoISO 8601 date. Returns the messages before it
curl "https://api.xbase.app/api/external/v1/whatsapp/conversations/5521999990000?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
  -H "Authorization: Bearer $XBASE_API_KEY"

200 response, with the messages in chronological order:

{
  "contact": { "id": "8b2f4c1e-3d5a-4e6f-9a8b-7c6d5e4f3a2b", "name": "Maria Souza", "phone": "5521999990000" },
  "threadId": "c1d7f0b2-5a4e-4f3d-9c2b-1a0e9d8c7b6a",
  "window": { "open": true, "expiresAt": "2026-11-08T14:02:11.000Z", "reason": null },
  "messages": [
    {
      "id": "0b9c8d7e-6f5a-4b3c-2d1e-0f9a8b7c6d5e",
      "messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABEYEjQ1QzM1RkQ2RDhGNjZBMDQ3MwA=",
      "direction": "out",
      "type": "template",
      "text": "Hi Maria, your order 12345 was delivered on 11/04 at 2:28 PM.",
      "at": "2026-11-07T13:40:02.000Z",
      "status": "read",
      "author": "Store integration"
    },
    {
      "id": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21",
      "messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABIYFDNBMjc1QjE3RjdCNEE1QzlEMjA4AA==",
      "direction": "in",
      "type": "text",
      "text": "Has my order shipped?",
      "at": "2026-11-07T14:02:11.000Z",
      "status": null,
      "author": null
    }
  ]
}

If the phone never talked to the number, the response is also 200: threadId is null, messages is empty and the window is closed with reason: "no_contact_message". To start the conversation, send a template.

Messages

FieldDescription
idMessage id in XBASE
messageIdMessage id at Meta (wamid.…), the same as in the webhooks. Use it to react or mark as read. May be null
directionin: from the contact. out: from the company (person, agent or API)
typetext, image, audio, video, document, sticker, location, template, interactive…
textText, caption or audio transcript. A template comes with its variables filled in. Media without text comes with a label, such as [imagem]
atWhen the message was recorded
statusDelivery status: submitted, sent, delivered, read, deleted or error. On received messages, usually null
authorWho sent it on the company's side: the name of the person, the agent or the API key

Media (image, audio, document) is not in the response. Conversation records that are not messages, such as a tag or stage change, are left out.

24-hour window

FieldDescription
window.opentrue: a free-form message can be sent now
window.expiresAtWhen the window closes (24 hours after the contact's last message), or null
window.reasonWith the window closed: no_contact_message (the contact never wrote), window_expired (more than 24 hours passed) or awaiting_template_reply (the company sent a template and the contact has not replied yet). null with the window open

Reading uses the same rule as sending: with open: true, POST /whatsapp/messages does not refuse for a closed window at that moment.

Pagination

  • Conversations: send in before the lastActivityAt of the last conversation you received. A list shorter than limit is the last page.
  • Messages: send in before the at of the first message you received to get the older ones.

Errors

StatuscodeWhen
400(no code)Invalid parameter, such as a malformed phone, limit out of range or before that is not a date
403MISSING_SCOPEThe key does not have the whatsapp:read permission
404NUMBER_NOT_FOUNDThe number does not exist in this workspace

See the full format in Errors.

Frequently asked questions

See also

On this page