GET /v1/conversations — Listar Conversas

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

string

Datetime ISO 8601. Filtra conversas cuja última mensagem seja igual ou posterior a esta data.

string

Datetime ISO 8601. Filtra conversas cuja última mensagem seja igual ou anterior a esta 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, é retornado 400 INVALID_DATE_RANGE.

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:

Modo PII	Efeito
`STORE_INDEFINITE` (padrão)	Todas as conversas retornadas (sujeitas aos filtros de data).
`STORE_X_DAYS`	As 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_ONLY`	As 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"

{
  "conversations": [
    {
      "id": "conv_abc123",
      "from": "+5511999999999",
      "fromName": "John Doe",
      "type": "DIRECT",
      "lastMessageAt": "2026-06-27T10:15:00.000Z",
      "unreadCount": 2,
      "createdAt": "2026-06-01T09:00:00.000Z"
    },
    {
      "id": "conv_def456",
      "from": null,
      "fromName": "Team Chat",
      "type": "GROUP",
      "lastMessageAt": "2026-06-27T09:45:00.000Z",
      "unreadCount": 0,
      "createdAt": "2026-06-10T14:00:00.000Z"
    }
  ],
  "total": 45,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3
}

{
  "conversations": [
    {
      "id": "conv_abc123",
      "from": null,
      "fromName": null,
      "type": "DIRECT",
      "lastMessageAt": "2026-06-27T10:15:00.000Z",
      "unreadCount": 2,
      "createdAt": "2026-06-01T09:00:00.000Z"
    },
    {
      "id": "conv_def456",
      "from": null,
      "fromName": null,
      "type": "GROUP",
      "lastMessageAt": "2026-06-27T09:45:00.000Z",
      "unreadCount": 0,
      "createdAt": "2026-06-10T14:00:00.000Z"
    }
  ],
  "total": 45,
  "page": 1,
  "pageSize": 30,
  "totalPages": 2,
  "notice": "PII_RELAY_ONLY"
}

Campos do objeto de conversa

string

obrigatório

ID da conversa no Pilot Status.

string

obrigatório

"DIRECT", "GROUP" ou "NEWSLETTER".

string | null

Telefone do remetente em E.164 (com +) para indivíduos; null para grupos/newsletters e peers apenas-lid.

string | null

Nome de exibição do contato ou grupo, quando disponível (resolvido a partir da conversa).

string

obrigatório

ISO 8601 — timestamp da última atividade de mensagem.

integer

obrigatório

Número de mensagens recebidas ainda não lidas.

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).

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

GET /v1/conversations — Listar Conversas

Endpoint

Parâmetros de consulta

Efeito do modo PII

Exemplo

Campos do objeto de conversa

Erros comuns

​Endpoint

​Parâmetros de consulta

​Efeito do modo PII

​Exemplo

​Campos do objeto de conversa

​Erros comuns

Endpoint

Parâmetros de consulta

Efeito do modo PII

Exemplo

Campos do objeto de conversa

Erros comuns