Skip to main content
Recupere as mensagens recebidas que contam como não lidas para o número conectado. O estado de não lida não é derivado de um campo readAt por mensagem (o readAt por mensagem não é mantido para mensagens recebidas). Em vez disso, ele é derivado do unreadCount de cada conversa — o mesmo contador exibido no painel — e o total da resposta é a soma do unreadCount entre as conversas não lidas. Cada item inclui essa contagem de não lidas no nível da conversa.

​
Endpoint

GET https://pilotstatus.com.br/v1/messages/unread
Requer uma chave de API com escopo de número (ps_*) no cabeçalho x-api-key. Chaves com escopo de tenant retornam 403.

​
Parâmetros de query

​
integer
padrão:"1"
Número da página (≥ 1).
​
integer
padrão:"30"
Resultados por página (1–100).
Não há filtro de intervalo de datas neste endpoint; ele retorna todas as mensagens recebidas atualmente não lidas.

​
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). Este endpoint usa redigir-e-mostrar (redact-and-show): ele não aplica um filtro rígido por data de retenção — os envelopes das mensagens continuam sendo retornados, mas content, from, media e fromName/remetente são anulados e redacted: true é definido nas linhas cobertas pela política de PII.

​
Exemplo

​
Campos do objeto de mensagem

​
string
obrigatório
ID interno da mensagem no Pilot Status.
​
string
obrigatório
ID da conversa pai.
​
integer
obrigatório
Contagem total de mensagens não lidas dessa conversa.
​
string
obrigatório
Sempre "INBOUND" para este endpoint.
​
string
obrigatório
text, image, audio, video, document, location, contacts, sticker ou reaction.
​
string | null
Texto da mensagem ou legenda, quando disponível.
​
string
obrigatório
Remetente no formato E.164.
​
string | null
Nome de exibição do remetente (resolvido a partir da conversa), quando disponível.
​
object | null
Descritor de mídia { provider, id, url, mimeType, fileName } quando a mensagem carrega mídia; null para texto.
  • 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 (então 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 da mídia quando conhecido (pode ser null).
​
boolean
true quando content, media e os campos do remetente foram anulados pela política de PII do número (veja Efeito do modo PII); false (ou ausente) quando a linha é retornada na íntegra.
​
null
obrigatório
Sempre null — o readAt por mensagem não é mantido para mensagens recebidas; o estado de não lida é rastreado no nível da conversa via conversationUnreadCount.
​
string
obrigatório
ISO 8601 — quando a mensagem foi recebida.

​
Erros comuns

  • 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 usada (é necessária uma chave com escopo de número).