Listar mensagens
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.
Parâmetros de consulta
directionstringSó os envios (out) ou só as mensagens recebidas (in). Não muda counts.
"in", "out"statusstringSó as mensagens neste estado: queued (na fila), sent (enviada), delivered (entregue), read (lida), failed (falhou) ou received (recebida).
"queued", "sent", "delivered", "read", "failed", "received"tenantIdstringFiltra 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.
connectionIdstringSó 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.
qstringBusca, 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.
limitintegerQuantas 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.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | messages, 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. |
| 400 | FST_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. |
| 401 | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 403 | A chave não tem o escopo logs:read; a mensagem cita o escopo (This credential lacks the logs:read scope). |
| 404 | O 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. |
| 429 | Requisiçõ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