# Phone numbers

Fonte: https://lunahia.com.br/en/docs/reference/phone-numbers

The connected numbers: connect, read state, quality and throughput, edit and disconnect.

Migrating a number that is already on another provider's API is a supported path, and it needs no new number and loses no existing one. A number already registered on another provider's Cloud API almost always has two step verification configured there, and Meta requires the existing PIN to register it again: there is no endpoint to read or to turn that PIN off, so it has to come from the end business. Give the PIN at POST /v1/numbers/{id}/pin, or ask the end business to turn two step verification off in its WhatsApp Manager. The other prerequisites are on its side too: it has to own the WhatsApp Business account and have the number released by the previous provider.

A number that today exists only in the WhatsApp Business App, the phone application, is the other case, and Meta calls it coexistence. It has never been through any API. The connection starts from the same Meta window, and the option only shows up once the end business account is enabled for it on Meta's side and the app on the device is version 2.24.17 or later.

Connected this way, the number keeps working in the phone application, and the earlier conversations on the device are imported into the platform: they show up in GET /v1/messages next to the new ones. The import has a deadline to finish, and what tells you where it stands is GET /v1/numbers/{id}, in the fields sincronizacaoDoHistorico and sincronizacaoPrazo. The same resource carries tetoDeVazaoPorSegundo, which is the fixed sending speed ceiling of a number in coexistence and does not go up over time. And what the business owner answers from the phone application arrives too, in the recipient's conversation.

### Read the business profile

`GET /v1/numbers/{id}/profile`

The profile the contact sees on WhatsApp: about text, address, description, email, websites, vertical and the picture. It does not work on a number in coexistence.

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "about": "Atendimento de segunda a sexta",
  "address": "YOUR_ADDRESS",
  "description": "YOUR_DESCRIPTION",
  "email": "ana@suaempresa.com.br",
  "websites": [
    "YOUR_WEBSITES"
  ],
  "vertical": "YOUR_VERTICAL",
  "profilePictureUrl": "YOUR_PROFILEPICTUREURL"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "not_available_in_coexistence",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### Change the business profile

`PATCH /v1/numbers/{id}/profile`

Changes the fields you send and leaves the others as they are. With displayName, it requests the display name change and answers 202: the name stays under review at Meta. It does not work on a number in coexistence.

Authentication: API key. Required scope: `numbers:write`

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `about` | `string` | no | O recado curto. Até 139 caracteres. · 1 to 139 characters |
| `address` | `string` | no | O endereço. Até 256 caracteres. · 1 to 256 characters |
| `description` | `string` | no | A descrição. Até 512 caracteres. · 1 to 512 characters |
| `email` | `string` | no | O e-mail de contato. Até 128 caracteres. · 1 to 128 characters |
| `websites` | `array<string (uri)>` | no | Até dois sites. A lista inteira substitui a que existe. · up to 2 items |
| `vertical` | `string` | no | O ramo de atividade, no vocabulário da Meta. · 1 to 64 characters |
| `displayName` | `string` | no | Pede à Meta a mudança do nome de exibição (o nome que o contato vê no topo da conversa). A resposta é 202: o pedido está em revisão e displayNameStatus passa a pending_review. A Meta aceita até 10 mudanças a cada 30 dias, e é ela quem julga o nome. O evento number.display_name_reviewed avisa o resultado. Um nome aprovado só passa a valer depois que o número é registrado de novo. · 1 to 512 characters |
| `profilePictureHandle` | `string` | no | O handle de uma foto que você subiu pelo envio resumível da Meta. O mesmo handle que POST /v1/template-assets devolve serve de foto do perfil, o que está a confirmar na doc da Meta. · 1 to 1024 characters |

#### Code examples

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_ID/profile" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "about": "YOUR_ABOUT",
  "address": "YOUR_ADDRESS",
  "description": "YOUR_DESCRIPTION"
}'
```

#### Responses

**200**: Success.

```json
{
  "updatedFields": [
    "YOUR_UPDATEDFIELDS"
  ]
}
```

**202**: Accepted: the request was recorded and will be processed.

```json
{
  "updatedFields": [
    "YOUR_UPDATEDFIELDS"
  ],
  "displayNameStatus": "pending_review",
  "pendingDisplayName": "YOUR_PENDINGDISPLAYNAME"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "not_available_in_coexistence",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### List blocked users

`GET /v1/numbers/{id}/blocked-users`

Who this number has blocked, in pages. The cursor is Meta's, and its shape does not change.

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | Quantos por página, de 1 a 100. |
| `cursor` | `string` | no | O nextCursor da página anterior. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "waId": "YOUR_WAID",
      "userId": "YOUR_USERID"
    }
  ],
  "nextCursor": "YOUR_NEXTCURSOR"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### Block users

`POST /v1/numbers/{id}/blocked-users`

Blocks people who wrote to the number in the last 24 hours. Each user is a phone number or a BSUID, and the response separates the ones Meta accepted from the ones it refused, with the reason.

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `users` | `array<string>` | yes | Os usuários a bloquear, de um a cinquenta. · 1 to 50 items |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/blocked-users" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "users": [
    "YOUR_USERS"
  ]
}'
```

#### Responses

**200**: Success.

```json
{
  "done": [
    {
      "input": "YOUR_INPUT",
      "waId": "YOUR_WAID",
      "userId": "YOUR_USERID",
      "reasons": [
        "YOUR_REASONS"
      ]
    }
  ],
  "failed": [
    {
      "input": "YOUR_INPUT",
      "waId": "YOUR_WAID",
      "userId": "YOUR_USERID",
      "reasons": [
        "YOUR_REASONS"
      ]
    }
  ]
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### Unblock a user

`DELETE /v1/numbers/{id}/blocked-users/{user}`

Unblocks a user, by the phone number or the BSUID in the path. It stays open on a suspended account: unblocking is never the problem.

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |
| `user` | `string` | yes | O telefone (só dígitos) ou o BSUID do usuário. |

#### Code examples

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_ID/blocked-users/YOUR_USER" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**200**: Success.

```json
{
  "done": [
    {
      "input": "YOUR_INPUT",
      "waId": "YOUR_WAID",
      "userId": "YOUR_USERID",
      "reasons": [
        "YOUR_REASONS"
      ]
    }
  ],
  "failed": [
    {
      "input": "YOUR_INPUT",
      "waId": "YOUR_WAID",
      "userId": "YOUR_USERID",
      "reasons": [
        "YOUR_REASONS"
      ]
    }
  ]
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### List the QR codes

`GET /v1/numbers/{id}/qr-codes`

The codes that exist on this number, with each one's short link.

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "code": "4O4YGZEG3RIVE1",
      "prefilledMessage": "YOUR_PREFILLEDMESSAGE",
      "link": "https://exemplo.com.br/arquivo",
      "imageUrl": "YOUR_IMAGEURL"
    }
  ]
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### Create a QR code and a short link

`POST /v1/numbers/{id}/qr-codes`

Creates a code that opens a conversation with the number, with the message already written. It returns the code, the short link and, if you asked for it, the address of the image.

Authentication: API key. Required scope: `numbers:write`

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `prefilledMessage` | `string` | yes | A mensagem que já vem escrita. Até 140 caracteres, o limite da Meta, que está a confirmar na doc dela. · 1 to 140 characters |
| `imageFormat` | `string` | no | Peça a imagem do QR em PNG ou SVG. Sem isto, só o código e o link voltam. · Values: PNG, SVG |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/qr-codes" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefilledMessage": "YOUR_PREFILLEDMESSAGE"
}'
```

#### Responses

**201**: Created.

```json
{
  "code": "4O4YGZEG3RIVE1",
  "prefilledMessage": "YOUR_PREFILLEDMESSAGE",
  "link": "https://exemplo.com.br/arquivo",
  "imageUrl": "YOUR_IMAGEURL"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### Delete a QR code

`DELETE /v1/numbers/{id}/qr-codes/{code}`

Deletes the code and the short link: whoever still has the QR printed stops opening the conversation. It stays open on a suspended account.

Authentication: API key. Required scope: `numbers:write`

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |
| `code` | `string` | yes | O código do QR, como a criação o devolveu. |

#### Code examples

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_ID/qr-codes/YOUR_CODE" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**204**: No content: the operation was done and the response has no body.

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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

### Open a connection session

`POST /v1/onboarding/sessions`

Creates the session that Meta's connection flow fills in, and returns the sessionId and the csrfState.

Authentication: API key. Required scope: `onboarding:write`

Topic guide: https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-sessions

#### Code examples

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

#### Responses

**201**: Created.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "configId": "YOUR_CONFIGID",
  "sdkVersion": "YOUR_SDKVERSION",
  "csrfState": "YOUR_CSRFSTATE",
  "expiresAt": "YOUR_EXPIRESAT"
}
```

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

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_capacity_reached",
  "message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
  "capacity": 20,
  "activeNumbers": 20
}
```

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

### Read a connection session

`GET /v1/onboarding/sessions/{id}`

The session's current state and the matching guidance text, ready to display.

Authentication: API key. Required scope: `onboarding:write`

Topic guide: https://lunahia.com.br/en/docs/connect-a-number#rota-get-v1-onboarding-sessions-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "terminal": true,
  "proximoPasso": "YOUR_PROXIMOPASSO",
  "attemptCount": 1,
  "nextAttemptAt": "YOUR_NEXTATTEMPTAT",
  "retryNotBefore": "YOUR_RETRYNOTBEFORE",
  "expiresAt": "YOUR_EXPIRESAT",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

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

### Report an abandoned or failed flow

`POST /v1/onboarding/sessions/{id}/abandon`

Telemetry about what happened in Meta's window when the flow did not complete: which screen the customer stopped on, or which error Meta reported.

Authentication: API key. Required scope: `onboarding:write`

Topic guide: https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-sessions-id-abandon

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrfState` | `string` | yes |  |
| `currentStep` | `string \| null` | no | 1 to 120 characters |
| `errorCode` | `integer \| null` | no |  |
| `errorMessage` | `string \| null` | no |  |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_ID/abandon" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "csrfState": "YOUR_CSRFSTATE"
}'
```

#### Responses

**200**: Success.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "abandonedAtStep": "YOUR_ABANDONEDATSTEP"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

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

### Complete the connection

`POST /v1/onboarding/sessions/{id}/complete`

Exchanges the embedded flow's code for permanent access to the customer's account, and drives the session to the end: sealed token, app subscribed to the account, phone number registered.

Authentication: API key. Required scope: `onboarding:write`

Topic guide: https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-sessions-id-complete

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | yes |  |
| `csrfState` | `string` | yes |  |
| `wabaId` | `string \| null` | no |  |
| `phoneNumberId` | `string \| null` | no |  |
| `businessId` | `string \| null` | no |  |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_ID/complete" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "YOUR_CODE",
  "csrfState": "YOUR_CSRFSTATE"
}'
```

#### Responses

**200**: Success.

```json
{
  "sessionId": "77012a00-f049-4523-a658-3a3a4b105de6",
  "state": "APP_SUBSCRIBED",
  "orientacao": "O número está registrado na Meta e pronto para trocar mensagem.",
  "terminal": true,
  "proximoPasso": null,
  "motivo": null,
  "podeRetentar": false,
  "wabaId": "2000000000000001",
  "phoneNumberId": "1000000000000001"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

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

### List connected phone numbers

`GET /v1/numbers`

Every WhatsApp number connected to this customer, with state, quality, sending speed and daily conversation limit. Filters: externalId (exact match), q (prefix search over externalId, label and displayNumber), state, wabaId, qualityRating, connectionStatus, ready and canSend. A parameter the route does not know answers 400.

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

Topic guide: https://lunahia.com.br/en/docs/plan-and-numbers#rota-get-v1-numbers

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | `string` | no | O rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia. |
| `state` | `string` | no | O estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED. |
| `q` | `string` | no | Busca por prefixo, sem diferenciar maiúscula, em externalId, label e displayNumber. Quem digita só o número de telefone acha o número mesmo sem os espaços e o hífen. |
| `wabaId` | `string` | no | O id da conta de negócio na Meta (waba.id): só os números dela. Igualdade exata; uma conta sem número seu devolve lista vazia. |
| `qualityRating` | `string` | no | A qualidade que a Meta informou para o número (qualityRating): GREEN, YELLOW, RED, NA ou UNKNOWN. Número cuja qualidade a Luna ainda não leu (qualityRating nulo) não entra em nenhum valor. |
| `connectionStatus` | `string` | no | Só os números com este connection.status: connected, connecting, action_required ou disconnected. |
| `ready` | `string` | no | true: só os números prontos para enviar e receber. false: só os que ainda não estão. |
| `canSend` | `string` | no | true: só os números por onde enviar funciona agora (connection.canSend). false: só os que não. |
| `limit` | `integer` | no | Quantos números por página: de 1 a 100, 50 se omitido. |
| `cursor` | `string` | no | O nextCursor da resposta anterior. Opaco: carrega posição, não contagem. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "metaPhoneNumberId": "YOUR_METAPHONENUMBERID",
      "displayNumber": "YOUR_DISPLAYNUMBER",
      "state": "YOUR_STATE",
      "retryNotBefore": "YOUR_RETRYNOTBEFORE",
      "podeRetentar": true,
      "qualityRating": "YOUR_QUALITYRATING",
      "throughputLevel": "YOUR_THROUGHPUTLEVEL",
      "limiteDiarioDeConversas": "YOUR_LIMITEDIARIODECONVERSAS",
      "codeVerificationStatus": "YOUR_CODEVERIFICATIONSTATUS",
      "displayName": "YOUR_DISPLAYNAME",
      "displayNameStatus": "YOUR_DISPLAYNAMESTATUS",
      "pendingDisplayName": "YOUR_PENDINGDISPLAYNAME",
      "autoRead": true,
      "externalId": "YOUR_EXTERNALID",
      "label": "YOUR_LABEL",
      "orientacao": "YOUR_ORIENTACAO",
      "awaitingPaymentSince": "YOUR_AWAITINGPAYMENTSINCE",
      "waba": {
        "id": "YOUR_ID",
        "restricted": true,
        "disabled": true,
        "credentialExpiresAt": "YOUR_CREDENTIALEXPIRESAT",
        "credentialNeverExpires": true,
        "paymentMethodOnMeta": true,
        "currency": "YOUR_CURRENCY"
      },
      "ready": true,
      "connection": {
        "status": "connected",
        "canSend": true,
        "reasons": [
          {
            "code": "YOUR_CODE",
            "message": "YOUR_MESSAGE",
            "solution": "YOUR_SOLUTION",
            "action": "send_pin",
            "actionUrl": null,
            "docsUrl": null,
            "since": null
          }
        ]
      },
      "allowedActions": [
        "disconnect"
      ],
      "blockedActions": [
        {
          "action": "disconnect",
          "message": "YOUR_MESSAGE"
        }
      ],
      "createdAt": "YOUR_CREATEDAT",
      "updatedAt": "YOUR_UPDATEDAT"
    }
  ],
  "nextCursor": "YOUR_NEXTCURSOR"
}
```

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

### Read one phone number

`GET /v1/numbers/{id}`

One number, with everything the listing carries plus the health of its connection to Meta.

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

Topic guide: https://lunahia.com.br/en/docs/plan-and-numbers#rota-get-v1-numbers-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
  "metaPhoneNumberId": "1000000000000001",
  "displayNumber": "+55 11 90000-0000",
  "state": "REGISTERED",
  "retryNotBefore": null,
  "podeRetentar": false,
  "qualityRating": "GREEN",
  "throughputLevel": "STANDARD",
  "limiteDiarioDeConversas": "TIER_10K",
  "codeVerificationStatus": "VERIFIED",
  "displayName": "Clínica Sorriso",
  "displayNameStatus": "approved",
  "pendingDisplayName": null,
  "autoRead": false,
  "externalId": "cliente-8841",
  "label": "Atendimento Pinheiros",
  "orientacao": "Número conectado e operando. Mensagens já entram e saem por ele.",
  "awaitingPaymentSince": null,
  "waba": {
    "id": "102290129340398",
    "restricted": false,
    "disabled": false,
    "credentialExpiresAt": null,
    "credentialNeverExpires": true,
    "paymentMethodOnMeta": true,
    "currency": "BRL"
  },
  "ready": true,
  "connection": {
    "status": "connected",
    "canSend": true,
    "reasons": [],
    "steps": [
      {
        "key": "authorized",
        "label": "Autorização do negócio",
        "status": "done"
      },
      {
        "key": "receiving",
        "label": "Recebimento das mensagens",
        "status": "done"
      },
      {
        "key": "registered",
        "label": "Número registrado",
        "status": "done"
      },
      {
        "key": "ready",
        "label": "Pronto para usar",
        "status": "done"
      }
    ]
  },
  "allowedActions": [
    "disconnect",
    "edit_label"
  ],
  "blockedActions": [],
  "createdAt": "2026-08-07T11:28:14.597Z",
  "updatedAt": "2026-08-07T11:28:28.703Z",
  "tetoDeVazaoPorSegundo": null,
  "sincronizacaoDoHistorico": null,
  "sincronizacaoPrazo": null,
  "sincronizacaoProgresso": null,
  "subscriptionConfirmedAt": "2026-08-07T11:27:47.141Z",
  "credentialStatus": "active",
  "podeReconectar": false,
  "coexistence": false
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

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

### Edit a number

`PATCH /v1/numbers/{id}`

Changes a number's externalId and label, and turns autoRead (mark every received message as read on its own) on or off. It is how you reuse a number for another customer of yours, or name a number that was connected through the console, without a link.

Authentication: API key. Required scope: `numbers:write`

Topic guide: https://lunahia.com.br/en/docs/plan-and-numbers#rota-patch-v1-numbers-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | `string \| null` | no | O seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa. · 1 to 128 characters |
| `label` | `string \| null` | no | Um nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa. · 1 to 128 characters |
| `autoRead` | `boolean` | no | true: a Luna marca como lida, na Meta, cada mensagem que o número receber daqui em diante, sem indicador de digitando. false desliga. Ausente não muda. O padrão de um número é false. |

#### Code examples

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "YOUR_EXTERNALID",
  "label": "YOUR_LABEL",
  "autoRead": true
}'
```

#### Responses

**200**: Success.

```json
{
  "id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
  "metaPhoneNumberId": "1000000000000001",
  "displayNumber": "+55 11 90000-0000",
  "state": "REGISTERED",
  "retryNotBefore": null,
  "podeRetentar": false,
  "qualityRating": "GREEN",
  "throughputLevel": "STANDARD",
  "limiteDiarioDeConversas": "TIER_10K",
  "codeVerificationStatus": "VERIFIED",
  "displayName": "Clínica Sorriso",
  "displayNameStatus": "approved",
  "pendingDisplayName": null,
  "autoRead": false,
  "externalId": "cliente-8841",
  "label": "Atendimento Pinheiros",
  "orientacao": "Número conectado e operando. Mensagens já entram e saem por ele.",
  "awaitingPaymentSince": null,
  "waba": {
    "id": "102290129340398",
    "restricted": false,
    "disabled": false,
    "credentialExpiresAt": null,
    "credentialNeverExpires": true,
    "paymentMethodOnMeta": true,
    "currency": "BRL"
  },
  "ready": true,
  "connection": {
    "status": "connected",
    "canSend": true,
    "reasons": [],
    "steps": [
      {
        "key": "authorized",
        "label": "Autorização do negócio",
        "status": "done"
      },
      {
        "key": "receiving",
        "label": "Recebimento das mensagens",
        "status": "done"
      },
      {
        "key": "registered",
        "label": "Número registrado",
        "status": "done"
      },
      {
        "key": "ready",
        "label": "Pronto para usar",
        "status": "done"
      }
    ]
  },
  "allowedActions": [
    "disconnect",
    "edit_label"
  ],
  "blockedActions": [],
  "createdAt": "2026-08-07T11:28:14.597Z",
  "updatedAt": "2026-08-07T11:28:28.703Z",
  "tetoDeVazaoPorSegundo": null,
  "sincronizacaoDoHistorico": null,
  "sincronizacaoPrazo": null,
  "sincronizacaoProgresso": null,
  "subscriptionConfirmedAt": "2026-08-07T11:27:47.141Z",
  "credentialStatus": "active",
  "podeReconectar": false,
  "coexistence": false
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

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

### Disconnect a number

`DELETE /v1/numbers/{id}`

Takes the number off Luna. It is how you open a slot in the plan capacity: the number stops counting from this instant, and your customer can be swapped for another.

Authentication: API key. Required scope: `numbers:write`

Topic guide: https://lunahia.com.br/en/docs/plan-and-numbers#rota-delete-v1-numbers-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Code examples

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

#### Responses

**204**: No content: the operation was done and the response has no body.

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

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

### Give a number's two step verification PIN

`POST /v1/numbers/{id}/pin`

Gives the two step verification PIN of a number that is already registered on another provider's Cloud API, so Luna can register it without the end business having to turn verification off.

Authentication: API key. Required scope: `onboarding:write`

Topic guide: https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-numbers-id-pin

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pin` | `string` | yes | O PIN de verificação em duas etapas deste número, com exatamente seis dígitos. Quando o número já tem verificação em duas etapas configurada em outro provedor, é o PIN existente dele, e apenas o negócio final o conhece: não existe endpoint para ler nem para desligar o PIN de um número. Quando o número não tem verificação em duas etapas, este valor passa a ser o PIN dele. · /^\d{6}$/ |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/pin" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pin": "YOUR_PIN"
}'
```

#### Responses

**200**: Success.

```json
{
  "id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
  "state": "PENDING"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "pin_not_applicable",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número não está aguardando o PIN de verificação em duas etapas. O campo state diz em que ponto ele está."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

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

### Reconnect a number whose authorisation died

`POST /v1/onboarding/reconnect`

Opens a connection session for a number that already exists, when the authorisation granted by the customer expired or was revoked.

Authentication: API key. Required scope: `onboarding:write`

Topic guide: https://lunahia.com.br/en/docs/connect-a-number#rota-post-v1-onboarding-reconnect

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `numberId` | `string` | yes | O número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/reconnect" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "numberId": "YOUR_NUMBERID"
}'
```

#### Responses

**201**: Created.

```json
{
  "sessionId": "77012a00-f049-4523-a658-3a3a4b105de6",
  "state": "STARTED",
  "configId": "1234567890",
  "sdkVersion": "v26.0",
  "csrfState": "Xk3s...",
  "expiresAt": "2026-08-26T18:30:00.000Z"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "reconnect_not_applicable",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "A autorização deste número não admite reconexão.",
  "credentialStatus": "active"
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

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

### List business accounts

`GET /v1/business-accounts`

The WhatsApp Business accounts this customer has connected, newest first, each with its name at Meta, its WhatsApp Manager address and its numbers.

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

Topic guide: https://lunahia.com.br/en/docs/connect-a-number#rota-get-v1-business-accounts

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
      "wabaId": "102290129340398",
      "numbers": [
        "+55 11 90000-0000"
      ],
      "name": "Padaria do Zé",
      "managerUrl": "https://business.facebook.com/latest/whatsapp_manager/overview?asset_id=102290129340398",
      "phoneNumbers": [
        {
          "id": "a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d",
          "displayNumber": "+55 11 90000-0000",
          "externalId": "cliente-8841",
          "label": "Atendimento Pinheiros"
        }
      ],
      "status": {
        "restricted": false,
        "restrictions": [],
        "disabled": false,
        "violationType": null,
        "reportedAt": null
      },
      "credentialExpiresAt": null,
      "credentialNeverExpires": true,
      "paymentMethodOnMeta": true,
      "currency": "BRL",
      "createdAt": "2026-08-07T11:27:41.208Z"
    }
  ]
}
```

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

### Check the account payment method at Meta now

`POST /v1/business-accounts/{id}/payment-method/check`

Reads from Meta whether the account has a payment method on file, without waiting for the hourly read, and returns the result. The webhook notice follows the usual path: number.action_required (reason payment_method_missing) when it is missing and number.action_resolved when it shows up. A read newer than 60 seconds is returned without calling Meta, and the call respects the account call budget.

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O id da conta de negócio na Luna, o mesmo que GET /v1/business-accounts devolve em id. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/business-accounts/YOUR_ID/payment-method/check" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**200**: Success.

```json
{
  "id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
  "wabaId": "102290129340398",
  "paymentMethodOnMeta": false,
  "currency": "BRL",
  "checkedAt": "2026-11-05T14:02:11.000Z",
  "refreshed": true,
  "reason": "checked"
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

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

### Read the health of a phone number

`GET /v1/numbers/{id}/health`

The quality rating, throughput level and daily conversation limit Meta assigns to this number right now, and the changes the platform has observed over time.

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

Topic guide: https://lunahia.com.br/en/docs/account-health#rota-get-v1-numbers-id-health

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "qualityRating": "GREEN",
  "throughputLevel": "HIGH",
  "tetoDeVazaoPorSegundo": null,
  "sincronizacaoDoHistorico": "em_curso",
  "sincronizacaoPrazo": "2026-09-19T09:00:00.000Z",
  "sincronizacaoProgresso": 40,
  "limiteDiarioDeConversas": "TIER_10K",
  "codeVerificationStatus": "VERIFIED",
  "checkedAt": "2026-08-26T12:00:00.000Z",
  "transitions": [
    {
      "qualityRating": "GREEN",
      "throughputLevel": "HIGH",
      "limiteDiarioDeConversas": "TIER_2K",
      "codeVerificationStatus": "VERIFIED",
      "observedAt": "2026-08-24T10:00:00.000Z"
    }
  ]
}
```

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

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

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

### Read the Meta usage of a number or a customer

`GET /v1/usage`

The usage Meta measures for a number (numberId) or for all the numbers of one of your customers (externalId), passed through as Meta reports it, with each account's currency and no sums. format=csv returns text/csv. Luna only reads and shows it: none of it goes into the Luna subscription.

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

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `numberId` | `string` | no | O número a consultar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. Mande este ou externalId, nunca os dois. |
| `externalId` | `string` | no | O rótulo do seu cliente (o externalId do link de conexão): lê o consumo de todos os números dele, cada um na moeda da conta dele. Mande este ou numberId, nunca os dois. |
| `start` | `any` | no | O começo do período, em ISO 8601 (data ou data e hora, em UTC). Ausente, o primeiro dia do mês corrente. |
| `end` | `any` | no | O fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos). |
| `granularity` | `string` | no | O tamanho de cada ponto, no vocabulário da Meta: HALF_HOUR, DAILY (o padrão) ou MONTHLY. A Meta limita o período de cada um, e recusa o que passa do limite dela. |
| `format` | `string` | no | json (o padrão) ou csv. O csv vem em text/csv, uma linha por ponto, com numberId, phoneNumberId e currency em cada linha, para planilha. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "numberId": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
  "phoneNumberId": "123456789012345",
  "externalId": null,
  "start": "2026-11-01T00:00:00.000Z",
  "end": "2026-11-03T15:00:00.000Z",
  "granularity": "DAILY",
  "readAt": "2026-11-03T15:00:12.000Z",
  "notice": "Valores aproximados, como a Meta os informa, na moeda da conta do negócio na Meta. A Meta cobra o uso do WhatsApp direto do negócio dono do número, e a fatura dela é a referência: este consumo pode divergir dela. A Luna só repassa a leitura, e nada daqui entra na assinatura da Luna.",
  "numbers": [
    {
      "numberId": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
      "phoneNumberId": "123456789012345",
      "currency": "BRL",
      "read": true,
      "reason": null
    }
  ],
  "data": [
    {
      "numberId": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
      "phoneNumberId": "123456789012345",
      "currency": "BRL",
      "start": "2026-11-02T03:00:00.000Z",
      "end": "2026-11-03T03:00:00.000Z",
      "pricingCategory": "UTILITY",
      "pricingType": "REGULAR",
      "tier": null,
      "country": "BR",
      "volume": 12,
      "cost": 0.5
    }
  ]
}
```

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

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "error": "number_disconnected",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}
```

**422**: The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.

```json
{
  "error": "meta_rejected",
  "docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
  "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
  "meta": {
    "codigo": 131030,
    "categoria": "nao_entregavel",
    "mensagem": "A Meta recusou o pedido.",
    "acaoRecomendada": "Confira os campos enviados e tente de novo.",
    "original": {
      "error": {
        "message": "Invalid parameter",
        "type": "OAuthException",
        "code": 131030,
        "fbtrace_id": "AbCdEfGhIjK"
      }
    }
  }
}
```

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