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
Número da página (≥ 1).
Resultados por página (1–100).
Efeito do modo PII
A resposta depende do modo PII configurado para o número (definido viaPATCH /api/whatsapp-numbers/[id]). 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.
| Modo PII | Efeito |
|---|---|
STORE_INDEFINITE (padrão) | Todas as mensagens não lidas são retornadas na íntegra, redacted: false. |
STORE_X_DAYS | Os envelopes continuam sendo retornados, mas as linhas fora da janela de retenção são redigidas (content/from/media/remetente anulados, redacted: true); as linhas dentro da janela são retornadas na íntegra. |
RELAY_ONLY | O redigir-e-mostrar se aplica a todas as linhas (redacted: true) e a resposta adiciona um campo notice: "PII_RELAY_ONLY". Na prática, números RELAY_ONLY não armazenam nada, então a lista costuma ficar vazia (messages: [], total: 0). |
Exemplo
Campos do objeto de mensagem
ID interno da mensagem no Pilot Status.
ID da conversa pai.
Contagem total de mensagens não lidas dessa conversa.
Sempre
"INBOUND" para este endpoint.text, image, audio, video, document, location, contacts, sticker ou reaction.Texto da mensagem ou legenda, quando disponível.
Remetente no formato E.164.
Nome de exibição do remetente (resolvido a partir da conversa), quando disponível.
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úmerosMETA— passe-o paraGET /v1/media/{mediaId}para baixar os bytes;nullpara 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 tantoidquantourl); o provedor não oficial fornece seu próprio link. Melhor esforço — pode sernull.media.mimeType— Tipo MIME da mídia quando conhecido (pode sernull).media.fileName— Nome do arquivo da mídia quando conhecido (pode sernull).
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.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.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çalhox-api-keyausente ou inválido.403— chave com escopo de tenant usada (é necessária uma chave com escopo de número).