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}| Parameter | Required | Rule |
|---|---|---|
numberId | yes | Workspace number (list the numbers) |
limit | no | How many conversations, from 1 to 100. Default: 50 |
before | no | ISO 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 }
}
]| Field | Description |
|---|---|
threadId | Conversation in XBASE |
phone | Contact's phone with country code, digits only |
contact | Contact of the conversation (id and name), or null |
lastActivityAt | Last activity of the conversation. Use it in before to get the next page |
lastMessage | Last message, in the messages format (without status and author), or null |
unansweredCount | Messages from the contact after the company's last reply |
window | The 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.
| Parameter | Required | Rule |
|---|---|---|
numberId | yes | Workspace number |
limit | no | How many messages, from 1 to 200. Default: 50 (the most recent) |
before | no | ISO 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
| Field | Description |
|---|---|
id | Message id in XBASE |
messageId | Message id at Meta (wamid.…), the same as in the webhooks. Use it to react or mark as read. May be null |
direction | in: from the contact. out: from the company (person, agent or API) |
type | text, image, audio, video, document, sticker, location, template, interactive… |
text | Text, caption or audio transcript. A template comes with its variables filled in. Media without text comes with a label, such as [imagem] |
at | When the message was recorded |
status | Delivery status: submitted, sent, delivered, read, deleted or error. On received messages, usually null |
author | Who 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
| Field | Description |
|---|---|
window.open | true: a free-form message can be sent now |
window.expiresAt | When the window closes (24 hours after the contact's last message), or null |
window.reason | With 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
beforethelastActivityAtof the last conversation you received. A list shorter thanlimitis the last page. - Messages: send in
beforetheatof the first message you received to get the older ones.
Errors
| Status | code | When |
|---|---|---|
| 400 | (no code) | Invalid parameter, such as a malformed phone, limit out of range or before that is not a date |
| 403 | MISSING_SCOPE | The key does not have the whatsapp:read permission |
| 404 | NUMBER_NOT_FOUND | The number does not exist in this workspace |
See the full format in Errors.