Buscar mensagens

GET /messages lê as mensagens guardadas da inbox, da mais nova para a mais antiga. Cada item é a mensagem, no mesmo formato do envio e dos eventos.

GET /messages?chat_id=5511999999999&limit=20

{
  "messages": [
    {
      "id": "3EB0A1...",
      "type": "text",
      "text": "oi",
      "...": "..."
    }
  ],
  "next_cursor": "MTc5MjIzODQwMDAwMHwzRUIwQTE"
}

Paginação

limit: de 1 a 200 itens por página (padrão 50).
next_cursor: vem enquanto houver mais. Para a próxima página, repita a mesma busca com cursor=<next_cursor>. Sem next_cursor, acabou.
Não pula nem repete: o cursor marca a posição exata (o horário e o id da última mensagem lida). Mensagem que chega enquanto você pagina não empurra as outras: ela aparece numa busca nova, do começo.
Página com menos itens não quer dizer fim. Com um filtro raro (por exemplo type=sticker numa inbox com muitas mensagens), a api para de procurar depois de um certo volume e devolve o que achou, até vazio, com next_cursor. Continue enquanto vier next_cursor.

Filtros

Todos são opcionais e se combinam, menos o message_id: com message_id, a busca devolve aquela mensagem e ignora os outros filtros.

Filtro	O que faz
`chat_id`	Só desta conversa. Aceita o número (com ou sem `+`, com ou sem o nono dígito), o id do WhatsApp, o LID ou o id do grupo. A api inclui as outras formas da mesma conversa (o LID de um número e o número de um LID), porque o WhatsApp guarda mensagens das duas.
`message_id`	Uma mensagem só, pelo `id` dela. Volta numa lista com um item (ou vazia).
`direction`	`in` (do contato) ou `out` (da inbox).
`type`	Tipos, separados por vírgula (`image,video`). Tipo desconhecido responde `400`.
`category`	Classes, separadas por vírgula (veja abaixo).
`track_source`, `track_id`	As mensagens que você enviou com esse rastreamento.
`after`, `before`	Enviadas depois ou antes de uma data (ISO 8601). Os limites não entram: `after` é "depois de", não "a partir de".

Classes (`category`)

Vem em cada mensagem (campo category), dado pela api: leia o campo em vez de deduzir do type ou do status. Só conversation não apagada aceita resposta, reação, edição e fixar.

`category`	O que entra
`conversation`	As mensagens da conversa (texto, mídia, botões...): o que aparece como balão, apagada inclusive.
`reaction`	Reações.
`call`	Ligações.
`event`	O que não é balão: edição, voto de enquete, fixar, registros do grupo e do sistema (alguém entrou, mudou o nome do grupo...).
`unsent`	Envios que ainda não chegaram ao canal: agendado, na fila, enviando, com falha ou cancelado.

Para mostrar uma conversa como no WhatsApp: category=conversation,call,event.

Sem `chat_id`

A busca percorre a inbox toda, o que serve para sincronizar ("o que chegou desde ontem?": after=2026-10-16T00:00:00.000Z). As publicações de Status (status@broadcast) ficam de fora; para elas, filtre por chat_id=status@broadcast.

O que a busca vê

Mensagens recebidas e enviadas, inclusive as que ainda estão sendo gravadas (a busca junta o que está em memória com o que já foi gravado, sem repetir).
O status mais recente de cada mensagem.
O nome de quem escreveu (author.name), da agenda. A mensagem traz só o chat_id; o nome da conversa vem em GET /chats.
Não traz miniatura (nem da mídia, nem do link, da localização ou do convite; ela vem só no evento em tempo real) nem o arquivo: o url vem quando o arquivo já foi baixado.