> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/conversations — Listar Conversas

> Liste as conversas do número conectado, ordenadas pela atividade de mensagem mais recente.

Liste as conversas do número conectado, ordenadas pela atividade de mensagem mais recente.

## Endpoint

`GET https://pilotstatus.com.br/v1/conversations`

<Note>
  Requer uma chave de API **com escopo de número** (`ps_*`) no cabeçalho `x-api-key`. Chaves com escopo de tenant retornam `403`.
</Note>

## Parâmetros de consulta

<ParamField query="startDate" type="string">
  Datetime ISO 8601. Filtra conversas cuja última mensagem seja **igual ou posterior** a esta data.
</ParamField>

<ParamField query="endDate" type="string">
  Datetime ISO 8601. Filtra conversas cuja última mensagem seja **igual ou anterior** a esta data.
</ParamField>

<ParamField query="page" default="1" type="integer">
  Número da página (≥ 1).
</ParamField>

<ParamField query="pageSize" default="30" type="integer">
  Resultados por página (1–100).
</ParamField>

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```json Response (200) theme={null}
  {
    "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
  }
  ```

  ```json RELAY_ONLY (200) theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

## Campos do objeto de conversa

<ResponseField name="id" type="string" required>
  ID da conversa no Pilot Status.
</ResponseField>

<ResponseField name="type" type="string" required>
  `"DIRECT"`, `"GROUP"` ou `"NEWSLETTER"`.
</ResponseField>

<ResponseField name="from" type="string | null">
  Telefone do remetente em E.164 (com `+`) para indivíduos; `null` para grupos/newsletters e peers apenas-lid.
</ResponseField>

<ResponseField name="fromName" type="string | null">
  Nome de exibição do contato ou grupo, quando disponível (resolvido a partir da conversa).
</ResponseField>

<ResponseField name="lastMessageAt" type="string" required>
  ISO 8601 — timestamp da última atividade de mensagem.
</ResponseField>

<ResponseField name="unreadCount" type="integer" required>
  Número de mensagens recebidas ainda não lidas.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 — quando a conversa foi criada pela primeira vez.
</ResponseField>

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