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.

​
Coexistência: o que de fato cai aqui

Num número Meta em coexistência, a Meta envia o histórico do aparelho depois do pareamento, em pedaços, pelo webhook interno history. O que disso você consegue reler aqui é mais estreito do que o que a Meta manda, em três pontos específicos.
1 — A janela de importação é de 30 dias, não de seis meses. Tudo o que a Meta entrega é filtrado contra connectedAt − 30 dias (caindo para createdAt em números anteriores à coluna). Mensagens mais antigas chegam e são descartadas — nunca são gravadas, então nenhum endpoint consegue devolvê-las depois. A Meta pode muito bem mandar seis meses; só os últimos 30 dias antes da conexão sobrevivem.
2 — Nada é gravado se historyImportEnabled não estava true ANTES de o número conectar. Com ele desligado, a entrega de history inteira é descartada na chegada e este endpoint responde como se o número não tivesse passado.Número novo nasce com true. Números criados entre 2026-08-25 e 2026-09-16 nasceram com false e continuam false — a mudança de padrão não altera linha existente, porque desde 25/08 o painel pergunta antes de conectar e um false ali pode ser escolha real. Se o número é anterior, confirme o valor em vez de assumir.⛔ Não adianta ligar depois. A Meta entrega o histórico uma vez só, logo após o pareamento; um PATCH posterior chega tarde e o que o aparelho entregou já foi descartado. Mande no POST /v1/numbers/remote-pairing, que aceita o bloco settings.E não dá para corrigir depois: a Meta entrega o histórico uma vez, logo após o pareamento, e não há como pedir de novo. Defina na chamada de pareamento — o POST /v1/numbers/remote-pairing aceita o mesmo bloco settings — e não num PATCH posterior, que corre contra a rajada. Veja configurações do número.
Para diagnosticar um resultado vazio: GET /v1/numbers/{id} → historyImport diz se o histórico chegou e foi descartado (discarded) ou se a Meta recusou enviá-lo (syncRefused).
3 — Num número Meta, o histórico importado nunca é entregue aos seus webhooks, nem com webhookHistoricalMessages: true. Essa flag governa o trilho Evolution (QR), onde o replay realmente despacha message.received. O caminho history da Meta só persiste as linhas; ele não tem despacho de webhook. (history é também um dos nove campos da Meta que nunca são encaminhados nativamente, nem para uma assinatura "*".)Ou seja: num número Meta este endpoint é a única forma de ler o que foi importado. Consulte-o depois do pareamento, em vez de esperar entregas que não virão.
Contatos não têm endpoint próprio. O que você tem é o interlocutor de cada conversa — telefone e, quando o WhatsApp forneceu, o nome de perfil — via GET /v1/conversations e as linhas de mensagem daqui. Não existe importação de agenda separada para ler.

​
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
De onde veio uma mensagem enviada, quando registrado: APP — enviada pelo app WhatsApp Business no celular ou por outra ferramenta na mesma WABA; CHATWOOT — resposta de atendente vinda de uma inbox nativa WhatsApp Cloud do Chatwoot, enviada pela camada Meta; LAYER — enviada pela camada Meta por qualquer outro cliente. Uma mensagem que a própria Pilot Status enviou pode vir com API ou null. null em mensagens recebidas: leia direction para distinguir enviada de recebida. O conjunto cresce, então trate um valor que você não reconhece como mensagem enviada.
​
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).