Listar Mensagens
Lista todas as mensagens (imediatas e agendadas) dentro de um período. Retorna informações de status, entrega e leitura de cada mensagem. Usa paginação cursor-based para navegar entre páginas de resultados.
O período máximo por consulta é de 90 dias. O quão longe no passado você pode consultar depende do seu plano (retenção do histórico).
Parâmetros obrigatórios
Os camposfrom e to definem o período da consulta. O período máximo é de 90 dias por requisição.
O quão longe no passado você pode consultar depende do seu plano:
| Plano | Retenção do histórico |
|---|---|
| Essential | 24 horas |
| Pro | 30 dias |
| Enterprise | 180 dias |
Filtros disponíveis
Você pode combinar qualquer filtro na mesma requisição:| Filtro | Descrição | Exemplo |
|---|---|---|
status | Filtrar por status da mensagem | status=scheduled |
instance_id | Filtrar por instância | instance_id=inst_xyz |
recipient | Filtrar por destinatário | recipient=5511999999999 |
message_id | Buscar pelo ID do WhatsApp | message_id=wamid.HBgM... |
connection_type | Filtrar por tipo de conexão | connection_type=waba |
Paginação
A listagem usa paginação cursor-based. Cada resposta inclui um objetometa com:
has_more: indica se existem mais resultadosnext_cursor: valor para passar no parâmetroafterda próxima requisiçãolimit: quantidade de itens por página
- Faça a primeira requisição sem o parâmetro
after - Se
has_morefortrue, pegue o valor denext_cursor - Faça a próxima requisição com
after=<valor do next_cursor> - Repita até
has_moreserfalse
Sobre o campo errors
Quando uma mensagem falha (status=failed), o campo errors contém os detalhes do problema. Para instâncias WABA, inclui o código de erro da Meta e um link para a documentação.
Erros comuns:
| Código | Descrição |
|---|---|
| 131047 | Janela de 24 horas expirada (precisa de template) |
| 132000 | Template não encontrado ou parâmetros incorretos |
| 132001 | Template não existe na tradução informada |
Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Parâmetros de consulta
Início do período no formato ISO 8601
Fim do período no formato ISO 8601
Filtrar por ID da instância
Filtrar por status da mensagem
pending, scheduled, sent, failed, canceled Filtrar por destinatário (número de telefone)
Buscar pelo ID do WhatsApp (wamid)
Filtrar por tipo de conexão (oficial ou não oficial)
waba, unofficial Cursor para a próxima página (valor de next_cursor da resposta anterior)
Quantidade de itens por página (1 a 100, padrão 20)
1 <= x <= 100