# Conversas

Fonte: https://lunahia.com.br/docs/referencia/conversas

Uma linha por interlocutor por número, com o estado da janela de atendimento de 24 horas.

### Listar conversas

`GET /v1/conversations`

Uma linha por interlocutor por número, da mais ativa para a mais parada.

Autenticação: Chave de API. Escopo exigido: `messages:read`

Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-get-v1-conversations

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `limit` | `integer` | não |  |
| `phoneNumberId` | `string` | não | O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. |
| `externalId` | `string` | não | O rótulo que você deu ao seu cliente (externalId): só as conversas dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia. |
| `waId` | `string` | não | O identificador do interlocutor no WhatsApp (o waId da conversa, em geral o telefone só com dígitos): só as conversas dele, em cada número. Igualdade exata, mas o celular brasileiro vale nas duas grafias, com e sem o 9 depois do DDD (a Meta entrega alguns sem ele); um waId sem conversa devolve lista vazia. |
| `userId` | `string` | não | O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só a conversa dele, em cada número. Igualdade exata; um userId sem conversa devolve lista vazia. |
| `cursor` | `string` | não |  |

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/conversations" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```json
{
  "data": [
    {
      "id": "0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12",
      "waId": "5511900000000",
      "userId": "BR.13491208655302741918",
      "parentUserId": null,
      "username": null,
      "phoneNumberId": "7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11",
      "numberId": "7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11",
      "externalId": "cliente-8841",
      "contactName": "Maria Souza",
      "displayNumber": "+55 11 90000-0000",
      "createdAt": "2026-08-07T11:35:10.000Z",
      "lastMessage": {
        "direction": "outbound",
        "type": "text",
        "bodyText": "Olá! Recebemos seu pedido e já estamos preparando.",
        "createdAt": "2026-08-07T12:24:02.085Z"
      },
      "windowOpen": true,
      "windowExpiresAt": "2026-08-08T11:35:10.000Z",
      "windowSource": "usuario"
    }
  ],
  "nextCursor": null
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```
