Listar Logs de Mensagens

GET https://pilotstatus.com.br/v1/messages

Lista os logs de mensagens — enviadas e recebidas — do número de WhatsApp vinculado à sua chave de API, das mais recentes para as mais antigas, com paginação e filtros. Para o detalhe completo de uma única mensagem, use GET /v1/messages/{messageId}.

A página Logs & Analytics do painel é a contraparte visual deste endpoint — as mesmas linhas, filtros e status que você vê lá são o que este endpoint retorna em JSON.

Cabeçalhos

x-api-key: ps_... (ou x-api-key-id: <api_key_id>) — uma chave com escopo de número. Chaves com escopo de tenant recebem 403.

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
`page`	integer	`1`	Número da página (começa em 1).
`pageSize`	integer	`20`	Linhas por página (máx. `100`).
`status`	string (CSV)	—	Filtra por status de entrega: `QUEUED`, `SENT`, `DELIVERED`, `READ`, `PLAYED`, `FAILED`, `CANCELED`. Aceita lista separada por vírgula (ex.: `status=FAILED,CANCELED`). Status de entrega só existem para mensagens enviadas, então este filtro implica somente saídas (outbound).
`direction`	string	—	`in` (recebidas) ou `out` (enviadas). `out` deixa de fora as linhas de saída que não tiveram requisição de envio — veja o aviso em Linhas de saída sem requisição de envio.
`startDate`	string	—	Limite inferior em ISO 8601 sobre `createdAt` (ex.: `2026-02-01T00:00:00.000Z`).
`endDate`	string	—	Limite superior em ISO 8601 sobre `createdAt`. Não pode ser anterior a `startDate`.
`search`	string	—	Um número de telefone em qualquer formato (`+5511999999999`, `5511999999999`, `11 99999-9999`, …) ou o nome de um template.
`templateId`	string	—	Id ou nome do template — retorna apenas mensagens enviadas com esse template.
`window`	string	—	`open` ou `closed` — o estado da janela de atendimento de 24h registrado no momento do envio (veja a nota abaixo).

Janela de atendimento de 24h: o WhatsApp abre uma janela de atendimento de 24 horas sempre que um contato manda mensagem para você. serviceWindowOpenAtSend registra o estado dessa janela no momento em que cada mensagem enviada foi aceita: true significa que foi uma resposta dentro de uma janela aberta e foi enviada imediatamente; false significa que foi um envio “frio” fora da janela — ritmado pelo motor anti-bloqueio em números web do Pilot Status, e exigindo um template aprovado em números Meta Cloud API; null significa que a janela não foi computada (linhas recebidas, destinos de grupo/canal). Filtre com window=open / window=closed.

Exemplos

curl "https://pilotstatus.com.br/v1/messages?page=1&pageSize=20" \
  -H "x-api-key: ps_your_key_here"

curl "https://pilotstatus.com.br/v1/messages?page=1&pageSize=20" \
  -H "x-api-key-id: ck_xxx"

curl "https://pilotstatus.com.br/v1/messages?status=FAILED&direction=out&startDate=2026-02-01T00:00:00.000Z&endDate=2026-02-28T23:59:59.999Z" \
  -H "x-api-key: ps_your_key_here"

Resposta (200)

{
  "data": [
    {
      "id": "msg_abc",
      "correlationId": "corr_123",
      "direction": "OUT",
      "from": "+5511888888888",
      "to": "+5511999999999",
      "content": "Oi João, seu pedido 123 está a caminho!",
      "template": "order_shipped",
      "status": "READ",
      "errorCode": null,
      "errorMessage": null,
      "origin": "API",
      "serviceWindowOpenAtSend": true,
      "createdAt": "2026-02-24T15:00:00.000Z",
      "sentAt": "2026-02-24T15:00:05.000Z",
      "deliveredAt": "2026-02-24T15:00:07.000Z",
      "readAt": "2026-02-24T15:02:11.000Z",
      "externalMessageId": "wamid.HBgLNTUxMTk5OTk5OTk5"
    },
    {
      "id": "msg_def",
      "correlationId": null,
      "direction": "IN",
      "from": "+5511999999999",
      "to": "+5511888888888",
      "content": "Obrigado! Até amanhã.",
      "template": null,
      "status": null,
      "errorCode": null,
      "errorMessage": null,
      "origin": null,
      "serviceWindowOpenAtSend": null,
      "createdAt": "2026-02-24T15:03:40.000Z",
      "sentAt": null,
      "deliveredAt": null,
      "readAt": null,
      "externalMessageId": "wamid.HBgLNTUxMTg4ODg4ODg4"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 2,
  "totalPages": 1
}

Campos da resposta

Campo	Descrição
`id`	Id interno da mensagem — use com `GET /v1/messages/{messageId}` para o detalhe de uma única mensagem.
`correlationId`	Identificador de correlação da requisição de envio. `null` em linhas recebidas e em linhas de saída que não tiveram requisição de envio (veja Linhas de saída sem requisição de envio).
`direction`	`IN` (recebida) ou `OUT` (enviada).
`from` / `to`	Telefones de remetente e destinatário.
`content`	Texto da mensagem. `null` quando redigido pelo modo de retenção de PII do número.
`template`	Nome do template em envios de template; caso contrário, `null`.
`status`	Status de entrega das mensagens enviadas (`QUEUED`, `SENT`, `DELIVERED`, `READ`, `PLAYED`, `FAILED`, `CANCELED`) — veja Status da Mensagem. `null` em linhas recebidas.
`errorCode` / `errorMessage`	Preenchidos em envios `FAILED` — veja Códigos de Erro do Log. `GET /v1/messages/{messageId}` devolve o mesmo `errorCode` para a mesma mensagem.
`origin`	Por qual trilho o envio saiu. Conjunto completo de valores abaixo.
`serviceWindowOpenAtSend`	`true`, `false` ou `null` — o estado da janela de atendimento de 24h registrado no momento do envio (veja a nota acima).
`createdAt` / `sentAt` / `deliveredAt` / `readAt`	Timestamps do ciclo de vida (ISO 8601).
`externalMessageId`	ID de mensagem do WhatsApp do provedor (wamid).

Retenção: as linhas respeitam o modo de retenção de PII do número. Em números RELAY_ONLY, as linhas retornam redigidas (content: null).

`origin` — por qual trilho a mensagem saiu

Valor	Trilho
`API`	`POST /v1/messages/send` — a API pública
`MCP`	A ferramenta do servidor MCP da Pilot Status
`CHATWOOT`	Resposta de atendente vinda de uma inbox do Chatwoot. Numa inbox de espelho por API, quem envia é a Pilot Status e a linha é um envio normal. Numa inbox nativa WhatsApp Cloud, o próprio Chatwoot envia pela camada Meta — veja abaixo
`CHAT`	O chat do painel da Pilot Status
`DASHBOARD`	Um preview de template enviado pelo painel
`SYSTEM`	Emitido pela plataforma (boas-vindas de onboarding e outros envios internos)
`APP`	Saída, mas não por nós — o negócio enviou pelo app WhatsApp Business no celular, ou por outra ferramenta na mesma WABA. Num número Meta essas linhas vêm dos webhooks `message_echoes` / `smb_message_echoes`
`LAYER`	Enviada pela camada Meta da Pilot Status por um cliente que não é uma inbox nativa do Chatwoot — por exemplo, o seu próprio código chamando a Graph API com a sua chave `ps_`
`null`	Uma mensagem recebida — ou uma de saída cuja origem de envio não é nenhuma das acima

origin: null não significa “recebida”. Para isso leia o direction. Um null numa linha OUT significa que o envio carregava uma origem que não mapeamos para uma etiqueta pública; trate como “saída não classificada”, não como tráfego recebido, ou um relatório de cobrança vai subcontar os seus próprios envios em silêncio.

O conjunto cresce. Trate um valor que você não reconhece como “saída não classificada”, não como erro.

Linhas de saída sem requisição de envio

Três tipos de linha OUT não foram enviados pela Pilot Status, então não há requisição de envio por trás deles: APP, LAYER e CHATWOOT vindo de uma inbox nativa WhatsApp Cloud. Nessas linhas:

correlationId, template, serviceWindowOpenAtSend, errorCode e errorMessage são null;
GET /v1/messages/{messageId} responde 404 — a linha da lista é tudo o que existe;
o status segue os status que a Meta informa: SENT, DELIVERED, READ ou FAILED;
a mensagem não conta no consumo de mensagens do seu plano;
num número cujo modo de retenção de PII redige a linha, to e content vêm null e redacted: true é acrescentado, como em qualquer outra linha.

Uma linha CHATWOOT vinda de uma inbox de espelho por API é um envio normal: tem correlationId e detalhe completo. Em linhas LAYER e linhas CHATWOOT de inbox nativa, o content é o que a requisição à Graph API trazia: o texto, a legenda da mídia ou o texto do corpo de uma mensagem interativa. Três tipos recebem um texto curto gerado no lugar:

um template aparece como Template: <nome> — o corpo renderizado não é guardado, e template continua null;
uma localização aparece como Location: <latitude>, <longitude>, seguida do nome e do endereço quando a requisição os trazia;
contatos aparecem como Contacts: <nomes>.

Áudio e figurinha vêm com content: null. Uma linha CHATWOOT de inbox nativa:

{
  "id": "cm_01J9...",
  "correlationId": null,
  "direction": "OUT",
  "from": "+5511911111111",
  "to": "5511988887777",
  "content": "resposta do atendente",
  "template": null,
  "status": "SENT",
  "errorCode": null,
  "errorMessage": null,
  "origin": "CHATWOOT",
  "serviceWindowOpenAtSend": null,
  "createdAt": "2026-10-06T18:00:00.000Z",
  "sentAt": "2026-10-06T18:00:00.000Z",
  "deliveredAt": null,
  "readAt": null,
  "externalMessageId": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjA="
}

Os filtros status, direction=out, templateId e window deixam essas linhas de fora. Eles só devolvem mensagens que tiveram requisição de envio, então linhas APP, LAYER e CHATWOOT de inbox nativa nunca casam com eles, mesmo sendo OUT. Para obter essas linhas, liste sem esses filtros (startDate, endDate e uma search por telefone as mantêm) e leia direction e origin.

Linhas LAYER, e linhas CHATWOOT de inbox nativa, só são registradas a partir do momento em que a Pilot Status começou a registrar os envios pela camada para o número. Envios anteriores não são recuperados. O que é e o que não é registrado: Camada Meta → Envios ficam registrados nos Logs.

Erros comuns

Status	Significado
`400`	`INVALID_DATE_RANGE` — `startDate`/`endDate` malformados, ou `endDate` anterior a `startDate`
`401`	Cabeçalho de chave de API ausente/inválido (`x-api-key` / `x-api-key-id`)
`403`	Chave com escopo de tenant usada em endpoint com escopo de número

Visão Geral

Mensagens

Modelos

Números

Linhas Telefônicas

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

GET /v1/messages — Listar Logs de Mensagens

Listar Logs de Mensagens

Cabeçalhos

Parâmetros de query

Exemplos

Resposta (200)

Campos da resposta

`origin` — por qual trilho a mensagem saiu

Linhas de saída sem requisição de envio

Erros comuns

​Listar Logs de Mensagens

​Cabeçalhos

​Parâmetros de query

​Exemplos

​Resposta (200)

​Campos da resposta

​origin — por qual trilho a mensagem saiu

​Linhas de saída sem requisição de envio

​Erros comuns

Listar Logs de Mensagens

Cabeçalhos

Parâmetros de query

Exemplos

Resposta (200)

Campos da resposta

`origin` — por qual trilho a mensagem saiu

Linhas de saída sem requisição de envio

Erros comuns