Pular para o conteúdo principal
GET
/
wa
/
messages
Listar mensagens
curl --request GET \
  --url https://api.zapsterapi.com/v1/wa/messages \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "id": "msg_k7m2nxp9q4",
      "instance_id": "inst_xyz",
      "recipient": "5511999999999",
      "status": "sent",
      "connection_type": "waba",
      "send_at": "2026-03-30T12:00:00.000Z",
      "message_id": "wamid.HBgMNTU4...",
      "errors": [
        {
          "code": 131047,
          "title": "Re-engagement message",
          "details": "Message failed to send because more than 24 hours have passed since the customer last replied.",
          "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
        }
      ],
      "created_at": "2026-03-28T10:30:00.000Z",
      "sent_at": "2026-03-28T10:30:01.000Z",
      "delivered_at": "2026-03-28T10:30:05.000Z",
      "read_at": "2026-03-28T10:32:00.000Z",
      "canceled_at": null
    }
  ],
  "meta": {
    "next_cursor": "2026-03-28T09:00:00.000Z",
    "has_more": true,
    "limit": 20
  }
}
Lista todas as mensagens enviadas e agendadas dentro de um período. Retorna informações de status, entrega e leitura de cada mensagem.

Parâmetros obrigatórios

Os campos from 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:
PlanoRetenção do histórico
Essential24 horas
Pro30 dias
Enterprise180 dias

Filtros disponíveis

Você pode combinar qualquer filtro na mesma requisição:
FiltroDescriçãoExemplo
statusFiltrar por status da mensagemstatus=scheduled
instance_idFiltrar por instânciainstance_id=inst_xyz
recipientFiltrar por destinatáriorecipient=5511999999999
message_idBuscar pelo ID do WhatsAppmessage_id=wamid.HBgM...
connection_typeFiltrar por tipo de conexãoconnection_type=waba

Paginação

A listagem usa paginação cursor-based. Cada resposta inclui um objeto meta com:
  • has_more: indica se existem mais resultados
  • next_cursor: valor para passar no parâmetro after da próxima requisição
  • limit: quantidade de itens por página
Para navegar entre páginas:
  1. Faça a primeira requisição sem o parâmetro after
  2. Se has_more for true, pegue o valor de next_cursor
  3. Faça a próxima requisição com after=<valor do next_cursor>
  4. Repita até has_more ser false
O padrão é 20 itens por página. Você pode ajustar com o parâmetro limit (mínimo 1, máximo 100).

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ódigoDescrição
131047Janela de 24 horas expirada (precisa de template)
132000Template não encontrado ou parâmetros incorretos
132001Template não existe na tradução informada

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de consulta

from
string<date-time>
obrigatório

Início do período no formato ISO 8601

to
string<date-time>
obrigatório

Fim do período no formato ISO 8601

instance_id
string

Filtrar por ID da instância

status
enum<string>

Filtrar por status da mensagem

Opções disponíveis:
pending,
scheduled,
sent,
failed,
canceled
recipient
string

Filtrar por destinatário (número de telefone)

message_id
string

Buscar pelo ID do WhatsApp (wamid)

connection_type
enum<string>

Filtrar por tipo de conexão (oficial ou não oficial)

Opções disponíveis:
waba,
unofficial
after
string<date-time>

Cursor para a próxima página (valor de next_cursor da resposta anterior)

limit
integer
padrão:20

Quantidade de itens por página (1 a 100, padrão 20)

Intervalo obrigatório: 1 <= x <= 100

Resposta

Lista de mensagens com paginação

data
object[]
meta
object