Endpoint
GET https://pilotstatus.com.br/v1/messages/group
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
Data/hora ISO 8601. Filtra mensagens criadas na data ou depois desta data.
Data/hora ISO 8601. Filtra mensagens criadas na data ou antes desta data.
Número da página (≥ 1).
Resultados por página (1–100).
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 createdAt de forma decrescente (mais recentes primeiro).
Efeito do modo PII
A resposta depende do modo PII configurado para o número (definido viaPATCH /api/whatsapp-numbers/[id]).
Os limites inferior e superior da consulta vêm apenas dos startDate / endDate informados pelo chamador — o modo PII nunca restringe o intervalo de datas consultado. Em vez disso, as linhas que ficam fora da janela de retenção de PII do número ainda são retornadas, mas redigidas: seus campos content, media e de participante/peer são definidos como null e a linha carrega redacted: true.
| Modo PII | Efeito |
|---|---|
STORE_INDEFINITE (padrão) | Todas as mensagens de grupo são retornadas por completo (sujeito a startDate / endDate). |
STORE_X_DAYS | Todas as linhas correspondentes são retornadas. Linhas mais antigas que a janela de retenção são redigidas (campos content, media e de participante como null, redacted: true); linhas dentro da janela são retornadas por completo. |
RELAY_ONLY | Todas as linhas correspondentes são retornadas, mas todas as linhas são redigidas (campos content, media e de participante como null, redacted: true), e a resposta inclui um campo notice: "PII_RELAY_ONLY". |
Exemplo
Campos do objeto de mensagem
ID interno da mensagem no Pilot Status.
ID da conversa de grupo pai.
"INBOUND" (recebida no grupo) ou "OUTBOUND" (enviada ao grupo).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 no WhatsApp quando disponível.
JID do grupo (ex.:
120363123456789012@g.us).Nome de exibição do grupo 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 inbound da META é espelhada no S3 (então mensagens META geralmente carregam tantoidquantourl); o provedor não oficial fornece seu próprio link. É best-effort — 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 a linha fica fora da janela de retenção de PII do número (ou em todas as linhas no caso de RELAY_ONLY). Linhas redigidas ainda aparecem na lista, mas os campos content, media e de participante/peer ficam null.ISO 8601 — quando a mensagem foi criada.
Erros comuns
400 META_GROUPS_NOT_ELIGIBLE— a chave de API está vinculada a um número da Meta Cloud API que não é uma Conta Comercial Oficial (Official Business Account) aprovada (ou não tem grupos habilitados).400 INVALID_DATE_RANGE—startDateouendDatenão é uma string ISO 8601 válida, oustartDate > endDate.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 utilizada (é necessária uma chave com escopo de número).