Pular para o conteúdo

Listar mensagens

GET/messages

Lista as mensagens registradas do projeto, das mais novas para as mais antigas: os envios feitos pela API (POST /connections/{id}/send) e as mensagens recebidas. Cada linha traz o estado atual da mensagem e o histórico de mudanças em events. counts aplica todos os filtros menos direction, para mostrar quantas há em cada direção de uma vez. Escopo necessário: logs:read.

Ver em Markdown

Parâmetros de consulta

directionstring

Só os envios (out) ou só as mensagens recebidas (in). Não muda counts.

Valores: "in", "out"
statusstring

Só as mensagens neste estado: queued (na fila), sent (enviada), delivered (entregue), read (lida), failed (falhou) ou received (recebida).

Valores: "queued", "sent", "delivered", "read", "failed", "received"
tenantIdstring

Filtra por projeto (tenantId). Com uma chave de API, a lista já cobre só o projeto da chave, então este filtro só aceita esse mesmo projeto; outro responde 404.

connectionIdstring

Só as mensagens de uma conexão (o número). Uma conexão que não é do projeto da chave não dá erro: a lista vem vazia.

qstring

Busca, sem diferenciar maiúsculas de minúsculas, em contact, body, jobId, clientRef e messageId. Um telefone formatado (+55 (11) 98888-7777) também encontra o contato guardado só com dígitos.

limitinteger

Quantas linhas trazer, das mais novas para as mais antigas. Padrão 60; um valor acima de 200 é tratado como 200. Não há paginação: para ver linhas mais antigas, estreite os filtros.

mínimo 1padrão: 60

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200messages, as linhas das mais novas para as mais antigas (cada uma com id, tenantId, connectionId, direction, contact, type, body, status, jobId, clientRef, messageId, error, events, createdAt e updatedAt), e counts, com o total de linhas que atendem aos filtros (all) e quantas são recebidas (in) e enviadas (out). Sem nada registrado, a lista vem vazia.
400FST_ERR_VALIDATIONUm filtro não segue o schema da operação: direction ou status fora da lista, ou limit que não é um inteiro maior que zero; message diz o que está errado.
401Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
403A chave não tem o escopo logs:read; a mensagem cita o escopo (This credential lacks the logs:read scope).
404O filtro tenantId aponta para um projeto que não é da chave ({"error": "Tenant not found"}): o projeto de outra pessoa responde exatamente como um que não existe.
429Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After

Detalhes

O que entra no registro. Um envio entra como queued no momento em que é aceito na fila e avança para sent, delivered e read conforme as confirmações do WhatsApp chegam; uma mensagem recebida entra como received. Mensagens digitadas no próprio celular não aparecem aqui (para acompanhá-las, use o evento message.outgoing).

O status só avança. Uma confirmação que chega fora de ordem (um read antes do delivered) nunca faz a linha voltar. failed vale sempre, e uma linha failed ainda pode passar para sent, delivered ou read se o WhatsApp confirmar a mensagem depois. events guarda cada mudança aplicada, com o horário em at.

Os campos de cada linha. direction é out (envio) ou in (recebida). contact é o telefone só com dígitos ou, quando o endereço não é um telefone, a parte antes do @ do JID (um LID ou o id de um grupo). type é text, image, video, audio, document, sticker, location ou, num envio por template, template. body é uma prévia de até 1000 caracteres: o texto, a legenda da mídia, o nome do arquivo ou o nome do local, e null quando não há nada disso. jobId e clientRef só existem nos envios; messageId é o id do WhatsApp, preenchido quando o envio sai ou na mensagem recebida.

Por que falhou. Numa linha failed, error explica o motivo, em português: Número não está no WhatsApp, Número temporariamente restrito pelo WhatsApp para iniciar conversas, Falhou após 3 tentativas, Tempo de processamento esgotado, Cancelado via API ou Falha ao enfileirar. Para reagir a falhas no seu sistema, use os eventos message.send_failed e message.delivery; este registro serve para consulta.

Retenção. Os registros ficam guardados por 7 dias por padrão; depois disso, saem da lista e das contagens.

Guia: Uso e registros

Esta página ajudou? · Atualizado em 28 set 2026