Skip to main content
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.
Este endpoint é o jeito de ler mensagem antiga. O seu webhook não as replica: quando um número conecta, o histórico do aparelho é importado para o chat mas não é entregue como evento message.received. Veja PATCH /v1/numbers/{id} se quiser ligar essa entrega num número.

​
Parâmetros de query

​
string
Data/hora ISO 8601. Filtra mensagens com providerTimestamp em ou após esta data.
​
string
Data/hora ISO 8601. Filtra mensagens com providerTimestamp em ou antes desta data.
​
integer
padrão:"1"
Número da página (≥ 1).
​
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 no painel, no painel Privacidade & retenção da página API Keys ou nas configurações do número). 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.

​
Exemplo

​
Campos do objeto de mensagem

​
string
obrigatório
ID interno da mensagem no Pilot Status.
​
string
obrigatório
ID da conversa pai (direta ou em grupo).
​
string
obrigatório
"INBOUND" (recebida) ou "OUTBOUND" (enviada).
​
string
obrigatório
Provedor que processou a mensagem (PILOT_STATUS, META, …).
​
string | null
ID da mensagem no provedor (ex.: wamid da Meta) quando disponível.
​
string
obrigatório
Status da mensagem (QUEUED, SENT, DELIVERED, READ, FAILED, …).
​
string
obrigatório
text, image, audio, video, document, location, contacts, sticker ou reaction.
​
string | null
Origem de uma mensagem enviada (ex.: APP, API) quando disponível.
​
string | null
Texto ou legenda da mensagem quando disponível.
​
string | null
Nome de exibição do WhatsApp da contraparte/remetente quando disponível.
​
string | null
Contraparte/remetente no formato E.164 quando disponível.
​
string | null
externalMessageId da mensagem à qual esta responde, quando disponível.
​
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).
​
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.
​
string | null
ISO 8601 — quando a mensagem foi enviada.
​
string | null
ISO 8601 — quando a mensagem foi entregue.
​
string | null
ISO 8601 — quando a mensagem foi lida (apenas quando as confirmações de leitura estão habilitadas).
​
string
obrigatório
ISO 8601 — timestamp do provedor para a mensagem (chave de ordenação).
​
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).