# Conversations

Fonte: https://lunahia.com.br/en/docs/reference/conversations

One row per contact per number, with the state of the 24 hour customer service window.

### List conversations

`GET /v1/conversations`

One row per correspondent per number, from the most active to the most idle.

Authentication: API key. Required scope: `messages:read`

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-get-v1-conversations

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no |  |
| `phoneNumberId` | `string` | no | O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. |
| `externalId` | `string` | no | 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` | no | 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` | no | 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` | no |  |

#### Code examples

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

#### Responses

**200**: Success.

```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**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```
