Pular para o conteúdo principal
Recupere todo o histórico de mensagens armazenado (conversas diretas e em grupo) do número conectado.

​
Endpoint

GET https://pilotstatus.com.br/v1/messages/history
Requer uma chave de API com escopo de número (ps_*) no cabeçalho x-api-key. Chaves com escopo de tenant retornam 403. Você também pode identificar a chave com x-api-key-id: <api_key_id>.Todos os provedores suportados: este endpoint funciona tanto para números não oficiais (Pilot Status web) quanto para números oficiais da Meta Cloud API.

​
Parâmetros de query

​
startDate
string
Data/hora ISO 8601. Filtra mensagens com providerTimestamp em ou após esta data.
​
endDate
string
Data/hora ISO 8601. Filtra mensagens com providerTimestamp em ou antes desta data.
​
page
integer
padrão:"1"
Número da página (≥ 1).
​
pageSize
integer
padrão:"30"
Resultados por página (1–100).
Tanto startDate quanto endDate são opcionais individualmente. Quando fornecidos, cada um deve ser uma string ISO 8601 válida e startDate não pode ser posterior a endDate; caso contrário, 400 INVALID_DATE_RANGE é retornado. Os resultados são ordenados por providerTimestamp de forma decrescente (mais recentes primeiro). O endpoint retorna até aproximadamente um mês de histórico armazenado, contado a partir da data de conexão do número.

​
Efeito do modo PII

A resposta depende do modo PII configurado para o número (definido via PATCH /api/whatsapp-numbers/[id]). Os limites da query vêm exclusivamente dos seus startDate/endDate — a janela PII não é aplicada à query. Em vez disso, as linhas que ficam fora da janela de retenção ainda são retornadas, porém redigidas: a linha está presente (indexada pelo seu providerTimestamp) com redacted: true e com text, media, participantName e participantPhone nulos.
Modo PIIEfeito
STORE_INDEFINITE (padrão)Todas as mensagens são retornadas na íntegra (sujeitas aos filtros de data).
STORE_X_DAYSMensagens dos últimos N dias são retornadas na íntegra. Mensagens mais antigas que piiRetentionDays são retornadas redigidas (redacted: true, com text/media/participantName/participantPhone nulos), indexadas pelo providerTimestamp.
RELAY_ONLYToda mensagem é retornada redigida (redacted: true, com conteúdo/mídia/contraparte nulos) e a resposta inclui um campo notice: "PII_RELAY_ONLY".

​
Exemplo

curl "https://pilotstatus.com.br/v1/messages/history?startDate=2026-06-01T00:00:00Z&endDate=2026-06-30T23:59:59Z&page=1&pageSize=30" \
  -H "x-api-key: ps_your_key_here"

​
Campos do objeto de mensagem (ChatMessageDTO)

​
id
string
obrigatório
ID interno da mensagem no Pilot Status.
​
conversationId
string
obrigatório
ID da conversa pai (direta ou em grupo).
​
direction
string
obrigatório
"INBOUND" (recebida) ou "OUTBOUND" (enviada).
​
providerKind
string
obrigatório
Provedor que processou a mensagem (PILOT_STATUS, META, …).
​
externalMessageId
string | null
ID da mensagem no provedor (ex.: wamid da Meta) quando disponível.
​
status
string
obrigatório
Status da mensagem (QUEUED, SENT, DELIVERED, READ, FAILED, …).
​
messageType
string
obrigatório
text, image, audio, video, document, location, contacts, sticker ou reaction.
​
origin
string | null
Origem de uma mensagem enviada (ex.: APP, API) quando disponível.
​
text
string | null
Texto ou legenda da mensagem quando disponível.
​
participantName
string | null
Nome de exibição do WhatsApp da contraparte/remetente quando disponível.
​
participantPhone
string | null
Contraparte/remetente no formato E.164 quando disponível.
​
repliedToExternalId
string | null
externalMessageId da mensagem à qual esta responde, quando disponível.
​
media
object | null
Descritor de mídia { provider, id, url, mimeType, fileName } quando a mensagem carrega mídia; null caso contrário.
  • media.provider — o provedor que entregou a mídia — "META" para números da Meta Cloud API, ou uma tag interna de provedor para números não oficiais.
  • media.id — ID de mídia da Meta. Definido em números META — passe-o para GET /v1/media/{mediaId} para baixar os bytes; null para números não oficiais.
  • media.url — URL de download direto quando disponível. Mídia recebida da META é espelhada no S3 (portanto mensagens META geralmente carregam tanto id quanto url); o provedor não oficial fornece seu próprio link. Melhor esforço — pode ser null.
  • media.mimeType — Tipo MIME da mídia quando conhecido (pode ser null).
  • media.fileName — Nome do arquivo de mídia quando conhecido (pode ser null).
​
redacted
boolean
true quando a linha fica fora da janela de retenção de PII do número (ou o número está em RELAY_ONLY). Linhas redigidas mantêm seu id, providerTimestamp e os metadados de entrega, mas text, media, participantName e participantPhone são null.
​
sentAt
string | null
ISO 8601 — quando a mensagem foi enviada.
​
deliveredAt
string | null
ISO 8601 — quando a mensagem foi entregue.
​
readAt
string | null
ISO 8601 — quando a mensagem foi lida (apenas quando as confirmações de leitura estão habilitadas).
​
providerTimestamp
string
obrigatório
ISO 8601 — timestamp do provedor para a mensagem (chave de ordenação).
​
createdAt
string
obrigatório
ISO 8601 — quando o registro foi criado no Pilot Status.

​
Erros comuns

  • 400 INVALID_DATE_RANGE — startDate ou endDate não é uma string ISO 8601 válida, ou startDate > endDate.
  • 400 NUMBER_NOT_FOUND — a chave de API não está vinculada a um número de WhatsApp.
  • 401 — cabeçalho x-api-key ausente ou inválido.
  • 403 — chave com escopo de tenant utilizada (é necessária uma chave com escopo de número).