WhatsApp APIAPI

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âmetroObrigatórioRegra
numberIdsimNúmero do workspace (listar os números)
limitnãoQuantas conversas, de 1 a 100. Padrão: 50
beforenãoData 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 }
  }
]
CampoDescrição
threadIdConversa na XBASE
phoneTelefone do contato com DDI, só dígitos
contactContato 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
unansweredCountMensagens do contato depois da última resposta da empresa
windowJanela 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âmetroObrigatórioRegra
numberIdsimNúmero do workspace
limitnãoQuantas mensagens, de 1 a 200. Padrão: 50 (as mais recentes)
beforenãoData 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

CampoDescrição
idId da mensagem na XBASE
messageIdId da mensagem na Meta (wamid.…), o mesmo dos webhooks. Use para reagir ou marcar como lida. Pode ser null
directionin: do contato. out: da empresa (pessoa, agente ou API)
typetext, image, audio, video, document, sticker, location, template, interactive…
textTexto, legenda ou transcrição do áudio. Template vem com as variáveis preenchidas. Mídia sem texto vem com um rótulo, como [imagem]
atQuando a mensagem foi registrada
statusSituação do envio: submitted, sent, delivered, read, deleted ou error. Nas mensagens recebidas, em geral null
authorQuem 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

CampoDescrição
window.opentrue: uma mensagem livre pode ser enviada agora
window.expiresAtQuando a janela fecha (24 horas depois da última mensagem do contato), ou null
window.reasonCom 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 before o lastActivityAt da última conversa recebida. Uma lista menor que o limit é a última página.
  • Mensagens: mande em before o at da primeira mensagem recebida para buscar as anteriores.

Erros

StatuscodeQuando
400(sem code)Parâmetro inválido, como telefone fora do formato, limit fora da faixa ou before que não é data
403MISSING_SCOPEA chave não tem a permissão whatsapp:read
404NUMBER_NOT_FOUNDO número não existe neste workspace

Veja o formato completo em Erros.

Perguntas frequentes

Veja também

Nesta página