Pular para o conteúdo principal
Liste as conversas do número conectado, ordenadas pela atividade de mensagem mais recente.

​
Endpoint

GET https://pilotstatus.com.br/v1/conversations
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 consulta

​
startDate
string
Datetime ISO 8601. Filtra conversas cuja última mensagem seja igual ou posterior a esta data.
​
endDate
string
Datetime ISO 8601. Filtra conversas cuja última mensagem seja igual ou anterior a esta data.
​
page
integer
padrão:"1"
Número da página (≥ 1).
​
pageSize
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, é retornado 400 INVALID_DATE_RANGE.

​
Efeito do modo PII

A resposta depende do modo PII configurado para o número (definido via PATCH /api/whatsapp-numbers/[id]):
Modo PIIEfeito
STORE_INDEFINITE (padrão)Todas as conversas retornadas (sujeitas aos filtros de data).
STORE_X_DAYSAs conversas continuam sendo retornadas dentro do intervalo de datas solicitado — a lista não é truncada. No entanto, os dados de mensagem, peer e preview mais antigos que a janela de retenção (now − piiRetentionDays) são ocultados (nulificados) nas linhas retornadas.
RELAY_ONLYAs conversas são retornadas (não uma lista vazia), mas o peer e o preview da última mensagem são ocultados (nulificados). A resposta inclui um campo notice: "PII_RELAY_ONLY" e total > 0.

​
Exemplo

curl "https://pilotstatus.com.br/v1/conversations?startDate=2026-06-01T00:00:00Z&page=1&pageSize=20" \
  -H "x-api-key: ps_your_key_here"

​
Campos do objeto de conversa

​
id
string
obrigatório
ID da conversa no Pilot Status.
​
type
string
obrigatório
"DIRECT", "GROUP" ou "NEWSLETTER".
​
from
string | null
Telefone do remetente em E.164 (com +) para indivíduos; null para grupos/newsletters e peers apenas-lid.
​
fromName
string | null
Nome de exibição do contato ou grupo, quando disponível (resolvido a partir da conversa).
​
lastMessageAt
string
obrigatório
ISO 8601 — timestamp da última atividade de mensagem.
​
unreadCount
integer
obrigatório
Número de mensagens recebidas ainda não lidas.
​
createdAt
string
obrigatório
ISO 8601 — quando a conversa foi criada pela primeira vez.

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