WhatsApp: ler as conversas pela API
Liste as conversas de um número de WhatsApp e leia as mensagens de um contato pela API da XBASE, com a janela de 24 horas de cada conversa.
Atualizado em
Com a leitura de conversas, o seu sistema ou agente vê o que o contato escreveu, o que a empresa respondeu e se a janela de 24 horas está aberta, antes de decidir entre uma mensagem livre e um template. As duas rotas só leem: nada muda na conversa.
A chave precisa da permissão whatsapp:read (Ler conversas do WhatsApp na tela de chaves).
Listar as conversas
GET https://api.xbase.app/api/external/v1/whatsapp/conversations?numberId={numberId}| Parâmetro | Obrigatório | Regra |
|---|---|---|
numberId | sim | Número do workspace (listar os números) |
limit | não | Quantas conversas, de 1 a 100. Padrão: 50 |
before | não | Data ISO 8601. Traz as conversas com atividade antes dela (veja paginação) |
curl "https://api.xbase.app/api/external/v1/whatsapp/conversations?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b&limit=20" \
-H "Authorization: Bearer $XBASE_API_KEY"Resposta 200, da conversa mais recente para a mais antiga:
[
{
"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": "O pedido já saiu?",
"at": "2026-11-07T14:02:11.000Z"
},
"unansweredCount": 2,
"window": { "open": true, "expiresAt": "2026-11-08T14:02:11.000Z", "reason": null }
}
]| Campo | Descrição |
|---|---|
threadId | Conversa na XBASE |
phone | Telefone do contato com DDI, só dígitos |
contact | Contato da conversa (id e name), ou null |
lastActivityAt | Última atividade da conversa. Use em before para buscar a próxima página |
lastMessage | Última mensagem, no formato das mensagens (sem status e author), ou null |
unansweredCount | Mensagens do contato depois da última resposta da empresa |
window | Janela de 24 horas da conversa |
Ler uma conversa
GET https://api.xbase.app/api/external/v1/whatsapp/conversations/{phone}?numberId={numberId}phone é o telefone do contato com DDI. +, espaços, hífens e parênteses são removidos.
| Parâmetro | Obrigatório | Regra |
|---|---|---|
numberId | sim | Número do workspace |
limit | não | Quantas mensagens, de 1 a 200. Padrão: 50 (as mais recentes) |
before | não | Data ISO 8601. Traz as mensagens anteriores a ela |
curl "https://api.xbase.app/api/external/v1/whatsapp/conversations/5521999990000?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Resposta 200, com as mensagens em ordem cronológica:
{
"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": "Olá Maria, o seu pedido 12345 foi entregue em 04/11 às 14:28.",
"at": "2026-11-07T13:40:02.000Z",
"status": "read",
"author": "Integração da loja"
},
{
"id": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21",
"messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABIYFDNBMjc1QjE3RjdCNEE1QzlEMjA4AA==",
"direction": "in",
"type": "text",
"text": "O pedido já saiu?",
"at": "2026-11-07T14:02:11.000Z",
"status": null,
"author": null
}
]
}Se o telefone nunca conversou com o número, a resposta também é 200: threadId nulo, messages vazio e a janela fechada com reason: "no_contact_message". Para iniciar a conversa, envie um template.
Mensagens
| Campo | Descrição |
|---|---|
id | Id da mensagem na XBASE |
messageId | Id da mensagem na Meta (wamid.…), o mesmo dos webhooks. Use para reagir ou marcar como lida. Pode ser null |
direction | in: do contato. out: da empresa (pessoa, agente ou API) |
type | text, image, audio, video, document, sticker, location, template, interactive… |
text | Texto, legenda ou transcrição do áudio. Template vem com as variáveis preenchidas. Mídia sem texto vem com um rótulo, como [imagem] |
at | Quando a mensagem foi registrada |
status | Situação do envio: submitted, sent, delivered, read, deleted ou error. Nas mensagens recebidas, em geral null |
author | Quem mandou pela empresa: o nome da pessoa, do agente ou da chave de API |
A mídia (imagem, áudio, documento) não vem na resposta. Registros da conversa que não são mensagem, como troca de etiqueta ou de etapa, ficam de fora.
Janela de 24 horas
| Campo | Descrição |
|---|---|
window.open | true: uma mensagem livre pode ser enviada agora |
window.expiresAt | Quando a janela fecha (24 horas depois da última mensagem do contato), ou null |
window.reason | Com a janela fechada: no_contact_message (o contato nunca escreveu), window_expired (passou de 24 horas) ou awaiting_template_reply (a empresa mandou um template e o contato ainda não respondeu). null com a janela aberta |
A leitura usa a mesma regra do envio: com open: true, POST /whatsapp/messages não recusa por janela fechada naquele momento.
Paginação
- Conversas: mande em
beforeolastActivityAtda última conversa recebida. Uma lista menor que olimité a última página. - Mensagens: mande em
beforeoatda primeira mensagem recebida para buscar as anteriores.
Erros
| Status | code | Quando |
|---|---|---|
| 400 | (sem code) | Parâmetro inválido, como telefone fora do formato, limit fora da faixa ou before que não é data |
| 403 | MISSING_SCOPE | A chave não tem a permissão whatsapp:read |
| 404 | NUMBER_NOT_FOUND | O número não existe neste workspace |
Veja o formato completo em Erros.