Skip to main content
Recupere mensagens de conversas de GRUPO para o número conectado.

​
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.
Números Meta: este endpoint também funciona para números oficiais da Meta Cloud API, desde que o número seja uma Conta Comercial Oficial (Official Business Account) aprovada com grupos habilitados. Números que não são elegíveis retornam 400 META_GROUPS_NOT_ELIGIBLE.

​
Parâmetros de query

​
string
Data/hora ISO 8601. Filtra mensagens criadas na data ou depois desta data.
​
string
Data/hora ISO 8601. Filtra mensagens criadas na data 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 createdAt de forma decrescente (mais recentes primeiro).

​
Efeito do modo PII

A resposta depende do modo PII configurado para o número — alterado no painel, na página API Keys (painel Privacidade & retenção) ou nas configurações do número em Números. 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.

​
Exemplo

​
Campos do objeto de mensagem

​
string
obrigatório
ID interno da mensagem no Pilot Status.
​
string
obrigatório
ID da conversa de grupo pai.
​
string
obrigatório
"INBOUND" (recebida no grupo) ou "OUTBOUND" (enviada ao grupo).
​
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 no WhatsApp quando disponível.
​
string
obrigatório
JID do grupo (ex.: 120363123456789012@g.us).
​
string | null
Nome de exibição do grupo 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 inbound 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. É best-effort — 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 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.
​
string
obrigatório
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 — 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).