# API reference

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

## Messages

Send messages and read what came in and went out. Sending is asynchronous: the answer is 202 and delivery happens at the pace Meta allows.

### List messages

`GET /v1/messages`

The record of what came in and what went out, newest first. Each message carries the number, the customer label, the conversation and, when it failed, the error summary. Filters: phoneNumberId, externalId, conversationId, waId, userId, wamid, direction, status, since and until. A parameter the route does not know answers 400. format=csv answers text/csv, with the same filters.

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

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

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | Quantas mensagens trazer. Padrão 50, máximo 100. Com format=csv o padrão e o máximo são 1000. Mais que 100 sem format=csv responde 400. |
| `format` | `string` | no | json (o padrão) ou csv. O csv vem em text/csv, uma linha por mensagem, com os mesmos filtros e a mesma ordem; a próxima página vem no cabeçalho X-Luna-Next-Cursor (ausente na última) e vai em cursor. Colunas: id, direction, wamid, type, bodyText, status, waId, userId, displayNumber, numberId, externalId, conversationId, errorCode, errorMessage, createdAt. |
| `phoneNumberId` | `string` | no | O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. |
| `externalId` | `string` | no | O rótulo que você deu ao seu cliente (externalId): só as mensagens dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia. |
| `conversationId` | `string` | no |  |
| `waId` | `string` | no | O telefone do interlocutor (waId), só com dígitos: só as mensagens da conversa dele. Igualdade exata, e o celular do Brasil vale com e sem o nono dígito; um waId sem conversa devolve lista vazia. |
| `userId` | `string` | no | O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só as mensagens da conversa dele. Igualdade exata; um userId sem conversa devolve lista vazia. |
| `direction` | `string` | no | inbound: só o que chegou. outbound: só o que você enviou. |
| `status` | `string` | no | O status da mensagem, como a Meta o informa e como o campo status o devolve (por exemplo sent, delivered, read, failed). Igualdade exata, e um valor que nenhuma mensagem tem devolve lista vazia. Vale só para mensagem enviada, que é a que tem status. |
| `since` | `any` | no | Só as mensagens criadas neste instante ou depois (ISO 8601: 2026-11-03T00:00:00.000Z, 2026-11-03T00:00:00-03:00, ou a data 2026-11-03, que vale meia-noite UTC). |
| `until` | `any` | no | Só as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until). |
| `wamid` | `string` | no | O identificador da mensagem na Meta, o mesmo que os eventos de webhook trazem em wamid. Devolve só a mensagem com esse wamid, e a lista vem vazia quando ele não é seu ou não existe. |
| `cursor` | `string` | no |  |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "id": "ae60f288-7565-4315-a440-3663e9c231e1",
      "direction": "outbound",
      "wamid": "wamid.HBgMNTUzMTgwMzYwMjEwFQIAERgSQjczNEE1OEVDMDgyMTJCMjA2AA==",
      "type": "text",
      "bodyText": "Olá! Recebemos seu pedido e já estamos preparando.",
      "content": null,
      "callbackData": "atendimento-8841",
      "status": "read",
      "pricing": {
        "billable": true,
        "pricing_model": "PMP",
        "type": "regular",
        "category": "utility"
      },
      "waId": "5511900000000",
      "userId": "BR.13491208655302741918",
      "parentUserId": null,
      "username": null,
      "displayNumber": "+55 11 90000-0000",
      "numberId": "a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d",
      "externalId": "cliente-8841",
      "conversationId": "2d9f6a41-0c5b-4e7a-8f13-9b6c4d2e1a07",
      "errorSummary": null,
      "createdAt": "2026-08-07T12:24:02.085Z"
    },
    {
      "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51",
      "direction": "inbound",
      "wamid": "wamid.HBgMNTUzMTgwMzYwMjEwFQIAEhgUM0FCMEFBNDUzNzg4NzY5MUQ5MTUA",
      "type": "text",
      "bodyText": "oi",
      "content": null,
      "callbackData": null,
      "status": null,
      "pricing": null,
      "waId": "5511900000000",
      "userId": "BR.13491208655302741918",
      "parentUserId": null,
      "username": null,
      "displayNumber": "+55 11 90000-0000",
      "numberId": "a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d",
      "externalId": "cliente-8841",
      "conversationId": "2d9f6a41-0c5b-4e7a-8f13-9b6c4d2e1a07",
      "errorSummary": null,
      "createdAt": "2026-08-07T11:35:10.000Z"
    }
  ],
  "nextCursor": null
}
```

**400**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

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

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.

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

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

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

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

### Send a text message

`POST /v1/messages`

Accepts the message, returns 202 with its identifier, and delivers it to Meta asynchronously. With a test key, the message does NOT go to Meta: Luna returns the 202 and delivers the simulated states sent, delivered and read to your webhook, with test: true. The optional Idempotency-Key header (1 to 255 visible characters, no space) makes repeating the request return the original message; empty or malformed answers 400.

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

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

#### Request body

`application/json`

Shape 1: `type = "text"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | no | Sempre text. Pode ser omitido: um corpo sem type é interpretado como texto, para não quebrar quem integrou antes dos demais tipos existirem. · default: "text" · Values: text |
| `text` | `object` | yes |  |
| `text.body` | `string` | yes | O texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API. · 1 to 4096 characters |
| `text.preview_url` | `boolean` | no | Se a Meta deve buscar a primeira URL do texto para montar uma prévia. Desligado por padrão: ligado, ele dispara uma requisição de saída a partir de conteúdo que o negócio final escreveu, com latência e comportamento que não são da plataforma. |

Shape 2: `type = "image"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre image. · Values: image |
| `image` | `object` | yes |  |
| `image.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `image.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `image.caption` | `string` | no | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · up to 1024 characters |

Shape 3: `type = "video"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre video. · Values: video |
| `video` | `object` | yes |  |
| `video.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `video.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `video.caption` | `string` | no | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · up to 1024 characters |

Shape 4: `type = "audio"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre audio. · Values: audio |
| `audio` | `object` | yes |  |
| `audio.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `audio.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `audio.voice` | `boolean` | no | true para enviar como mensagem de voz (a bolinha de áudio do WhatsApp, com a forma de onda), e não como arquivo de áudio. A Meta exige um arquivo .ogg com codec OPUS, e a Luna não converte áudio: com link, um arquivo de outro tipo reconhecido (por exemplo .mp3) é recusado com 400. Com id, a Luna não vê o tipo do arquivo, e a conferência é da Meta. |

Shape 5: `type = "document"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre document. · Values: document |
| `document` | `object` | yes |  |
| `document.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `document.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `document.caption` | `string` | no | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · up to 1024 characters |
| `document.filename` | `string` | no | O nome com que o arquivo aparece para quem recebe. Sem ele, quem recebe vê o nome que a Meta derivar da origem. · 1 to 240 characters |

Shape 6: `type = "sticker"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre sticker. · Values: sticker |
| `sticker` | `object` | yes |  |
| `sticker.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `sticker.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |

Shape 7: `type = "location"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre location. · Values: location |
| `location` | `object` | yes |  |
| `location.latitude` | `number` | yes | A latitude em graus decimais, entre -90 e 90. · minimum -90 · maximum 90 |
| `location.longitude` | `number` | yes | A longitude em graus decimais, entre -180 e 180. · minimum -180 · maximum 180 |
| `location.name` | `string` | no | O nome do lugar, exibido acima do endereço. · up to 1000 characters |
| `location.address` | `string` | no | O endereço do lugar, exibido abaixo do nome. · up to 1000 characters |

Shape 8: `type = "contacts"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre contacts. · Values: contacts |
| `contacts` | `array<object>` | yes | Os cartões de contato a enviar. Ao menos um, no máximo vinte. · 1 to 20 items |
| `contacts[].name` | `object` | yes |  |
| `contacts[].name.formatted_name` | `string` | yes | O nome como ele aparece no cartão. · 1 to 512 characters |
| `contacts[].name.first_name` | `string` | no | O primeiro nome. · up to 256 characters |
| `contacts[].name.last_name` | `string` | no | O sobrenome. · up to 256 characters |
| `contacts[].name.middle_name` | `string` | no | O nome do meio. · up to 256 characters |
| `contacts[].name.prefix` | `string` | no | O prefixo, como Dr. ou Sra. · up to 64 characters |
| `contacts[].name.suffix` | `string` | no | O sufixo, como Jr. ou Neto. · up to 64 characters |
| `contacts[].birthday` | `string` | no | A data de nascimento em AAAA-MM-DD. · /^\d{4}-\d{2}-\d{2}$/ |
| `contacts[].org` | `object` | no | Os dados profissionais do contato. |
| `contacts[].org.company` | `string` | no | A empresa. · up to 256 characters |
| `contacts[].org.department` | `string` | no | O departamento. · up to 256 characters |
| `contacts[].org.title` | `string` | no | O cargo. · up to 256 characters |
| `contacts[].phones` | `array<object>` | no | Os telefones do contato. · up to 20 items |
| `contacts[].phones[].phone` | `string` | no | O telefone, como ele deve aparecer. · up to 64 characters |
| `contacts[].phones[].type` | `string` | no | O rótulo do telefone, como CELL ou WORK. · up to 64 characters |
| `contacts[].phones[].wa_id` | `string` | no | O identificador do contato no WhatsApp, se conhecido. · up to 64 characters |
| `contacts[].emails` | `array<object>` | no | Os e-mails do contato. · up to 20 items |
| `contacts[].emails[].email` | `string` | no | O endereço de e-mail. · up to 320 characters |
| `contacts[].emails[].type` | `string` | no | O rótulo do e-mail, como HOME ou WORK. · up to 64 characters |
| `contacts[].addresses` | `array<object>` | no | Os endereços do contato. · up to 20 items |
| `contacts[].addresses[].street` | `string` | no | O logradouro e o número. · up to 512 characters |
| `contacts[].addresses[].city` | `string` | no | A cidade. · up to 256 characters |
| `contacts[].addresses[].state` | `string` | no | O estado. · up to 256 characters |
| `contacts[].addresses[].zip` | `string` | no | O CEP. · up to 64 characters |
| `contacts[].addresses[].country` | `string` | no | O país. · up to 256 characters |
| `contacts[].addresses[].country_code` | `string` | no | O código do país em duas letras. · up to 8 characters |
| `contacts[].addresses[].type` | `string` | no | O rótulo do endereço, como HOME ou WORK. · up to 64 characters |
| `contacts[].urls` | `array<object>` | no | As páginas do contato. · up to 20 items |
| `contacts[].urls[].url` | `string` | no | O endereço na web. · up to 2048 characters |
| `contacts[].urls[].type` | `string` | no | O rótulo da URL, como HOME ou WORK. · up to 64 characters |

Shape 9: `type = "reaction"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre reaction. · Values: reaction |
| `reaction` | `object` | yes |  |
| `reaction.message_id` | `string` | yes | A mensagem que recebe a reação: o wamid que a Meta atribuiu ou o id da Luna (UUID), que a Luna troca pelo wamid. O content da mensagem enviada mostra o wamid. · 1 to 256 characters |
| `reaction.emoji` | `string` | yes | O emoji da reação. Mande vazio para remover uma reação que já tinha sido posta. · up to 16 characters |

Shape 10: `type = "interactive"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre interactive. · Values: interactive |
| `interactive` | `object` | yes | A mensagem interativa: botões de resposta (button), lista de opções (list), botão com URL (cta_url), pedido de localização (location_request_message), pedido de endereço (address_message), carrossel de mídia (carousel), Flow (flow), um produto do catálogo (product) ou uma lista de produtos do catálogo (product_list). |
| `interactive.type` | `string` | no | Sempre button. · Values: button |
| `interactive.header` | `object` | no | O cabeçalho, exibido acima do corpo. |
| `interactive.header.type` | `string` | yes | O que o cabeçalho carrega. · Values: text, image, video, document |
| `interactive.header.text` | `string` | no | O texto do cabeçalho, quando type é text. · up to 60 characters |
| `interactive.header.image` | `object` | no | A imagem do cabeçalho, quando type é image. |
| `interactive.header.image.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `interactive.header.image.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `interactive.header.video` | `object` | no | O vídeo do cabeçalho, quando type é video. |
| `interactive.header.video.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `interactive.header.video.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `interactive.header.document` | `object` | no | O documento do cabeçalho, quando type é document. |
| `interactive.header.document.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `interactive.header.document.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `interactive.header.document.filename` | `string` | no | up to 240 characters |
| `interactive.body` | `object` | no | O corpo da mensagem interativa. |
| `interactive.body.text` | `string` | yes | O texto do corpo. · 1 to 1024 characters |
| `interactive.footer` | `object` | no | O rodapé, exibido abaixo dos botões. |
| `interactive.footer.text` | `string` | yes | O texto do rodapé. · up to 60 characters |
| `interactive.action` | `object` | no |  |
| `interactive.action.buttons` | `array<object>` | yes | Os botões de resposta. De um a três, o teto da Cloud API. · 1 to 3 items |
| `interactive.action.buttons[].type` | `string` | yes | Sempre reply. · Values: reply |
| `interactive.action.buttons[].reply` | `object` | yes |  |
| `interactive.action.buttons[].reply.id` | `string` | yes | O identificador que volta no webhook quando o botão é tocado. · 1 to 256 characters |
| `interactive.action.buttons[].reply.title` | `string` | yes | O rótulo do botão. Limite de 20 caracteres. · 1 to 20 characters |
| `interactive.action.button` | `string` | yes | O rótulo do botão que abre a lista. Limite de 20 caracteres. · 1 to 20 characters |
| `interactive.action.sections` | `array<object>` | yes | As seções da lista. De uma a dez, o teto da Cloud API. · 1 to 10 items |
| `interactive.action.sections[].title` | `string` | no | O título da seção. · up to 24 characters |
| `interactive.action.sections[].rows` | `array<object>` | yes | As linhas da seção. De uma a dez. · 1 to 10 items |
| `interactive.action.sections[].rows[].id` | `string` | yes | O identificador que volta no webhook quando a linha é escolhida. · 1 to 200 characters |
| `interactive.action.sections[].rows[].title` | `string` | yes | O título da linha. · 1 to 24 characters |
| `interactive.action.sections[].rows[].description` | `string` | no | A descrição da linha. · up to 72 characters |
| `interactive.action.name` | `string` | no | Sempre cta_url. · default: "cta_url" · Values: cta_url |
| `interactive.action.parameters` | `object` | yes |  |
| `interactive.action.parameters.display_text` | `string` | yes | O rótulo do botão. Limite de 20 caracteres. · 1 to 20 characters |
| `interactive.action.parameters.url` | `string (uri)` | yes | O endereço que o botão abre. · up to 2048 characters |
| `interactive.action.parameters.country` | `string` | no | O país do endereço, em duas letras (ISO 3166). O padrão é BR. · /^[A-Za-z]{2}$/ · default: "BR" |
| `interactive.action.parameters.values` | `object` | no | Os campos do endereço já preenchidos, com os nomes que a Meta define para o país. |
| `interactive.action.parameters.saved_addresses` | `array<object>` | no | Endereços salvos que o usuário pode escolher, no máximo vinte. · up to 20 items |
| `interactive.action.parameters.saved_addresses[].id` | `string` | yes | O identificador do endereço salvo. · 1 to 128 characters |
| `interactive.action.parameters.saved_addresses[].value` | `object` | yes | Os campos do endereço salvo. |
| `interactive.action.parameters.validation_errors` | `object` | no | Mensagens de erro por campo, para quando você devolve o formulário depois de uma validação. |
| `interactive.action.cards` | `array<object>` | yes | Os cartões, de dois a dez. · 2 to 10 items |
| `interactive.action.cards[].card_index` | `integer` | yes | A posição do cartão, de 0 a 9. Não repita. · minimum 0 · maximum 9 |
| `interactive.action.cards[].type` | `string` | no | Sempre cta_url. · default: "cta_url" · Values: cta_url |
| `interactive.action.cards[].header` | `object` | yes | A mídia do cartão. |
| `interactive.action.cards[].header.type` | `string` | yes | O que o cartão mostra. · Values: image, video |
| `interactive.action.cards[].header.image` | `object` | no | A imagem do cartão, quando type é image. |
| `interactive.action.cards[].header.image.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `interactive.action.cards[].header.image.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `interactive.action.cards[].header.video` | `object` | no | O vídeo do cartão, quando type é video. |
| `interactive.action.cards[].header.video.id` | `string` | no | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 to 128 characters |
| `interactive.action.cards[].header.video.link` | `string (uri)` | no | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · up to 2048 characters |
| `interactive.action.cards[].body` | `object` | no | O texto do cartão. |
| `interactive.action.cards[].body.text` | `string` | yes | O texto do cartão. Limite de 160 caracteres. · 1 to 160 characters |
| `interactive.action.cards[].action` | `object` | yes |  |
| `interactive.action.cards[].action.name` | `string` | no | Sempre cta_url. · default: "cta_url" · Values: cta_url |
| `interactive.action.cards[].action.parameters` | `object` | yes |  |
| `interactive.action.cards[].action.parameters.display_text` | `string` | yes | O rótulo do botão. Limite de 20 caracteres. · 1 to 20 characters |
| `interactive.action.cards[].action.parameters.url` | `string (uri)` | yes | O endereço que o botão abre. · up to 2048 characters |
| `interactive.action.parameters.flow_message_version` | `string` | no | A versão do formato da mensagem de Flow. O padrão é 3, a corrente na Meta. · 1 to 8 characters · default: "3" |
| `interactive.action.parameters.flow_id` | `string` | no | O identificador do Flow. Use este OU flow_name. · 1 to 64 characters |
| `interactive.action.parameters.flow_name` | `string` | no | O nome do Flow. Use este OU flow_id. · 1 to 200 characters |
| `interactive.action.parameters.flow_cta` | `string` | yes | O rótulo do botão que abre o Flow. A Meta limita o tamanho (o limite exato está a confirmar na doc da Meta). · 1 to 40 characters |
| `interactive.action.parameters.flow_token` | `string` | no | O que você quer receber de volta na resposta do Flow, para ligá-la a este envio. · up to 256 characters |
| `interactive.action.parameters.flow_action` | `string` | no | navigate (padrão da Meta) ou data_exchange. · 1 to 32 characters |
| `interactive.action.parameters.flow_action_payload` | `object` | no | A tela e os dados de abertura, quando flow_action é navigate. |
| `interactive.action.parameters.flow_action_payload.screen` | `string` | yes | A tela do Flow que abre primeiro. · 1 to 200 characters |
| `interactive.action.parameters.flow_action_payload.data` | `object` | no | Os dados que o Flow recebe nessa tela. |
| `interactive.action.parameters.mode` | `string` | no | draft para testar um Flow ainda não publicado, ou published (padrão da Meta). · 1 to 16 characters |
| `interactive.action.catalog_id` | `string` | yes | O identificador do catálogo na conta de negócio do número (catalog_id da Meta). · 1 to 64 characters |
| `interactive.action.product_retailer_id` | `string` | yes | O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta). · 1 to 256 characters |
| `interactive.action.sections[].product_items` | `array<object>` | yes | Os produtos da seção. · 1 to 30 items |
| `interactive.action.sections[].product_items[].product_retailer_id` | `string` | yes | O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta). · 1 to 256 characters |

Shape 11: `type = "template"`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | yes | O número de origem: 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_-]+$/ |
| `to` | `string` | no | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ |
| `recipient` | `string` | no | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. |
| `context` | `object` | no | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. |
| `context.message_id` | `string` | yes | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 to 256 characters |
| `callbackData` | `string` | no | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 to 512 characters |
| `typingMs` | `integer` | no | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · minimum 1 · maximum 25000 |
| `type` | `string` | yes | Sempre template. · Values: template |
| `template` | `object` | yes |  |
| `template.name` | `string` | yes | O nome do template já aprovado pela Meta. · 1 to 512 characters |
| `template.language` | `object` | yes |  |
| `template.language.code` | `string` | yes | O código do idioma do template, como pt_BR. Ele precisa bater com o aprovado. · 2 to 16 characters |
| `template.components` | `array<object>` | no | Os componentes que preenchem as variáveis do template. · up to 32 items |
| `template.components[].type` | `string` | yes | Qual parte do template este componente preenche. · Values: header, body, button |
| `template.components[].sub_type` | `string` | no | O subtipo, exigido pela Cloud API quando type é button. · up to 64 characters |
| `template.components[].index` | `string` | no | A posição do botão, exigida pela Cloud API quando type é button. · up to 8 characters |
| `template.components[].parameters` | `array<object>` | no | Os valores das variáveis desta parte, na forma que a Cloud API define. · up to 64 items |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/messages" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "from": "1000000000000001",
  "to": "5511900000000",
  "text": {
    "body": "Olá! Recebemos seu pedido e já estamos preparando."
  }
}'
```

#### Responses

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

```json
{
  "id": "ae60f288-7565-4315-a440-3663e9c231e1",
  "status": "queued"
}
```

**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": "window_closed",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A janela de atendimento desta conversa está fechada. Só é possível enviar mensagem livre até 24 horas depois da última mensagem do contato.",
  "fechadaEm": "2026-10-06T12:00:00.000Z",
  "acaoRecomendada": "Para falar com este contato agora, envie um template aprovado. A mensagem livre volta a ser aceita quando o contato responder, porque é a resposta dele que abre a janela. Se este contato escreveu há pouco e a janela devia estar aberta, confira o campo to: use o telefone do evento recebido (wa_id).",
  "detalheTecnico": "A Luna já acha a conversa do celular brasileiro com e sem o nono dígito, mas qualquer outra diferença no telefone não encontra a conversa. Se o contato escreveu sem telefone (só com BSUID, o identificador de usuário), envie com recipient igual ao user_id do evento, e não com to."
}
```

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

### Mark a message as read

`POST /v1/messages/{id}/read`

Marks a message you received as read on Meta, and returns 200 once it accepts.

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

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-post-v1-messages-id-read

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Code examples

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

#### Responses

**200**: A Meta aceitou a marcação.

```json
{}
```

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

### Show the typing indicator

`POST /v1/messages/{id}/typing`

Shows the recipient that you are writing, and returns 200 once Meta accepts.

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

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-post-v1-messages-id-typing

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Code examples

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

#### Responses

**200**: A Meta aceitou o indicador.

```json
{}
```

**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 one message's state

`GET /v1/messages/{id}`

Returns the message's current state, the timestamp of each step, and what Meta said whenever it refused something.

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

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "ae60f288-7565-4315-a440-3663e9c231e1",
  "wamid": null,
  "content": null,
  "status": "failed",
  "criadaEm": "2026-08-24T12:24:02.085Z",
  "enviadaEm": null,
  "entregueEm": null,
  "lidaEm": null,
  "callbackData": null,
  "pricing": null,
  "erros": [
    {
      "codigo": 131026,
      "categoria": "nao_entregavel",
      "mensagem": "O destinatário não pode receber esta mensagem: o número não tem WhatsApp, ou não existe.",
      "acaoRecomendada": "Confira o número do destinatário e reenvie para o número correto. Repetir o envio para o mesmo número não muda o resultado.",
      "original": {
        "error": {
          "message": "Message undeliverable",
          "type": "OAuthException",
          "code": 131026,
          "fbtrace_id": "AbCdEfGhIjK"
        }
      }
    }
  ]
}
```

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

### Cancel a message in the queue

`DELETE /v1/messages/{id}`

Cancels a message still in the outbound queue (accepted) and answers 204. It moves to the terminal state canceled, and the message.status event with status canceled reaches your webhook. If the message already went to Meta or has an outcome, it answers 409 message_not_cancelable with the current state.

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

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador da mensagem na Luna, como POST /v1/messages o devolveu. |

#### Code examples

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/messages/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."
}
```

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

```json
{
  "error": "message_not_cancelable",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "Só uma mensagem que ainda está na fila de saída pode ser cancelada, e esta já saiu para a Meta ou já tem um desfecho. O estado atual vem em status; confira o resultado com GET /v1/messages/{id}.",
  "status": "sent"
}
```

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

### Replay a message's webhook

`POST /v1/messages/{id}/replay`

Asks for this message's event to be delivered to your endpoint again: the message.received if it was received, or the latest message.status if it was sent, with the same format and the same signature as the original. The response is 202: the request was recorded, and delivery happens asynchronously. A sent message that has no state yet, or that Meta has not accepted yet, answers 400.

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

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-post-v1-messages-id-replay

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Code examples

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

#### Responses

**202**: O pedido de reenvio foi registrado. A entrega acontece de forma assíncrona, pelo mesmo caminho de sempre.

```json
{
  "deliveryId": "9f2a1b0c-3d4e-4f5a-8b9c-0d1e2f3a4b5c",
  "requestedAt": "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": "no_webhook_endpoint",
  "docsUrl": "https://lunahia.com.br/docs/receber-eventos",
  "message": "Não há endpoint de webhook ativo para entregar este reenvio. Cadastre um em POST /v1/webhooks/endpoints, ou retome um pausado em PATCH /v1/webhooks/endpoints/{id}, e peça de novo."
}
```

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

### Simulate a received message

`POST /v1/test-mode/inbound-messages`

Delivers ONE example message.received to your webhook endpoints, signed and with test: true on the envelope, so you can exercise your code without waiting for a contact to write. The message goes out in about half a second, and nothing is stored or goes through a number of yours or through Meta. It works with the test key and with the regular key.

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phoneNumberId` | `string` | no | O phone_number_id que aparece no evento. Texto livre: a Luna não procura o número. Ausente, 123456789012345. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `waId` | `string` | no | O telefone de quem "escreveu", só dígitos. Ausente, 5511900000000. · /^[1-9]\d{7,14}$/ |
| `text` | `string` | no | O texto da mensagem recebida. Ausente, um texto de exemplo. · 1 to 4096 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/test-mode/inbound-messages" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumberId": "YOUR_PHONENUMBERID",
  "waId": "YOUR_WAID",
  "text": "YOUR_TEXT"
}'
```

#### Responses

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

```json
{
  "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
  "wamid": "wamid.TESTE_3f6a1c529d4e4b87a1f05e2c7b9d8a14",
  "endpoints": 1
}
```

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

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

## Conversations

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

### List conversations

`GET /v1/conversations`

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

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

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

#### Query parameters

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

#### Code examples

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

#### Responses

**200**: Success.

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

**400**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

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

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.

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

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

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

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

## Media

Upload a file to Meta and download the media that arrived in a message.

### Get a message's media

`GET /v1/messages/{id}/media`

Returns a signed URL, issued by Luna, to download media that has already been persisted.

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

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "url": "https://c1b129d42065073c6f8b203801c44b2d.r2.cloudflarestorage.com/lunabucket/midia/ae60f288-7565-4315-a440-3663e9c231e1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=EXEMPLO",
  "expiraEm": "2026-08-24T12:29:02.085Z"
}
```

**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": "media_not_ready",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A mídia desta mensagem ainda não está disponível.",
  "estado": "pendente"
}
```

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

### Download media through the notice link

`GET /v1/media/{token}`

The link that comes in media.url on the message.received and message.echo notices. It asks for no API key: the token in the address is the credential. Ready media answers 302 to a short-lived signed URL; media still being downloaded from Meta, 409 with Retry-After; a token that does not exist or has expired, 404.

Authentication: Public, no key

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

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | O token do link, como veio em media.url. |

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/media/YOUR_TOKEN"
```

#### Responses

**302**: Redirect: follow the Location header, which leads to the signed URL of the file.

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

**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": "media_not_ready",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "A mídia desta mensagem ainda não está disponível.",
  "estado": "pendente"
}
```

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

### Upload a file and get its media identifier

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

Takes a file in multipart/form-data under the field file, uploads it to Meta and returns its identifier.

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

Topic guide: https://lunahia.com.br/en/docs/send-messages#rota-post-v1-numbers-id-media

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

`multipart/form-data`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `string (binary)` | yes | The file to upload, in the file field. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/media" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -F "file=@./pedido.jpg;type=image/jpeg"
```

#### Responses

**200**: Success.

```json
{
  "mediaId": "1425835918205946"
}
```

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

**413**: The file is over the size ceiling, which is the same for every customer.

```json
{
  "error": "file_too_large",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura."
}
```

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

## Templates

Messages pre-approved by Meta, required to start a conversation outside the 24 hour window.

Approved is not cleared for volume: Meta applies a pace of its own over the first sends of a new template, and publishes no deadline and no mechanics. Ramp up your first send instead of scheduling it for a date, and watch the state of the template.

Above three buttons, only two appear in the delivered message. Meta accepts the template with more and delivers two, so the arrangement has to be decided before the flow is designed.

### List templates

`GET /v1/templates`

This customer's templates, newest first.

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

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

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | no | Devolve apenas os templates cujo último estado observado é exatamente este valor. A comparação é literal e sensível a maiúsculas. Valores comuns: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, mas o campo é texto livre, porque a Meta acrescenta estado sem aviso e um conjunto fechado impediria você de filtrar pelo estado novo. |
| `wabaId` | `string` | no | Devolve apenas os templates desta conta de negócio na Meta (WABA), o wabaId que GET /v1/business-accounts devolve. Com um cliente seu por conta, é o jeito de ver só os templates dele. Comparação exata. |
| `phoneNumberId` | `string` | no | Devolve apenas os templates da conta de negócio a que este número pertence. Aceita o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Template é da conta, e não do número: todos os números da conta compartilham os mesmos templates. |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "id": "ae60f288-7565-4315-a440-3663e9c231e1",
      "metaTemplateId": "1259544702043801",
      "wabaId": "102290129340398",
      "name": "numero_conectado",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "APPROVED",
      "createdAt": "2026-08-10T12:24:02.085Z",
      "updatedAt": "2026-08-10T12:31:47.004Z",
      "bodyText": "Olá {{primeiro_nome}}, o seu número foi conectado.",
      "header": null,
      "headerMedia": null,
      "footer": null,
      "buttons": [],
      "variables": [
        {
          "name": "primeiro_nome",
          "example": "Maria"
        }
      ],
      "rejectedReason": null,
      "qualityScore": "GREEN",
      "previousCategory": null,
      "allowedActions": [
        "edit",
        "delete"
      ]
    }
  ]
}
```

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

### Create a template

`POST /v1/templates`

Creates the template in the customer's account and submits it to Meta for approval.

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

Topic guide: https://lunahia.com.br/en/docs/templates#rota-post-v1-templates

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `wabaId` | `string` | yes | 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `name` | `string` | yes | /^[a-z0-9_]{1,512}$/ |
| `bodyText` | `string` | yes | 1 to 1024 characters |
| `examples` | `object` | no | Um valor de amostra por variável do corpo. Obrigatório quando o corpo tem `{{variavel}}`, porque a Meta recusa parâmetro sem exemplo. |
| `header` | `string` | no | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 to 60 characters |
| `headerMedia` | `object` | no | Cabeçalho de imagem, vídeo ou documento. O handle vem de POST /v1/template-assets, e não do identificador de mídia de mensagem. O arquivo é o exemplo que a Meta revisa, e não o conteúdo entregue: cada mensagem enviada fornece a própria mídia. |
| `headerMedia.format` | `string` | yes | IMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF. · Values: IMAGE, VIDEO, DOCUMENT |
| `headerMedia.handle` | `string` | yes | O handle devolvido por POST /v1/template-assets. · 1 to 2048 characters |
| `footer` | `string` | no | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 to 60 characters |
| `buttons` | `array<object>` | no | Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois. |
| `buttons[].type` | `string` | no | Values: QUICK_REPLY |
| `buttons[].text` | `string` | no | 1 to 25 characters |
| `buttons[].url` | `string` | no | 1 to 2000 characters |
| `buttons[].example` | `array<string>` | no | up to 1 items |
| `buttons[].phone_number` | `string` | no | 1 to 20 characters |
| `category` | `string` | no | A categoria do template. Ausente vale UTILITY, que é o comportamento de quem já integra e não manda o campo. A Meta pode reclassificar na criação: o template continua aprovado, com outra categoria, e a resposta traz a que ela atribuiu. Template de autenticação tem corpo próprio e ainda não é criado por esta rota. · Values: MARKETING, UTILITY |
| `language` | `string` | no | O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business. · /^[a-z]{2,3}(_[A-Z]{2})?$/ |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/templates" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "bodyText": "YOUR_BODYTEXT"
}'
```

#### Responses

**201**: Created.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "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."
}
```

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

### Read a template

`GET /v1/templates/{id}`

The template's current state at Meta, the content you wrote, and what Meta announced about it.

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

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

#### Path parameters

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT",
  "bodyText": "YOUR_BODYTEXT",
  "header": "YOUR_HEADER",
  "headerMedia": {
    "format": "YOUR_FORMAT"
  },
  "footer": "YOUR_FOOTER",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "YOUR_TEXT"
    }
  ],
  "variables": [
    {
      "name": "YOUR_NAME",
      "example": "YOUR_EXAMPLE"
    }
  ],
  "rejectedReason": "YOUR_REJECTEDREASON",
  "qualityScore": "YOUR_QUALITYSCORE",
  "previousCategory": "YOUR_PREVIOUSCATEGORY",
  "allowedActions": [
    "edit"
  ]
}
```

**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 template

`PATCH /v1/templates/{id}`

Changes the components of an existing template.

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

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

#### Path parameters

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bodyText` | `string` | no | 1 to 1024 characters |
| `examples` | `object` | no |  |
| `header` | `string` | no | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 to 60 characters |
| `footer` | `string` | no | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 to 60 characters |
| `buttons` | `array<object>` | no | Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois. |
| `buttons[].type` | `string` | no | Values: QUICK_REPLY |
| `buttons[].text` | `string` | no | 1 to 25 characters |
| `buttons[].url` | `string` | no | 1 to 2000 characters |
| `buttons[].example` | `array<string>` | no | up to 1 items |
| `buttons[].phone_number` | `string` | no | 1 to 20 characters |

#### Code examples

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/templates/YOUR_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bodyText": "YOUR_BODYTEXT",
  "examples": {},
  "header": "YOUR_HEADER"
}'
```

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "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."
}
```

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

### Delete a template

`DELETE /v1/templates/{id}`

Deletes the template at Meta and from your listing.

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

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

#### Path parameters

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

#### Code examples

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/templates/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."
}
```

### Read the template rules

`GET /v1/templates/rules`

The categories, the suggested languages, the name format, the maximum lengths of body, header and footer, and the button limits. It is what POST /v1/templates enforces, served so you can show the same limit without copying the number.

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "categories": [
    {
      "value": "MARKETING",
      "label": "Marketing",
      "summary": "Promove, convida ou tenta reengajar: oferta, novidade, carrinho esquecido. A Meta pode reclassificar um template de utilidade para marketing."
    }
  ],
  "languages": [
    {
      "code": "pt_BR",
      "label": "Português (Brasil)"
    }
  ],
  "namePattern": "^[a-z0-9_]{1,512}$",
  "nameExample": "confirmacao_do_pedido",
  "bodyMaxLength": 1024,
  "headerMaxLength": 60,
  "footerMaxLength": 60,
  "buttonLimits": {
    "total": 10,
    "byType": {
      "QUICK_REPLY": 10,
      "URL": 2,
      "PHONE_NUMBER": 1,
      "COPY_CODE": 1
    }
  }
}
```

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

### Create an authentication template

`POST /v1/templates/authentication`

Creates an authentication template with a copy code button, and submits it to Meta for approval.

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

Topic guide: https://lunahia.com.br/en/docs/templates#rota-post-v1-templates-authentication

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `wabaId` | `string` | yes | 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `name` | `string` | yes | /^[a-z0-9_]{1,512}$/ |
| `language` | `string` | no | O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business. · /^[a-z]{2,3}(_[A-Z]{2})?$/ |
| `addSecurityRecommendation` | `boolean` | no | Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso. |
| `codeExpirationMinutes` | `integer` | yes | Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela. · minimum 1 · maximum 1440 |
| `buttonText` | `string` | no | O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres. · 1 to 25 characters |
| `messageSendTtlSeconds` | `integer` | no | Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe. · minimum 1 |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/templates/authentication" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "codeExpirationMinutes": 10
}'
```

#### Responses

**201**: Created.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "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."
}
```

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

### Copy a template to other customers

`POST /v1/templates/{id}/copy`

Creates a copy of the template in up to 50 destinations, each a business account (wabaId) or a customer of yours (externalId). Answers 200 with one result per destination, and a destination that fails does not bring the others down. The copy goes through the same path and the same rules as POST /v1/templates.

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

#### Path parameters

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `targets` | `array<object>` | yes | Os destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }. · 1 to 50 items |
| `targets[].wabaId` | `string` | no | A conta de negócio de destino, pelo id dela na Meta (wabaId). · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `targets[].externalId` | `string` | no | O rótulo do cliente de destino (externalId): a cópia vai para cada conta de WhatsApp Business dos números dele. · 1 to 128 characters |
| `headerMediaHandle` | `string` | no | O handle do arquivo de exemplo do cabeçalho de mídia, para template de origem que tem um. A Luna guarda só o formato do cabeçalho, não o arquivo. · 1 to 1024 characters |
| `authentication` | `object` | no | Os parâmetros do template de autenticação, obrigatórios quando o template de origem é de autenticação: a Luna não os guarda. |
| `authentication.addSecurityRecommendation` | `boolean` | no | Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso. |
| `authentication.codeExpirationMinutes` | `integer` | yes | Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela. · minimum 1 · maximum 1440 |
| `authentication.buttonText` | `string` | no | O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres. · 1 to 25 characters |
| `authentication.messageSendTtlSeconds` | `integer` | no | Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe. · minimum 1 |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/templates/YOUR_ID/copy" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "targets": [
    {
      "wabaId": "YOUR_WABAID",
      "externalId": "YOUR_EXTERNALID"
    }
  ]
}'
```

#### Responses

**200**: Success.

```json
{
  "results": [
    {
      "target": {
        "wabaId": "YOUR_WABAID",
        "externalId": "YOUR_EXTERNALID"
      },
      "wabaId": "YOUR_WABAID",
      "status": 1,
      "template": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "metaTemplateId": "YOUR_METATEMPLATEID",
        "wabaId": "YOUR_WABAID",
        "name": "YOUR_NAME",
        "language": "YOUR_LANGUAGE",
        "category": "YOUR_CATEGORY",
        "status": "YOUR_STATUS",
        "createdAt": "YOUR_CREATEDAT",
        "updatedAt": "YOUR_UPDATEDAT"
      },
      "error": {
        "error": "YOUR_ERROR",
        "message": "YOUR_MESSAGE"
      }
    }
  ]
}
```

**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": "template_content_unknown",
  "docsUrl": "https://lunahia.com.br/docs/templates",
  "message": "A Luna não conhece o conteúdo deste template: ele foi criado direto no painel da Meta, ou antes de a Luna guardar o conteúdo. Sem o conteúdo não há o que copiar. Crie o template de novo por POST /v1/templates e copie o novo."
}
```

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

### Upload the example file for a media header

`POST /v1/template-assets`

Takes a file in multipart/form-data under the field file and returns the handle that template creation accepts in headerMedia.handle.

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

Topic guide: https://lunahia.com.br/en/docs/templates#rota-post-v1-template-assets

#### Request body

`multipart/form-data`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `string (binary)` | yes | The file to upload, in the file field. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/template-assets" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -F "file=@./pedido.jpg;type=image/jpeg"
```

#### Responses

**200**: Success.

```json
{
  "handle": "4:cGVkaWRvLnBuZw==:aW1hZ2UvcG5n:ARb0Xk:e:1790451084:1269849425120687:0"
}
```

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

**413**: The file is over the size ceiling, which is the same for every customer.

```json
{
  "error": "file_too_large",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura."
}
```

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

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

## Connection links

A link your customer opens to connect their WhatsApp number, without receiving your console login. One link per customer of yours, tied to the externalId you chose.

### List connect links

`GET /v1/onboarding/links`

The links you created, newest first, revoked ones included. Filters: externalId (exact), q (start of the externalId) and status (open, used, expired or revoked).

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

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-get-v1-onboarding-links

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | `string` | no | O começo do rótulo do seu cliente: os links cujo externalId começa com este texto, sem diferenciar maiúscula. Use no lugar de externalId quando você só lembra do começo. Combina com os outros filtros. |
| `externalId` | `string` | no | O rótulo que você deu ao seu cliente (externalId): só os links dele. Igualdade exata; um rótulo sem link devolve lista vazia. |
| `status` | `string` | no | Só os links neste estado: open, used, expired ou revoked. |
| `limit` | `integer` | no |  |
| `cursor` | `string` | no |  |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalId": "YOUR_EXTERNALID",
      "status": "open",
      "createdAt": "YOUR_CREATEDAT",
      "purpose": "new",
      "revokedAt": "YOUR_REVOKEDAT",
      "lastFailure": {
        "step": "YOUR_STEP",
        "reason": "YOUR_REASON",
        "at": "YOUR_AT"
      },
      "allowedActions": [
        "revoke"
      ],
      "expiresAt": "YOUR_EXPIRESAT",
      "usedAt": "YOUR_USEDAT",
      "redirectUrl": "YOUR_REDIRECTURL",
      "displayName": "YOUR_DISPLAYNAME",
      "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "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."
}
```

### Create a connect link for your customer

`POST /v1/onboarding/links`

Creates a link your customer opens to connect their own WhatsApp number, without being given your console login.

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

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-onboarding-links

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | `string` | no | O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão. · 1 to 128 characters |
| `displayName` | `string` | no | O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada. · 1 to 120 characters |
| `redirectUrl` | `string` | no | Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna. · up to 2048 characters · /^https:\/\/[^\s]+$/ |
| `numberId` | `string` | no | O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "YOUR_EXTERNALID",
  "displayName": "YOUR_DISPLAYNAME",
  "redirectUrl": "YOUR_REDIRECTURL"
}'
```

#### Responses

**201**: Created.

```json
{
  "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10",
  "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU",
  "expiresAt": "2026-10-10T14:00:00.000Z",
  "externalId": "cliente-8841",
  "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado",
  "displayName": "Escritório Silva & Filhos"
}
```

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

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

### Read a connect link

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

A link's state: open, used, expired or revoked, with its purpose, its last failure and what the account can do with it.

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

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-get-v1-onboarding-links-id

#### Path parameters

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalId": "YOUR_EXTERNALID",
  "status": "open",
  "createdAt": "YOUR_CREATEDAT",
  "purpose": "new",
  "revokedAt": "YOUR_REVOKEDAT",
  "lastFailure": {
    "step": "YOUR_STEP",
    "reason": "YOUR_REASON",
    "at": "YOUR_AT"
  },
  "allowedActions": [
    "revoke"
  ],
  "expiresAt": "YOUR_EXPIRESAT",
  "usedAt": "YOUR_USEDAT",
  "redirectUrl": "YOUR_REDIRECTURL",
  "displayName": "YOUR_DISPLAYNAME",
  "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

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

### Revoke a connect link

`DELETE /v1/onboarding/links/{id}`

Revokes the link. The url stops working at once and answers 404 to whoever opens it, like one that never existed. A connection the customer had already started in Meta's window can no longer be completed through it. The link stays in your list, with status revoked and revokedAt. Revoking an already revoked link answers 404.

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

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-delete-v1-onboarding-links-id

#### Path parameters

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

#### Code examples

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/onboarding/links/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."
}
```

### Create several connect links at once

`POST /v1/onboarding/links/batch`

Creates up to 100 links, each item in the same shape as POST /v1/onboarding/links and under the same rules, plan capacity included. Answers 200 with one result per item, with the url of each created link; an item that fails does not bring the others down.

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `links` | `array<object>` | yes | De 1 a 100 links, cada um no mesmo formato do corpo de POST /v1/onboarding/links: externalId, displayName, redirectUrl e numberId, todos opcionais. · 1 to 100 items |
| `links[].externalId` | `string` | no | O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão. · 1 to 128 characters |
| `links[].displayName` | `string` | no | O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada. · 1 to 120 characters |
| `links[].redirectUrl` | `string` | no | Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna. · up to 2048 characters · /^https:\/\/[^\s]+$/ |
| `links[].numberId` | `string` | no | O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/links/batch" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "links": [
    {
      "externalId": "YOUR_EXTERNALID",
      "displayName": "YOUR_DISPLAYNAME",
      "redirectUrl": "YOUR_REDIRECTURL"
    }
  ]
}'
```

#### Responses

**200**: Success.

```json
{
  "results": [
    {
      "index": 1,
      "status": 1,
      "link": {
        "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10",
        "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU",
        "expiresAt": "2026-10-10T14:00:00.000Z",
        "externalId": "cliente-8841",
        "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado",
        "displayName": "Escritório Silva & Filhos"
      },
      "error": {
        "error": "YOUR_ERROR",
        "message": "YOUR_MESSAGE"
      }
    }
  ]
}
```

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

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

### Generate the url of a connect link again

`POST /v1/onboarding/links/{id}/reissue`

Generates a new token for the same link (same id, label and expiry): the old url stops working at once and the new one appears only in this response. Only for an open link; used, expired or revoked answers 409. Use it when your customer lost the url, instead of revoking and creating another.

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

#### Path parameters

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10",
  "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU",
  "expiresAt": "2026-10-10T14:00:00.000Z",
  "externalId": "cliente-8841",
  "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado",
  "displayName": "Escritório Silva & Filhos"
}
```

**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": "link_not_open",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Só um link aberto pode ser reemitido, e este está usado. Crie um link novo com POST /v1/onboarding/links.",
  "status": "used"
}
```

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

## Webhooks and events

Where Luna delivers what arrives at your number, the secret that signs those deliveries, and the event types, each with its schema and an example.

### List webhook endpoints

`GET /v1/webhooks/endpoints`

The endpoints registered for this customer, newest first, with the endpoint limit and whether another can still be registered (limit and canCreate). Each endpoint carries deliveryStatus.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-endpoints

#### Code examples

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

#### Responses

**200**: Os endpoints cadastrados neste cliente, do mais recente para o mais antigo, com o limite de endpoints e se ainda dá para cadastrar outro (limit e canCreate).

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://exemplo.com.br/arquivo",
      "createdAt": "YOUR_CREATEDAT",
      "updatedAt": "YOUR_UPDATEDAT",
      "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT",
      "paused": true,
      "pausedAt": "YOUR_PAUSEDAT",
      "eventTypes": [
        "YOUR_EVENTTYPES"
      ],
      "externalIds": [
        "YOUR_EXTERNALIDS"
      ],
      "phoneNumberIds": [
        "YOUR_PHONENUMBERIDS"
      ],
      "headerNames": [
        "YOUR_HEADERNAMES"
      ],
      "lastDeliveryAt": "YOUR_LASTDELIVERYAT",
      "lastFailureAt": "YOUR_LASTFAILUREAT",
      "lastHttpStatus": 1,
      "deliveryStatus": "ok"
    }
  ],
  "limit": 1,
  "canCreate": true
}
```

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

### Register the webhook endpoint

`POST /v1/webhooks/endpoints`

Registers your server's URL and returns the secret that signs the deliveries. headers, optional, carries up to 5 own HTTP headers that Luna sends on every delivery (for a gateway that requires a fixed token); the values are secret and no response returns them.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-endpoints

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | yes | A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público. · up to 2048 characters |
| `eventTypes` | `array<string>` | no | Os tipos de evento que este endpoint recebe, por exemplo ["message.received", "message.status"]. Ausente ou vazio quer dizer todos, inclusive os tipos que a Luna criar depois. Com a lista preenchida, o endpoint só recebe esses tipos, e um tipo novo não chega até você incluí-lo. O filtro é só por tipo. O evento webhook.test não é filtrável: ele só sai quando você o pede. Os tipos estão no guia Receber eventos. · up to 30 items |
| `externalIds` | `array<string>` | no | Os clientes seus (externalId) de que este endpoint recebe eventos, por exemplo ["cliente-42"]. Ausente ou vazio quer dizer todos. Com a lista preenchida, o endpoint só recebe eventos de números com um destes externalId, inclusive os conectados depois, e dos links de conexão com ele. Eventos que não falam de um cliente (os de template, por exemplo) só chegam se a conta do template tem um número dele. O filtro é só por identificador. · up to 100 items |
| `phoneNumberIds` | `array<string>` | no | Os números de que este endpoint recebe eventos: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId), em qualquer mistura. A resposta devolve os ids da Meta, os mesmos que os eventos trazem em phone_number_id. Ausente ou vazio quer dizer todos. Um número que não é da conta responde 400. Para cobrir números que ainda serão conectados, use externalIds. · up to 100 items |
| `headers` | `object` | no | Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { "X-Token": "valor" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://exemplo.com.br/arquivo"
}'
```

#### Responses

**201**: O endpoint recém-criado, com o segredo de assinatura.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://exemplo.com.br/arquivo",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT",
  "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT",
  "paused": true,
  "pausedAt": "YOUR_PAUSEDAT",
  "eventTypes": [
    "YOUR_EVENTTYPES"
  ],
  "externalIds": [
    "YOUR_EXTERNALIDS"
  ],
  "phoneNumberIds": [
    "YOUR_PHONENUMBERIDS"
  ],
  "headerNames": [
    "YOUR_HEADERNAMES"
  ],
  "lastDeliveryAt": "YOUR_LASTDELIVERYAT",
  "lastFailureAt": "YOUR_LASTFAILUREAT",
  "lastHttpStatus": 1,
  "deliveryStatus": "ok",
  "secret": "YOUR_SECRET"
}
```

**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": "webhook_endpoint_limit",
  "docsUrl": "https://lunahia.com.br/docs/receber-eventos",
  "message": "Este cliente já tem o máximo de endpoints de webhook, e o limite é o mesmo para todos. Remova um endpoint com DELETE /v1/webhooks/endpoints/{id} para liberar a vaga.",
  "limit": 25
}
```

**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 the event types

`GET /v1/webhooks/event-types`

The event types Luna delivers, which eventTypes accepts when you register or update an endpoint. Each item carries the type, which is the value to send, a sentence that says what the event is, and the group it belongs to (group and groupLabel).

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-event-types

#### Code examples

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

#### Responses

**200**: Os tipos de evento que a Luna entrega, na ordem do contrato. O evento webhook.test não está na lista: ele só sai quando você o pede.

```json
{
  "data": [
    {
      "type": "YOUR_TYPE",
      "summary": "YOUR_SUMMARY",
      "group": "messages",
      "groupLabel": "YOUR_GROUPLABEL"
    }
  ]
}
```

**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 the webhook endpoint

`GET /v1/webhooks/endpoints/{id}`

The endpoint's configuration.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-endpoints-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do endpoint, devolvido no cadastro. |

#### Code examples

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

#### Responses

**200**: A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://exemplo.com.br/arquivo",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT",
  "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT",
  "paused": true,
  "pausedAt": "YOUR_PAUSEDAT",
  "eventTypes": [
    "YOUR_EVENTTYPES"
  ],
  "externalIds": [
    "YOUR_EXTERNALIDS"
  ],
  "phoneNumberIds": [
    "YOUR_PHONENUMBERIDS"
  ],
  "headerNames": [
    "YOUR_HEADERNAMES"
  ],
  "lastDeliveryAt": "YOUR_LASTDELIVERYAT",
  "lastFailureAt": "YOUR_LASTFAILUREAT",
  "lastHttpStatus": 1,
  "deliveryStatus": "ok"
}
```

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

### Update the webhook endpoint

`PATCH /v1/webhooks/endpoints/{id}`

Changes the URL, pauses or resumes the endpoint, or changes the event types it receives. Send url, paused, eventTypes, externalIds, phoneNumberIds, headers or any combination: a body with none of them answers 400.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-patch-v1-webhooks-endpoints-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do endpoint, devolvido no cadastro. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | no | A URL nova. Passa pela mesma validação do cadastro: https e endereço público. O segredo de assinatura continua o mesmo. · up to 2048 characters |
| `paused` | `boolean` | no | true pausa o endpoint: os eventos que ocorrerem enquanto ele estiver pausado não são entregues, nem depois. false o retoma, e ele passa a receber os eventos a partir desse momento. |
| `eventTypes` | `array<string>` | no | Troca a lista de tipos que o endpoint recebe: a lista enviada substitui a anterior. Lista vazia volta a receber todos. O que ocorreu antes da troca e foi filtrado não é entregue depois. · up to 30 items |
| `externalIds` | `array<string>` | no | Troca a lista de clientes de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Vale daí em diante. · up to 100 items |
| `phoneNumberIds` | `array<string>` | no | Troca a lista de números de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Aceita o UUID da Luna ou o id da Meta. · up to 100 items |
| `headers` | `object` | no | Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { "X-Token": "valor" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos. |

#### Code examples

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://exemplo.com.br/arquivo",
  "paused": true,
  "eventTypes": [
    "message.received"
  ]
}'
```

#### Responses

**200**: A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://exemplo.com.br/arquivo",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT",
  "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT",
  "paused": true,
  "pausedAt": "YOUR_PAUSEDAT",
  "eventTypes": [
    "YOUR_EVENTTYPES"
  ],
  "externalIds": [
    "YOUR_EXTERNALIDS"
  ],
  "phoneNumberIds": [
    "YOUR_PHONENUMBERIDS"
  ],
  "headerNames": [
    "YOUR_HEADERNAMES"
  ],
  "lastDeliveryAt": "YOUR_LASTDELIVERYAT",
  "lastFailureAt": "YOUR_LASTFAILUREAT",
  "lastHttpStatus": 1,
  "deliveryStatus": "ok"
}
```

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

### Remove the webhook endpoint

`DELETE /v1/webhooks/endpoints/{id}`

Removes the endpoint. The response is 204, and the endpoint stops receiving events.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-delete-v1-webhooks-endpoints-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do endpoint, devolvido no cadastro. |

#### Code examples

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/webhooks/endpoints/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."
}
```

### List the endpoint's deliveries

`GET /v1/webhooks/endpoints/{id}/deliveries`

The delivery attempts to the endpoint over the last 7 days, newest first: eventId, eventType, status, httpStatus (null when your server did not answer), durationMs, attempt and at. Filters: status (success or failed), eventType and since. It does not carry the body sent or what your server answered.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-endpoints-id-deliveries

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do endpoint, devolvido no cadastro. |

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | Quantos itens trazer. Padrão 50, máximo 100, igual para todos. |
| `status` | `string` | no | success: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta. |
| `eventType` | `string` | no | Só as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types). |
| `since` | `any` | no | Só as tentativas deste instante em diante (ISO 8601, ou a data pura, que vale meia-noite UTC). O histórico guarda 7 dias. |
| `cursor` | `string` | no | O nextCursor da página anterior. Omita na primeira. |

#### Code examples

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

#### Responses

**200**: O histórico de entregas do endpoint nos últimos 7 dias, uma linha por tentativa. Não traz o corpo enviado nem o que o seu servidor respondeu: só o status.

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "eventId": "YOUR_EVENTID",
      "eventType": "YOUR_EVENTTYPE",
      "status": "success",
      "httpStatus": 1,
      "durationMs": 1,
      "attempt": 1,
      "at": "YOUR_AT"
    }
  ],
  "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."
}
```

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

### Send a test event

`POST /v1/webhooks/endpoints/{id}/test`

Sends ONE webhook.test event to the endpoint, now, and returns the result in the response itself. The event goes out signed, with the same headers, the same signature and the same destination defenses as a real delivery, so a test that passes proves that the URL and signature verification work. With eventType in the body, the event is an example of that type, with a made-up body and test: true in the envelope.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-endpoints-id-test

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do endpoint, devolvido no cadastro. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `eventType` | `string` | no | Um tipo de GET /v1/webhooks/event-types. A Luna entrega ao endpoint um exemplo desse tipo, com corpo de mentira (identificadores que não existem) e test: true no envelope, para você exercitar o seu código sem esperar o evento de verdade. Ausente, o teste é o webhook.test de sempre. O exemplo não passa por nenhum número seu. · Values: message.received, message.status, contact.identity_changed, contact.preferences_changed, backlog.dropped, history_sync.deadline_approaching, message.echo, template.status, number.connected, number.payment_required, number.payment_resolved, account.restricted, account.violation, account.disabled, account.reinstated, account.update, account.limit_changed, number.disconnected, number.quality_changed, number.display_name_reviewed, number.credential_expiring, account.alert, number.action_required, number.action_resolved, onboarding.link.completed, onboarding.link.opened, onboarding.link.failed, onboarding.link.expired, template.category, template.quality |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID/test" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "message.received"
}'
```

#### Responses

**200**: O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito.

```json
{
  "delivered": true,
  "statusCode": 1,
  "durationMs": 1,
  "failure": "timeout"
}
```

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

### Rotate the signing secret

`POST /v1/webhooks/endpoints/{id}/rotacionar`

Mints a new secret and returns it once. Store it now, as on registration.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-endpoints-id-rotacionar

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador do endpoint, devolvido no cadastro. |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revokePrevious` | `boolean` | no | Com true, o segredo anterior deixa de valer no mesmo instante, em vez de seguir válido por sete dias. Use quando o segredo anterior vazou. As entregas que já saíram assinadas só com ele falham na verificação do seu lado. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID/rotacionar" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "revokePrevious": true
}'
```

#### Responses

**200**: O endpoint com o segredo novo. O anterior continua válido até previousSecretExpiresAt, então você pode trocar a configuração do seu lado sem pressa e sem perder entrega.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://exemplo.com.br/arquivo",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT",
  "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT",
  "paused": true,
  "pausedAt": "YOUR_PAUSEDAT",
  "eventTypes": [
    "YOUR_EVENTTYPES"
  ],
  "externalIds": [
    "YOUR_EXTERNALIDS"
  ],
  "phoneNumberIds": [
    "YOUR_PHONENUMBERIDS"
  ],
  "headerNames": [
    "YOUR_HEADERNAMES"
  ],
  "lastDeliveryAt": "YOUR_LASTDELIVERYAT",
  "lastFailureAt": "YOUR_LASTFAILUREAT",
  "lastHttpStatus": 1,
  "deliveryStatus": "ok",
  "secret": "YOUR_SECRET"
}
```

**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 deliveries that failed for good

`GET /v1/webhooks/dlq`

The events Luna tried to deliver to your endpoint and gave up on, newest first, each with the number, the customer label, the attempts, the last HTTP status and what can be done with it (allowedActions). Filters: endpointId, externalId and requeued.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-get-v1-webhooks-dlq

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | no | O cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página. |
| `limit` | `integer` | no | Quantos itens trazer nesta página. Máximo 100, igual para todos. |
| `endpointId` | `string` | no | Só os itens deste endpoint. |
| `externalId` | `string` | no | Só os itens dos números deste cliente seu (externalId do número). Igualdade exata; um rótulo sem item devolve lista vazia. |
| `requeued` | `string` | no | true: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions). |

#### Code examples

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

#### Responses

**200**: Uma página da fila de rejeitados. Sem total e sem contagem: a Luna não soma entregas, e nenhum número desta resposta alimenta cobrança. attempts e lastHttpStatus descrevem UMA entrega que falhou, e não um agregado.

```json
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "endpointId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "eventType": "message.received",
      "wamid": "YOUR_WAMID",
      "rejectedAt": "YOUR_REJECTEDAT",
      "failureReason": "http_4xx",
      "requeuedAt": "YOUR_REQUEUEDAT",
      "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalId": "YOUR_EXTERNALID",
      "attempts": 1,
      "lastHttpStatus": 1,
      "allowedActions": [
        "requeue"
      ]
    }
  ],
  "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."
}
```

### Requeue a failed delivery

`POST /v1/webhooks/dlq/{id}/reenfileirar`

Puts the event back on the delivery queue. The response is 202: the request was recorded, and delivery happens asynchronously.

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

Topic guide: https://lunahia.com.br/en/docs/receive-events#rota-post-v1-webhooks-dlq-id-reenfileirar

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | O identificador deste item na fila de rejeitados. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/webhooks/dlq/YOUR_ID/reenfileirar" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**202**: O item foi recolocado na fila de entrega. A entrega em si é assíncrona, como qualquer outra: se o seu endpoint ainda estiver fora do ar, ela será adiada e retentada pela mesma política de sempre.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "requeuedAt": "YOUR_REQUEUEDAT"
}
```

**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": "already_requeued",
  "docsUrl": "https://lunahia.com.br/docs/receber-eventos",
  "message": "Este item já foi re-enfileirado.",
  "reenfileiradoEm": "2026-10-06T12:00:00.000Z"
}
```

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

## Keys

Create, list and revoke the credentials that authenticate your calls.

### List API keys

`GET /v1/api-keys`

This customer's keys, with scopes, profile, status (active, revoked or expired), creation date, last use, revocation and what the account can do with each one (allowedActions).

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

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-api-keys

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `string` | no |  |

#### Code examples

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

#### Responses

**200**: Success.

```json
[
  {
    "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334",
    "label": "integração de produção",
    "kind": "integration",
    "scopes": [
      "messages:write",
      "messages:read",
      "numbers:read"
    ],
    "mode": "live",
    "externalId": null,
    "createdAt": "2026-08-07T12:10:44.201Z",
    "expiresAt": null,
    "revokedAt": null,
    "lastUsedAt": "2026-08-10T09:02:18.664Z",
    "status": "active",
    "profile": "agent",
    "allowedActions": [
      "revoke"
    ]
  }
]
```

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

### Create an API key

`POST /v1/api-keys`

Mints a new key and returns the secret exactly once. Store it the moment you receive it, because no route will return it again.

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

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-api-keys

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | no | 1 to 120 characters |
| `scopes` | `array<string>` | no | O que a chave pode fazer, escopo por escopo. Mande scopes ou profile, e nunca os dois: a lista de escopos que cada perfil concede está em GET /v1/api-keys/profiles. · at least 1 items |
| `profile` | `string` | no | Um perfil pronto no lugar de scopes: agent (atendimento), full (integração completa) ou read_only (somente leitura). A chave nasce com os escopos que o perfil concede no momento da criação, e a lista deles está em GET /v1/api-keys/profiles. · Values: agent, full, read_only |
| `expiresAt` | `string (date-time)` | no |  |
| `mode` | `string` | no | live (o padrão) é a chave de sempre. test cria uma chave do modo de teste: POST /v1/messages com ela NÃO vai à Meta, não usa número seu e não conta na capacidade do plano; a Luna devolve ao seu webhook eventos simulados, assinados e com test: true. Uma chave de teste só usa POST /v1/messages e POST /v1/test-mode/inbound-messages, e não aceita externalId. Não dá para mudar depois: crie outra. · Values: live, test |
| `externalId` | `string` | no | O seu identificador para o cliente a que esta chave pertence (1 a 128 caracteres), o mesmo externalId do link de conexão e dos números. Com ele, a chave é de UM cliente seu: só lê e envia pelos números com este externalId (inclusive os conectados depois), só cria link com ele, e não lista nem cria endpoints de webhook nem chaves. Sem ele, a chave é da conta inteira. Não dá para mudar depois: crie outra. · 1 to 128 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/api-keys" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "YOUR_LABEL",
  "scopes": [
    "keys:read"
  ],
  "profile": "agent"
}'
```

#### Responses

**201**: Created.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": "YOUR_LABEL",
  "kind": "integration",
  "scopes": [
    "YOUR_SCOPES"
  ],
  "mode": "live",
  "externalId": "YOUR_EXTERNALID",
  "createdAt": "YOUR_CREATEDAT",
  "expiresAt": "YOUR_EXPIRESAT",
  "revokedAt": "YOUR_REVOKEDAT",
  "lastUsedAt": "YOUR_LASTUSEDAT",
  "status": "active",
  "profile": "agent",
  "allowedActions": [
    "revoke"
  ],
  "secret": "YOUR_SECRET"
}
```

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

**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 the scopes a key can have

`GET /v1/api-keys/scopes`

The scopes an integration key can receive, each with its name in Portuguese, what it allows and whether it gives a power that calls for care.

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "scope": "messages:write",
      "label": "Enviar mensagens",
      "summary": "Envia mensagens e templates pelos números conectados.",
      "sensitive": false
    },
    {
      "scope": "keys:write",
      "label": "Criar e revogar chaves",
      "summary": "Permite que esta chave crie outras chaves, sem prazo. Dê só a quem precisa.",
      "sensitive": true
    }
  ]
}
```

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

### List the key profiles

`GET /v1/api-keys/profiles`

The ready-made key profiles (agent, full and read_only) and the scopes each one grants. In POST /v1/api-keys, profile stands in for scopes.

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "id": "read_only",
      "label": "Somente leitura",
      "summary": "Consulta tudo e não altera nada.",
      "scopes": [
        "keys:read",
        "numbers:read",
        "messages:read",
        "templates:read",
        "webhooks:read"
      ]
    }
  ]
}
```

**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 API key

`GET /v1/api-keys/{id}`

One key's metadata. The secret does not come back, for the reason described on the listing route.

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

#### Path parameters

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334",
  "label": "integração de produção",
  "kind": "integration",
  "scopes": [
    "messages:write",
    "messages:read",
    "numbers:read"
  ],
  "mode": "live",
  "externalId": null,
  "createdAt": "2026-08-07T12:10:44.201Z",
  "expiresAt": null,
  "revokedAt": null,
  "lastUsedAt": "2026-08-10T09:02:18.664Z",
  "status": "active",
  "profile": "agent",
  "allowedActions": [
    "revoke"
  ]
}
```

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

### Revoke an API key

`POST /v1/api-keys/{id}/revoke`

Invalidates the key immediately. The operation is idempotent, so revoking again returns the same result without an error.

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

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-api-keys-id-revoke

#### Path parameters

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334",
  "label": "integração de produção",
  "kind": "integration",
  "scopes": [
    "messages:write",
    "messages:read",
    "numbers:read"
  ],
  "mode": "live",
  "externalId": null,
  "createdAt": "2026-08-07T12:10:44.201Z",
  "expiresAt": null,
  "revokedAt": null,
  "lastUsedAt": "2026-08-10T09:02:18.664Z",
  "status": "active",
  "profile": "agent",
  "allowedActions": [
    "revoke"
  ]
}
```

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

## Account and plan

The credential's account, the plan, the number capacity and how many are in use in the period.

### Read the plan and the subscription

`GET /v1/subscription`

The account's plan (free trial or contracted), the number capacity and how many are in use, and what Helsen charges for the period: the capacity of active numbers, and nothing beyond that.

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

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-subscription

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inicio` | `string` | no |  |
| `fim` | `string` | no |  |

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "planName": "Growth",
  "status": "trial",
  "suspendedReason": null,
  "capacity": 20,
  "activeNumbers": 3,
  "trialEndsAt": "2026-11-03T13:00:00.000Z",
  "trialDaysLeft": 5,
  "periodo": {
    "inicio": "2026-03-01T00:00:00.000Z",
    "fim": "2026-04-01T00:00:00.000Z"
  },
  "canConnectNumber": true,
  "capacityLeft": 17,
  "capacityNotice": null,
  "writesAllowed": true,
  "suspendedNotice": null,
  "pricePerMonth": 990,
  "currency": "BRL",
  "contactEmail": "contato@lunahia.com.br",
  "numerosAtivos": 3,
  "phoneNumberIds": [
    "15550001111",
    "15550002222"
  ]
}
```

**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 the platform's technical limits

`GET /v1/limits`

The ceilings the API applies, each with its value, unit and reason. They are the same for every customer and do not depend on the plan: they exist for infrastructure capacity or because Meta imposes them. They are not a count of your usage and do not enter billing.

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "key": "webhook_endpoints",
      "label": "Endpoints de webhook por cliente",
      "value": 25,
      "unit": "endpoints",
      "reason": "Cada evento é entregue a cada endpoint que o aceita. Remover um endpoint libera a vaga."
    }
  ]
}
```

**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 Meta's pricing rules

`GET /v1/meta-pricing`

The rules by which Meta charges for the use of WhatsApp to the business that owns the number, and the day Luna read them. It carries no monetary values: the rate table stays at Meta. Luna charges none of this.

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "readAt": "2026-10-07",
  "sourceUrl": "https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing",
  "aiProvidersUrl": "https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ai-providers",
  "rules": [
    {
      "key": "marketing_templates",
      "title": "Template de marketing",
      "text": "É sempre cobrado pela Meta, dentro ou fora da janela de 24 horas."
    }
  ]
}
```

**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 your own account

`GET /v1/account`

Returns the account behind the credential presented: identifier, name, whether the email has been confirmed, and when the account was created.

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

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "YOUR_NAME",
  "emailConfirmed": true,
  "createdAt": "YOUR_CREATEDAT",
  "operatorEmail": "YOUR_OPERATOREMAIL"
}
```

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

### Rename the account

`PATCH /v1/account`

Changes the account name, the same one GET /v1/account returns. Returns the account with the new name. Only the console session does this.

Authentication: API key. Required scope: `session:end`

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | O novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro. · 1 to 120 characters |

#### Code examples

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/account" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "YOUR_NAME"
}'
```

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "YOUR_NAME",
  "emailConfirmed": true,
  "createdAt": "YOUR_CREATEDAT",
  "operatorEmail": "YOUR_OPERATOREMAIL"
}
```

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

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

### See the account summary

`GET /v1/account/overview`

What the account needs to look at now (alerts, most serious first), the four first steps, and the numbers by connection state. Everything is decided by the API, so a home screen has nothing to calculate.

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

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "attention": [
    {
      "code": "number_credential_expiring",
      "severity": "warning",
      "title": "Autorização do cliente perto de vencer (+55 11 90000-0000)",
      "message": "A autorização que o seu cliente deu à Luna vence em até 14 dias. O número continua enviando até lá.",
      "solution": "Gere um link de reconexão com POST /v1/onboarding/links informando numberId e envie ao seu cliente.",
      "resource": {
        "type": "number",
        "id": "ed404df1-b420-4ed6-8743-ba1609892e0a"
      },
      "action": "reconnect_link",
      "actionUrl": null,
      "since": "2026-10-25T12:00:00.000Z"
    }
  ],
  "checklist": [
    {
      "key": "connect_number",
      "done": true,
      "doneAt": "2026-08-07T11:28:14.597Z"
    },
    {
      "key": "create_key",
      "done": true,
      "doneAt": "2026-08-07T12:10:44.201Z"
    },
    {
      "key": "add_webhook_endpoint",
      "done": true,
      "doneAt": "2026-08-08T09:00:00.000Z"
    },
    {
      "key": "send_message",
      "done": false,
      "doneAt": null
    }
  ],
  "numbers": {
    "total": 1,
    "byStatus": {
      "connected": 1,
      "connecting": 0,
      "action_required": 0,
      "disconnected": 0
    }
  }
}
```

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

## Status

Availability probes and the state of the platform. No authentication.

### Check whether the API is up

`GET /healthz`

Answers 200 while the process is running. It requires no authentication and touches neither database nor queue, because it probes the process and not its dependencies. A 200 here does not promise that message sending works.

Authentication: Public, no key

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/healthz"
```

#### Responses

**200**: Success.

### See whether Luna is receiving and delivering

`GET /status`

Answers 200 with the platform state, measured every few minutes by a synthetic message that enters through the same door Meta uses and has to reach a destination over HTTPS. It requires no authentication and reveals no account data. When there is no recent check yet, the state is unknown, never ok.

Authentication: Public, no key

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/status"
```

#### Responses

**200**: Success.

```json
{
  "status": "ok",
  "checkedAt": "YOUR_CHECKEDAT",
  "components": {
    "ingestion": "ok",
    "delivery": "ok",
    "partitions": "ok"
  },
  "since": "YOUR_SINCE"
}
```

### Introduce the API

`GET /`

Answers 200 with the API name and the addresses of the documentation and of the OpenAPI specification. It requires no authentication and touches neither database nor queue.

Authentication: Public, no key

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/"
```

#### Responses

**200**: Success.

```json
{
  "name": "YOUR_NAME",
  "docs": "YOUR_DOCS",
  "openapi": "YOUR_OPENAPI"
}
```

## Console and public pages

Routes the Luna console and the public connection link page use: sign-up, login, session and completion of the flow. You normally do not need them. They exist here because the console is a client of this same API, with no privileged route.

### Read the connect link (customer page)

`GET /v1/public/onboarding-links/{token}`

For the page your customer opens. Returns the name of the account that asked for the connection, the link status, and the public identifiers of the Meta app that the connection window uses. Nothing else about your account comes out here.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-get-v1-public-onboarding-links-token

#### Path parameters

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

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN"
```

#### Responses

**200**: Success.

```json
{
  "accountName": "YOUR_ACCOUNTNAME",
  "displayName": "YOUR_DISPLAYNAME",
  "status": "open",
  "expiresAt": "YOUR_EXPIRESAT",
  "metaAppId": "YOUR_METAAPPID",
  "metaConfigId": "YOUR_METACONFIGID",
  "sdkVersion": "YOUR_SDKVERSION",
  "redirectUrl": "YOUR_REDIRECTURL",
  "reconnect": true
}
```

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

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

### Open the connection session through the link

`POST /v1/public/onboarding-links/{token}/sessions`

Opens the session that Meta's window fills in, for the account that owns the link. It is the same opening as POST /v1/onboarding/sessions, through the token's door. On a reconnection link (created with numberId), the session is born bound to the number's account, as in POST /v1/onboarding/reconnect.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions

#### Path parameters

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

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions"
```

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

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

**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": "account_at_capacity",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "A conta que pediu esta conexão atingiu o máximo de números. Avise quem enviou este link: assim que ela abrir uma vaga, ele poderá enviar um link novo."
}
```

**410**: The connect link expired or was already used. The error field says which of the two.

```json
{
  "error": "link_expired",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este link venceu. Peça um novo a quem enviou este."
}
```

**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 through the link

`POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/complete`

Exchanges the code from Meta's window for access to the customer's account. It is the same completion as POST /v1/onboarding/sessions/{id}/complete, through the token's door, and the same warning holds: the code lasts 30 seconds, so call it the moment it arrives.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions-sessionid-complete

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes |  |
| `sessionId` | `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/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/complete" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "YOUR_CODE",
  "csrfState": "YOUR_CSRFSTATE"
}'
```

#### Responses

**200**: Success.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "terminal": true,
  "motivo": "YOUR_MOTIVO",
  "podeRetentar": true,
  "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "returnUrl": "YOUR_RETURNURL"
}
```

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

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

**410**: The connect link expired or was already used. The error field says which of the two.

```json
{
  "error": "link_used",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este."
}
```

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

### Report an abandoned or failed flow through the link

`POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon`

Telemetry about what happened in Meta's window when the customer did not complete. It is the same report as POST /v1/onboarding/sessions/{id}/abandon, through the token's door, and it only applies to a session opened by this same link.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/saas-with-n-customers#rota-post-v1-public-onboarding-links-token-sessions-sessionid-abandon

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes |  |
| `sessionId` | `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/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/abandon" \
  -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."
    }
  ]
}
```

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

### Create an account

`POST /v1/operators/signup`

Creates the account and its first operator, in a single call and with no credential.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-signup

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | up to 254 characters |
| `password` | `string` | yes | 12 to 512 characters |
| `tenantName` | `string` | yes | 1 to 120 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/signup" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br",
  "password": "YOUR_PASSWORD",
  "tenantName": "YOUR_TENANTNAME"
}'
```

#### Responses

**201**: Created.

```json
{
  "nextStep": "login"
}
```

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

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

### Confirm an account's email

`GET /v1/operators/confirm`

Destination of the link sent by email when the account is created. It answers with a redirect to the console, and not with JSON, because a person in a browser is what opens it.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-operators-confirm

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | no |  |

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/operators/confirm"
```

#### Responses

**200**: Success.

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

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

### Ask for a password reset

`POST /v1/operators/password/forgot`

Asks for a link to choose a new password. It takes only the account email.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-password-forgot

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | up to 254 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br"
}'
```

#### Responses

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

```json
{
  "accepted": true
}
```

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

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

### Choose a new password

`POST /v1/operators/password/reset`

Changes the operator's password from the token in the link sent by email, and answers 204.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-password-reset

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | up to 512 characters |
| `password` | `string` | yes | 12 to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "YOUR_TOKEN",
  "password": "YOUR_PASSWORD"
}'
```

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

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

### Check the reset link

`POST /v1/operators/password/reset/check`

Answers 204 when the link token is still valid and 400 when it is not, without consuming it. Lets the screen warn before the person types the new password.

Authentication: Public, no key

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string` | yes | up to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset/check" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "YOUR_TOKEN"
}'
```

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

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

### Read the password rule

`GET /v1/public/password-policy`

The minimum length of an operator password, the same at signup, reset and change. It asks for no credential.

Authentication: Public, no key

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/password-policy"
```

#### Responses

**200**: Success.

```json
{
  "minLength": 12
}
```

**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 password

`POST /v1/operators/password/change`

Changes the password of the operator behind the presented session, checking the current password, and answers 204. The operator's other sessions are ended and the presented one stays valid. A wrong current password, or a credential with no operator (an integration key), answers 401.

Authentication: API key. Required scope: `session:elevate`

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currentPassword` | `string` | yes | A senha de hoje do operador da sessão. · up to 512 characters |
| `newPassword` | `string` | yes | A senha nova, pela mesma regra do cadastro (GET /v1/public/password-policy diz o mínimo). · 12 to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/change" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "currentPassword": "YOUR_CURRENTPASSWORD",
  "newPassword": "YOUR_NEWPASSWORD"
}'
```

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

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

### Resend the confirmation email

`POST /v1/operators/confirmation/resend`

Sends the confirmation link again to the email of the operator behind the session, and invalidates the previous link if it had not been opened. The new link is valid for seven days and is accepted a single time.

Authentication: API key. Required scope: `session:end`

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-confirmation-resend

#### Code examples

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

#### Responses

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

```json
{
  "emailConfirmed": true
}
```

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

### Authenticate an operator

`POST /v1/operators/login`

Exchanges email and password for an eight hour session credential, used by the web console.

Authentication: Public, no key

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-login

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | 1 to 254 characters |
| `password` | `string` | yes | 1 to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br",
  "password": "YOUR_PASSWORD"
}'
```

#### Responses

**200**: Success.

```json
{
  "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "operatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "YOUR_TOKEN",
  "expiresAt": "YOUR_EXPIRESAT",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

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

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

### Re-authenticate for a sensitive action

`POST /v1/operators/step-up`

Confirms the password of the operator behind the session presented, and opens a two hour window in which that same session can create and revoke API keys.

Authentication: API key. Required scope: `session:elevate`

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-post-v1-operators-step-up

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | `string` | yes | 1 to 512 characters |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/step-up" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "YOUR_PASSWORD"
}'
```

#### Responses

**200**: Success.

```json
{
  "elevatedUntil": "YOUR_ELEVATEDUNTIL",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

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

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

### Read the presented session

`GET /v1/operators/session`

When the presented credential expires, until when the elevation opened by POST /v1/operators/step-up lasts (null with no elevation or with the window closed) and the scopes it has now. It reads only the credential itself: the identifier comes from authentication and never from the path.

Authentication: API key. Required scope: `session:end`

#### Code examples

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

#### Responses

**200**: Success.

```json
{
  "expiresAt": "2026-11-03T20:00:00.000Z",
  "elevatedUntil": "2026-11-03T14:30:00.000Z",
  "scopes": [
    "numbers:read",
    "session:end",
    "session:elevate",
    "keys:write"
  ]
}
```

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

### End the session

`POST /v1/operators/logout`

Revokes the credential presented, and only it. The identifier comes from the authentication itself and never from the body, so this route cannot revoke someone else's key.

Authentication: API key. Required scope: `session:end`

#### Code examples

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

#### Responses

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

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

## Webhook events

Luna POSTs the event to the endpoint you registered, with the body as application/json and the signature header. Answer 2xx to confirm; any other answer, or none, counts as a failure and is repeated by the retry policy. Verify the signature over the raw body before trusting the content.

`x-luna-signature`: The delivery signature: t=<seconds since 1970>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> with the endpoint secret. During a secret rotation the header carries two v1= values, and one matching is enough. Reject deliveries whose t is more than 300 seconds from your clock.

### Message received

`message.received`

A contact wrote to one of your numbers. It carries the text, and the content when the message is of another type (media, tapped button, location, contacts, reaction).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"message.received"` | yes |  |
| `message` | `object` | yes | Uma mensagem que chegou de um interlocutor. Além de wamid, wa_id (que pode ser nulo), user_id, parent_user_id, username, type e text, ela traz o conteúdo que o tipo carrega (mídia, botão ou item clicado, resposta de Flow, localização, contatos, reação, pedido, edição, apagamento, aviso de tipo sem suporte), a citação, o anúncio de origem e o nome de perfil. Os nomes dentro desses campos são os da Meta. Todo campo está sempre presente, e é nulo quando não se aplica. |
| `message.id` | `string (uuid)` | yes | O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem. |
| `message.wamid` | `string` | yes | O identificador da mensagem na Meta. |
| `message.wa_id` | `string \| null` | yes | O identificador do interlocutor na Meta, em E.164 sem o sinal de mais: o telefone. Nulo quando o usuário escreveu sem que o telefone apareça (nome de usuário adotado): use user_id. |
| `message.user_id` | `string \| null` | yes | O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor. |
| `message.parent_user_id` | `string \| null` | yes | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. |
| `message.username` | `string \| null` | yes | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. |
| `message.type` | `string` | yes | O tipo da mensagem, no vocabulário da Meta. |
| `message.text` | `string \| null` | yes | O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title. |
| `message.profile_name` | `string \| null` | yes | O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou. |
| `message.media` | `object \| null` | yes |  |
| `message.media.mime_type` | `string \| null` | yes | O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu. |
| `message.media.sha256` | `string \| null` | yes | O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type. |
| `message.media.caption` | `string \| null` | yes | A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma. |
| `message.media.filename` | `string \| null` | yes | O nome do arquivo. Só documento tem. |
| `message.media.voice` | `boolean \| null` | yes | Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem. |
| `message.media.animated` | `boolean \| null` | yes | Verdadeiro quando a figurinha é animada. Só figurinha tem. |
| `message.media.url` | `string \| null` | yes | Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo. |
| `message.interactive` | `object \| null` | yes | A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu. |
| `message.interactive.type` | `string \| null` | yes | Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow). |
| `message.interactive.id` | `string \| null` | yes | O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply. |
| `message.interactive.title` | `string \| null` | yes | O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply. |
| `message.interactive.description` | `string \| null` | yes | A descrição do item da lista. Nula nos demais. |
| `message.interactive.name` | `string \| null` | yes | O nome do Flow. Só em nfm_reply. |
| `message.interactive.response_json` | `string \| null` | yes | As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply. |
| `message.button` | `object \| null` | yes | O clique num botão de resposta rápida de um template. |
| `message.button.payload` | `string \| null` | yes | O payload que você definiu no botão de resposta rápida do template. |
| `message.button.text` | `string \| null` | yes | O texto do botão. |
| `message.location` | `object \| null` | yes | A localização que o interlocutor compartilhou. |
| `message.location.latitude` | `number \| null` | yes | A latitude, em graus decimais. |
| `message.location.longitude` | `number \| null` | yes | A longitude, em graus decimais. |
| `message.location.name` | `string \| null` | yes | O nome do lugar, quando o interlocutor escolheu um. |
| `message.location.address` | `string \| null` | yes | O endereço, quando há. |
| `message.location.url` | `string \| null` | yes | O endereço web do lugar, quando há. |
| `message.contacts` | `array<object> \| null` | yes | Os cartões de contato que o interlocutor compartilhou. |
| `message.contacts[].name` | `object \| null` | yes | O nome do contato, nos campos da Meta. |
| `message.contacts[].name.formatted_name` | `string \| null` | yes |  |
| `message.contacts[].name.first_name` | `string \| null` | yes |  |
| `message.contacts[].name.last_name` | `string \| null` | yes |  |
| `message.contacts[].name.middle_name` | `string \| null` | yes |  |
| `message.contacts[].name.prefix` | `string \| null` | yes |  |
| `message.contacts[].name.suffix` | `string \| null` | yes |  |
| `message.contacts[].phones` | `array<object> \| null` | yes | Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp. |
| `message.contacts[].phones[].phone` | `string \| null` | yes |  |
| `message.contacts[].phones[].wa_id` | `string \| null` | yes |  |
| `message.contacts[].phones[].type` | `string \| null` | yes |  |
| `message.contacts[].emails` | `array<object> \| null` | yes | Os e-mails do contato. |
| `message.contacts[].emails[].email` | `string \| null` | yes |  |
| `message.contacts[].emails[].type` | `string \| null` | yes |  |
| `message.contacts[].org` | `object \| null` | yes | A organização do contato. |
| `message.contacts[].org.company` | `string \| null` | yes |  |
| `message.contacts[].org.department` | `string \| null` | yes |  |
| `message.contacts[].org.title` | `string \| null` | yes |  |
| `message.reaction` | `object \| null` | yes | A reação a uma mensagem, ou a retirada dela. |
| `message.reaction.wamid` | `string \| null` | yes | O wamid da mensagem que recebeu a reação. |
| `message.reaction.emoji` | `string \| null` | yes | O emoji. Nulo quando o interlocutor retirou a reação. |
| `message.context` | `object \| null` | yes | A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada. |
| `message.context.wamid` | `string \| null` | yes | O wamid da mensagem que o interlocutor citou ao responder. |
| `message.context.from` | `string \| null` | yes | Quem enviou a mensagem citada. |
| `message.context.forwarded` | `boolean \| null` | yes | Verdadeiro quando a mensagem foi encaminhada. |
| `message.context.frequently_forwarded` | `boolean \| null` | yes | Verdadeiro quando a mensagem foi encaminhada muitas vezes. |
| `message.referral` | `object \| null` | yes | O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever. |
| `message.referral.source_type` | `string \| null` | yes | A origem do clique, como ad ou post. |
| `message.referral.source_id` | `string \| null` | yes | O identificador do anúncio ou da publicação na Meta. |
| `message.referral.source_url` | `string \| null` | yes | O endereço do anúncio ou da publicação. |
| `message.referral.headline` | `string \| null` | yes | O título do anúncio. |
| `message.referral.body` | `string \| null` | yes | O texto do anúncio. |
| `message.referral.media_type` | `string \| null` | yes | O tipo da mídia do anúncio, como image ou video. |
| `message.referral.ctwa_clid` | `string \| null` | yes | O identificador do clique, para atribuição de conversão. |
| `message.unsupported` | `object \| null` | yes | Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso". |
| `message.unsupported.code` | `integer \| null` | yes | O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte"). |
| `message.unsupported.title` | `string \| null` | yes | O título do erro, como a Meta o mandou. |
| `message.unsupported.details` | `string \| null` | yes | O detalhe do erro, como a Meta o mandou. |
| `message.edit` | `object \| null` | yes | Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit). |
| `message.edit.wamid` | `string \| null` | yes | O wamid da mensagem que foi editada. |
| `message.edit.type` | `string \| null` | yes | O tipo do conteúdo novo, como text. |
| `message.edit.text` | `string \| null` | yes | O texto novo, quando o conteúdo novo é texto. |
| `message.revoke` | `object \| null` | yes | Presente quando o interlocutor apagou uma mensagem para todos (type é revoke). |
| `message.revoke.wamid` | `string \| null` | yes | O wamid da mensagem que o interlocutor apagou para todos. |
| `message.order` | `object \| null` | yes | O pedido que o interlocutor montou num catálogo e enviou (type é order). |
| `message.order.catalog_id` | `string \| null` | yes | O catálogo de onde veio o pedido. |
| `message.order.text` | `string \| null` | yes | O texto que o interlocutor escreveu junto com o pedido. |
| `message.order.items` | `array<object> \| null` | yes | Os itens do pedido. |
| `message.order.items[].product_retailer_id` | `string \| null` | yes | O identificador do produto no seu catálogo. |
| `message.order.items[].quantity` | `string \| null` | yes | A quantidade pedida, como a Meta mandou. |
| `message.order.items[].item_price` | `string \| null` | yes | O preço unitário, como a Meta mandou. |
| `message.order.items[].currency` | `string \| null` | yes | A moeda do preço. |

```json
{
  "version": "2026-11-10",
  "event_id": "1fd66b6f86489c36c3552f14dbf49f50df6b2d946c259f7b0eaa0ef88f58adb5",
  "event_type": "message.received",
  "occurred_at": "2026-10-06T14:05:40.120Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "7d1c4b8e-2a3f-4e5d-9c6b-1f0a2b3c4d5e",
    "wamid": "wamid.EXAMPLE_BUTTON_CLICK",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "interactive",
    "text": null,
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": {
      "type": "button_reply",
      "id": "rastrear",
      "title": "Rastrear pedido",
      "description": null,
      "name": null,
      "response_json": null
    },
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": {
      "wamid": "wamid.EXAMPLE_MESSAGE_WITH_BUTTONS",
      "from": "5511900000001",
      "forwarded": null,
      "frequently_forwarded": null
    },
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
```

```json
{
  "version": "2026-11-10",
  "event_id": "0ab56cecd18b825ebeb4548219cb8fe392fec9e56301e52be1086f3c734ace86",
  "event_type": "message.received",
  "occurred_at": "2026-10-06T14:07:03.900Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "4c9e2d1a-8b7f-4a6c-b5d3-0e1f2a3b4c5d",
    "wamid": "wamid.EXAMPLE_IMAGE",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "image",
    "text": null,
    "profile_name": "Maria Souza",
    "media": {
      "mime_type": "image/jpeg",
      "sha256": "EXAMPLE_SHA256_OF_THE_FILE",
      "caption": "A nota fiscal do pedido",
      "filename": null,
      "voice": null,
      "animated": null,
      "url": "https://api.lunahia.com.br/v1/media/6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b.EXEMPLO_DO_SEGREDO_DE_43_CARACTERES_AAAAAAAA"
    },
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
```

```json
{
  "version": "2026-11-10",
  "event_id": "a2f4909b0fd2db8ab8b1bfe4e16487f49b86113e27bf8c3c9d10a2d0fefebc72",
  "event_type": "message.received",
  "occurred_at": "2026-10-06T14:02:11.482Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51",
    "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "text",
    "text": "Oi! Queria saber o status do meu pedido.",
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
```

```json
{
  "version": "2026-11-10",
  "event_id": "e2f81dd079e4419dac363779655be694a25cc502b7646be51cdac4b0cfc276fb",
  "event_type": "message.received",
  "occurred_at": "2026-11-03T14:02:11.482Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "c8a1e5d2-6f3b-4a7c-9e0d-1b2c3d4e5f60",
    "wamid": "wamid.EXAMPLE_NO_PHONE",
    "wa_id": null,
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": "mariasouza",
    "type": "text",
    "text": "Oi! Queria saber o status do meu pedido.",
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
```

```json
{
  "version": "2026-11-10",
  "event_id": "1eaa360e693d1a7366e66ba81d7bee362a56c2b4f4ef4854e43ad35861bd7ae1",
  "event_type": "message.received",
  "occurred_at": "2026-11-04T14:10:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "f3a8c1d2-5b6e-4f70-8a9b-0c1d2e3f4a5b",
    "wamid": "wamid.EXAMPLE_ORDER",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "order",
    "text": null,
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": {
      "catalog_id": "EXAMPLE_CATALOG_ID",
      "text": "Quero estes dois, por favor.",
      "items": [
        {
          "product_retailer_id": "sku-001",
          "quantity": "2",
          "item_price": "49.90",
          "currency": "BRL"
        },
        {
          "product_retailer_id": "sku-002",
          "quantity": "1",
          "item_price": "15.00",
          "currency": "BRL"
        }
      ]
    }
  }
}
```

```json
{
  "version": "2026-11-10",
  "event_id": "b9714a025db0a22bd3a63f9dfd9aa52aed7ddcae4efde825dfb2fa41e1736dd2",
  "event_type": "message.received",
  "occurred_at": "2026-11-04T14:12:30.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "a4b9d2e3-6c7f-4081-9bac-1d2e3f4a5b6c",
    "wamid": "wamid.EXAMPLE_FLOW_REPLY",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "interactive",
    "text": null,
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": {
      "type": "nfm_reply",
      "id": null,
      "title": null,
      "description": null,
      "name": "flow",
      "response_json": "{\"flow_token\":\"EXAMPLE_FLOW_TOKEN\",\"nome\":\"Maria Souza\",\"data\":\"2026-11-10\"}"
    },
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
```

### State of a message you sent

`message.status`

A message you sent changed state: sent, delivered, read or failed. On failed, the event carries the error. On sent and on one of delivered and read, it carries the pricing: the cost Meta applied to the message, with its names.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"message.status"` | yes |  |
| `message` | `object` | yes | Uma mudança de estado de uma mensagem que você enviou. |
| `message.id` | `string (uuid) \| null` | yes | O identificador da mensagem na Luna, o mesmo que POST /v1/messages devolveu quando você a enviou. Nulo quando o status é de uma mensagem que a Luna não conhece. |
| `message.wamid` | `string \| null` | yes | O identificador da mensagem na Meta. Nulo quando a Meta recusou o envio antes de aceitar a mensagem, caso em que ela nunca teve identificador: use id para correlacionar. |
| `message.wa_id` | `string \| null` | yes | O identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id. |
| `message.user_id` | `string \| null` | yes | O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor. |
| `message.parent_user_id` | `string \| null` | yes | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. |
| `message.username` | `string \| null` | yes | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. |
| `message.status` | `string` | yes | O estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer. |
| `message.error_code` | `integer \| null` | yes | O código de erro da Meta quando o estado é de falha. Nulo nos demais. |
| `message.error` | `object \| null` | yes | O primeiro erro que a Meta informou quando o estado é de falha, com code, title e message. Nulo nos demais estados. O detalhe completo, com a causa e a ação recomendada, está em GET /v1/messages/{id}. |
| `message.error.code` | `integer \| null` | yes | O código do erro, como a Meta o informou. |
| `message.error.title` | `string \| null` | yes | O título do erro, como a Meta o informou. |
| `message.error.message` | `string \| null` | yes | A descrição do erro, como a Meta a informou. |
| `message.pricing` | `object \| null` | yes | O custo que a Meta aplicou à mensagem. A Meta o informa só no estado sent e em um entre delivered e read, então nos demais estados vem nulo. Não é a fatura da Meta: a fonte da verdade é o painel de cobrança dela. |
| `message.pricing.billable` | `boolean \| null` | yes | Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos. |
| `message.pricing.pricing_model` | `string \| null` | yes | O modelo de preço da Meta, como ela informou (hoje PMP ou CBP). |
| `message.pricing.type` | `string \| null` | yes | O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer. |
| `message.pricing.category` | `string \| null` | yes | A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer. |
| `message.callback_data` | `string \| null` | yes | A etiqueta que você mandou em callbackData ao enviar a mensagem, devolvida como veio. Nulo quando o envio não trouxe etiqueta. Está em todos os estados da mensagem, inclusive failed. |

```json
{
  "version": "2026-11-10",
  "event_id": "464e089a80690f1792db6249678ddeced5ad5be0d46d95e2daa263779f7d92e5",
  "event_type": "message.status",
  "occurred_at": "2026-10-06T14:02:14.090Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "ae60f288-7565-4315-a440-3663e9c231e1",
    "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "status": "sent",
    "error_code": null,
    "error": null,
    "pricing": {
      "billable": false,
      "pricing_model": "PMP",
      "type": "free_customer_service",
      "category": "service"
    },
    "callback_data": "atendimento-8841"
  }
}
```

```json
{
  "version": "2026-11-10",
  "event_id": "6a79ec64bfea6acc67135d032067fd6261aa568c3aea35af7999790a7730cf69",
  "event_type": "message.status",
  "occurred_at": "2026-10-06T14:02:15.311Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "ae60f288-7565-4315-a440-3663e9c231e1",
    "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "status": "failed",
    "error_code": 131026,
    "error": {
      "code": 131026,
      "title": "Message undeliverable",
      "message": "Message undeliverable"
    },
    "pricing": null,
    "callback_data": null
  }
}
```

### Contact changed phone number or BSUID

`contact.identity_changed`

A contact changed phone number (user_changed_number) or BSUID (user_changed_user_id). Luna linked the new identity to the same conversation. Use previous_user_id and user_id to update the contact in your records.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"contact.identity_changed"` | yes |  |
| `contact` | `object` | yes | O contato trocou de telefone ou de BSUID. A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro. Todo campo está sempre presente, e é nulo quando não se aplica. |
| `contact.wamid` | `string` | yes | O identificador, na Meta, da mensagem de sistema que avisou a troca. |
| `contact.change_type` | `string` | yes | O que mudou, como a Meta informou: user_changed_number (o telefone) ou user_changed_user_id (o BSUID). Novos valores podem aparecer. |
| `contact.wa_id` | `string \| null` | yes | O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário). |
| `contact.user_id` | `string \| null` | yes | O BSUID do contato depois da troca, como a Meta mandou. |
| `contact.previous_user_id` | `string \| null` | yes | O BSUID de antes da troca, quando a Meta o informa. Use-o para achar o contato no seu cadastro. |
| `contact.parent_user_id` | `string \| null` | yes | O BSUID pai do contato depois da troca, quando a Meta o informa. |
| `contact.previous_parent_user_id` | `string \| null` | yes | O BSUID pai de antes da troca, quando a Meta o informa. |

```json
{
  "version": "2026-11-10",
  "event_id": "f73a65b1f155f86f94e0886ad29bac662a822fabf796b626cdf865c7060f0db9",
  "event_type": "contact.identity_changed",
  "occurred_at": "2026-11-03T15:20:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "contact": {
    "wamid": "wamid.EXAMPLE_IDENTITY_CHANGE",
    "change_type": "user_changed_user_id",
    "wa_id": null,
    "user_id": "BR.98765432109876543210",
    "previous_user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "previous_parent_user_id": null
  }
}
```

### Contact changed a preference

`contact.preferences_changed`

A contact changed a preference at Meta, today the one about receiving marketing messages: they asked to stop (for example value stop) or accepted again. The values arrive as Meta sent them. Luna does not block any send because of the notice: your system decides, and should stop sending marketing to whoever asked. It only arrives if the user_preferences field is subscribed on the Meta app.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"contact.preferences_changed"` | yes |  |
| `contact` | `object` | yes | Quem mudou a preferência. |
| `contact.wa_id` | `string \| null` | yes | O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário): use user_id. |
| `contact.user_id` | `string \| null` | yes | O BSUID do contato, como a Meta mandou. |
| `contact.parent_user_id` | `string \| null` | yes | O BSUID pai do contato, quando a Meta o informa. |
| `contact.username` | `string \| null` | yes | O nome de usuário do contato, quando ele adotou um. |
| `contact.profile_name` | `string \| null` | yes | O nome que o contato exibe no WhatsApp, quando a Meta o manda. |
| `preference` | `object` | yes | O que mudou. |
| `preference.category` | `string \| null` | yes | A categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer. |
| `preference.value` | `string \| null` | yes | O que o contato escolheu, como a Meta informou (por exemplo stop para parar de receber, resume para voltar). Novos valores podem aparecer. |
| `preference.detail` | `string \| null` | yes | O texto que a Meta mandou para explicar a mudança. |

```json
{
  "version": "2026-11-10",
  "event_id": "4236ccfb21e7cec359d1e1b5b5f3f8e65cb3e8a8db0fc86e4d95da037796e97c",
  "event_type": "contact.preferences_changed",
  "occurred_at": "2026-11-04T16:45:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "contact": {
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "profile_name": "Maria Souza"
  },
  "preference": {
    "category": "marketing_messages",
    "value": "stop",
    "detail": "User requested to stop marketing messages"
  }
}
```

### Events dropped by unavailability

`backlog.dropped`

Your endpoint was down for too long, and the platform dropped what piled up. It says how many events and for what period. The notice is not dropped along with them.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"backlog.dropped"` | yes |  |
| `backlog` | `object` | yes | Eventos que a plataforma descartou sem entregar, e que não serão reenviados. |
| `backlog.motivo` | `string` | yes | Qual limite foi atingido: idade, quando as mensagens ficaram velhas demais para serem acionáveis; volume, quando o acumulado deste endpoint passou do teto da plataforma. · Values: idade, volume |
| `backlog.quantidade` | `integer` | yes | Quantos eventos foram descartados nesta ocorrência. |
| `backlog.janela_inicio` | `string` | yes | O evento mais antigo descartado nesta ocorrência. |
| `backlog.janela_fim` | `string` | yes | O evento mais recente descartado nesta ocorrência. |

```json
{
  "version": "2026-11-10",
  "event_id": "f76937420c2e818b87ce9b6acc5cb192c059ed2e33cda23339d5cf650b762ce5",
  "event_type": "backlog.dropped",
  "occurred_at": "2026-10-06T14:30:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "backlog": {
    "motivo": "idade",
    "quantidade": 37,
    "janela_inicio": "2026-10-06T09:00:00.000Z",
    "janela_fim": "2026-10-06T14:30:00.000Z"
  }
}
```

### History import deadline approaching

`history_sync.deadline_approaching`

On a number connected in coexistence, the import of earlier conversations is still in progress and its deadline approaches. Once the deadline passes without completion, Meta disconnects the end business.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"history_sync.deadline_approaching"` | yes |  |
| `history_sync` | `object` | yes | A importação das conversas anteriores de um número em coexistência está em curso e o prazo dela se aproxima. O estado corrente, inclusive o progresso, está em GET /v1/numbers/{id}/health. |
| `history_sync.prazo` | `string` | yes | Até quando a importação precisa terminar, em UTC. É o mesmo instante que sincronizacaoPrazo devolve na rota de saúde do número. |

```json
{
  "version": "2026-11-10",
  "event_id": "d42ca56e44ef023d52b0a0739dcf3afb0d5054a8b84321c41e432ed6707b043f",
  "event_type": "history_sync.deadline_approaching",
  "occurred_at": "2026-10-07T03:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "history_sync": {
    "prazo": "2026-10-07T09:00:00.000Z"
  }
}
```

### Test event

`webhook.test`

The event POST /v1/webhooks/endpoints/{id}/test sends to your endpoint, so you can check the URL and the signature verification. It does not go through any number.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | yes | Sempre null neste tipo: o evento de teste não passa por nenhum número. |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `null` | yes | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"webhook.test"` | yes |  |
| `webhook_test` | `object` | yes | Um evento de teste, enviado porque você pediu em POST /v1/webhooks/endpoints/{id}/test. Ele nunca aparece se você não pediu, não tem número nem conversa, e serve para conferir a URL e a verificação da assinatura. |
| `webhook_test.endpoint_id` | `string (uuid)` | yes | O endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu. |

```json
{
  "version": "2026-11-10",
  "event_id": "6af3f85d8fedc8bb0f6d5bb6b4631e324574c539763c25cf113fd40db822cea8",
  "event_type": "webhook.test",
  "occurred_at": "2026-10-07T12:00:00.000Z",
  "phone_number_id": null,
  "number": null,
  "webhook_test": {
    "endpoint_id": "5c0e9a52-3a0e-4c3f-9f3e-0b3f6f1a2c77"
  }
}
```

### Reply sent from the phone app

`message.echo`

The business owner answered a customer from the WhatsApp Business app on the phone. It only occurs on a number connected in coexistence. message.wa_id is the recipient.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"message.echo"` | yes |  |
| `message` | `object` | yes | Uma mensagem que o dono do negócio escreveu pelo aplicativo WhatsApp Business do celular, num número conectado em coexistência. Só ocorre em número conectado em coexistência. É o sinal para um agente automatizado ficar quieto na conversa: um humano respondeu. A forma é a de message.received, e wa_id é o destinatário. Todo campo está sempre presente, e é nulo quando não se aplica. |
| `message.id` | `string (uuid)` | yes | O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem. |
| `message.wamid` | `string` | yes | O identificador da mensagem na Meta. |
| `message.wa_id` | `string \| null` | yes | O identificador do DESTINATÁRIO na Meta, em E.164 sem o sinal de mais: o cliente final para quem o dono do negócio escreveu. É a conversa onde o seu agente deve ficar quieto. Nulo quando a conversa é só de BSUID: use user_id. |
| `message.user_id` | `string \| null` | yes | O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor. |
| `message.parent_user_id` | `string \| null` | yes | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. |
| `message.username` | `string \| null` | yes | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. |
| `message.type` | `string` | yes | O tipo da mensagem, no vocabulário da Meta. |
| `message.text` | `string \| null` | yes | O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title. |
| `message.profile_name` | `string \| null` | yes | O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou. |
| `message.media` | `object \| null` | yes |  |
| `message.media.mime_type` | `string \| null` | yes | O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu. |
| `message.media.sha256` | `string \| null` | yes | O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type. |
| `message.media.caption` | `string \| null` | yes | A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma. |
| `message.media.filename` | `string \| null` | yes | O nome do arquivo. Só documento tem. |
| `message.media.voice` | `boolean \| null` | yes | Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem. |
| `message.media.animated` | `boolean \| null` | yes | Verdadeiro quando a figurinha é animada. Só figurinha tem. |
| `message.media.url` | `string \| null` | yes | Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo. |
| `message.interactive` | `object \| null` | yes | A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu. |
| `message.interactive.type` | `string \| null` | yes | Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow). |
| `message.interactive.id` | `string \| null` | yes | O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply. |
| `message.interactive.title` | `string \| null` | yes | O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply. |
| `message.interactive.description` | `string \| null` | yes | A descrição do item da lista. Nula nos demais. |
| `message.interactive.name` | `string \| null` | yes | O nome do Flow. Só em nfm_reply. |
| `message.interactive.response_json` | `string \| null` | yes | As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply. |
| `message.button` | `object \| null` | yes | O clique num botão de resposta rápida de um template. |
| `message.button.payload` | `string \| null` | yes | O payload que você definiu no botão de resposta rápida do template. |
| `message.button.text` | `string \| null` | yes | O texto do botão. |
| `message.location` | `object \| null` | yes | A localização que o interlocutor compartilhou. |
| `message.location.latitude` | `number \| null` | yes | A latitude, em graus decimais. |
| `message.location.longitude` | `number \| null` | yes | A longitude, em graus decimais. |
| `message.location.name` | `string \| null` | yes | O nome do lugar, quando o interlocutor escolheu um. |
| `message.location.address` | `string \| null` | yes | O endereço, quando há. |
| `message.location.url` | `string \| null` | yes | O endereço web do lugar, quando há. |
| `message.contacts` | `array<object> \| null` | yes | Os cartões de contato que o interlocutor compartilhou. |
| `message.contacts[].name` | `object \| null` | yes | O nome do contato, nos campos da Meta. |
| `message.contacts[].name.formatted_name` | `string \| null` | yes |  |
| `message.contacts[].name.first_name` | `string \| null` | yes |  |
| `message.contacts[].name.last_name` | `string \| null` | yes |  |
| `message.contacts[].name.middle_name` | `string \| null` | yes |  |
| `message.contacts[].name.prefix` | `string \| null` | yes |  |
| `message.contacts[].name.suffix` | `string \| null` | yes |  |
| `message.contacts[].phones` | `array<object> \| null` | yes | Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp. |
| `message.contacts[].phones[].phone` | `string \| null` | yes |  |
| `message.contacts[].phones[].wa_id` | `string \| null` | yes |  |
| `message.contacts[].phones[].type` | `string \| null` | yes |  |
| `message.contacts[].emails` | `array<object> \| null` | yes | Os e-mails do contato. |
| `message.contacts[].emails[].email` | `string \| null` | yes |  |
| `message.contacts[].emails[].type` | `string \| null` | yes |  |
| `message.contacts[].org` | `object \| null` | yes | A organização do contato. |
| `message.contacts[].org.company` | `string \| null` | yes |  |
| `message.contacts[].org.department` | `string \| null` | yes |  |
| `message.contacts[].org.title` | `string \| null` | yes |  |
| `message.reaction` | `object \| null` | yes | A reação a uma mensagem, ou a retirada dela. |
| `message.reaction.wamid` | `string \| null` | yes | O wamid da mensagem que recebeu a reação. |
| `message.reaction.emoji` | `string \| null` | yes | O emoji. Nulo quando o interlocutor retirou a reação. |
| `message.context` | `object \| null` | yes | A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada. |
| `message.context.wamid` | `string \| null` | yes | O wamid da mensagem que o interlocutor citou ao responder. |
| `message.context.from` | `string \| null` | yes | Quem enviou a mensagem citada. |
| `message.context.forwarded` | `boolean \| null` | yes | Verdadeiro quando a mensagem foi encaminhada. |
| `message.context.frequently_forwarded` | `boolean \| null` | yes | Verdadeiro quando a mensagem foi encaminhada muitas vezes. |
| `message.referral` | `object \| null` | yes | O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever. |
| `message.referral.source_type` | `string \| null` | yes | A origem do clique, como ad ou post. |
| `message.referral.source_id` | `string \| null` | yes | O identificador do anúncio ou da publicação na Meta. |
| `message.referral.source_url` | `string \| null` | yes | O endereço do anúncio ou da publicação. |
| `message.referral.headline` | `string \| null` | yes | O título do anúncio. |
| `message.referral.body` | `string \| null` | yes | O texto do anúncio. |
| `message.referral.media_type` | `string \| null` | yes | O tipo da mídia do anúncio, como image ou video. |
| `message.referral.ctwa_clid` | `string \| null` | yes | O identificador do clique, para atribuição de conversão. |
| `message.unsupported` | `object \| null` | yes | Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso". |
| `message.unsupported.code` | `integer \| null` | yes | O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte"). |
| `message.unsupported.title` | `string \| null` | yes | O título do erro, como a Meta o mandou. |
| `message.unsupported.details` | `string \| null` | yes | O detalhe do erro, como a Meta o mandou. |
| `message.edit` | `object \| null` | yes | Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit). |
| `message.edit.wamid` | `string \| null` | yes | O wamid da mensagem que foi editada. |
| `message.edit.type` | `string \| null` | yes | O tipo do conteúdo novo, como text. |
| `message.edit.text` | `string \| null` | yes | O texto novo, quando o conteúdo novo é texto. |
| `message.revoke` | `object \| null` | yes | Presente quando o interlocutor apagou uma mensagem para todos (type é revoke). |
| `message.revoke.wamid` | `string \| null` | yes | O wamid da mensagem que o interlocutor apagou para todos. |
| `message.order` | `object \| null` | yes | O pedido que o interlocutor montou num catálogo e enviou (type é order). |
| `message.order.catalog_id` | `string \| null` | yes | O catálogo de onde veio o pedido. |
| `message.order.text` | `string \| null` | yes | O texto que o interlocutor escreveu junto com o pedido. |
| `message.order.items` | `array<object> \| null` | yes | Os itens do pedido. |
| `message.order.items[].product_retailer_id` | `string \| null` | yes | O identificador do produto no seu catálogo. |
| `message.order.items[].quantity` | `string \| null` | yes | A quantidade pedida, como a Meta mandou. |
| `message.order.items[].item_price` | `string \| null` | yes | O preço unitário, como a Meta mandou. |
| `message.order.items[].currency` | `string \| null` | yes | A moeda do preço. |

```json
{
  "version": "2026-11-10",
  "event_id": "01b53d46e858f6ab6c89e183ef9509d703f665f6cfe2eb1d6bb185df56224d88",
  "event_type": "message.echo",
  "occurred_at": "2026-10-07T13:02:30.250Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "9a3e6b14-5c2d-4f81-b7a0-2d8e1c4f6a93",
    "wamid": "wamid.EXAMPLE_ECHO",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "text",
    "text": "Oi, Maria! Já separei o seu pedido, sai hoje.",
    "profile_name": null,
    "media": null,
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
```

### A template changed state

`template.status`

Meta approved, rejected, paused or disabled a template, and the reason comes along when there is one. It has no number and no message.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | yes | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `null` | yes | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"template.status"` | yes |  |
| `template` | `object` | yes | O estado de um template mudou na Meta: aprovado, rejeitado, pausado, desativado ou outro. Não tem número nem conversa, porque o template pertence à conta de negócio. |
| `template.id` | `string (uuid)` | yes | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. |
| `template.name` | `string` | yes | O nome do template. |
| `template.language` | `string` | yes | O idioma do template, no código da Meta. |
| `template.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. |
| `template.external_id` | `string \| null` | yes | O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts). |
| `template.status` | `string` | yes | O novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer. |
| `template.category` | `string` | yes | A categoria do template, no vocabulário da Meta. |
| `template.reason` | `string \| null` | yes | O motivo que a Meta informou para a rejeição ou a pausa. Nulo quando ela não informa um, como nas aprovações. |

```json
{
  "version": "2026-11-10",
  "event_id": "821d41ec2c33a28abe8a0baf97db034baaef1dbe511a6e546a37eca4ad565c65",
  "event_type": "template.status",
  "occurred_at": "2026-10-07T13:20:00.000Z",
  "phone_number_id": null,
  "number": null,
  "template": {
    "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
    "name": "confirmacao_de_pedido",
    "language": "pt_BR",
    "waba_id": "102290129340398",
    "external_id": "cliente-8841",
    "status": "REJECTED",
    "category": "UTILITY",
    "reason": "INVALID_FORMAT"
  }
}
```

### Number connected

`number.connected`

A number finished connecting and is registered on the Cloud API. It is the signal that your customer completed the connection you opened with the connect link, and it carries their externalId.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão: você não precisa consultar a lista de números para descobrir. Para saber se o envio já está liberado, leia o campo ready de GET /v1/numbers/{id}. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. |
| `number.coexistence` | `boolean` | yes | true quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo do celular. Pode ser false no instante da conexão e passar a true depois. O estado corrente está no campo coexistence de GET /v1/numbers/{id}. |
| `event_type` | `"number.connected"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "458470a340db14358f03ac02fde7e3839cb6887f3071c06c57a3d9d456621996",
  "event_type": "number.connected",
  "occurred_at": "2026-10-07T13:45:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "waba_id": "102290129340398",
    "coexistence": false
  }
}
```

### Number waiting for a payment method at Meta

`number.payment_required`

Meta refused a send from this number for lack of a payment method on the business that owns the account (error 131042). It is sent once, when the state begins, and not for every refused message. The account owner fixes it in Meta’s WhatsApp Manager: Luna does not intermediate that payment. The Payment at Meta guide explains what to tell your customer.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). O número continua conectado e os eventos de entrada seguem chegando, mas os envios são recusados até o dono da conta cadastrar ou regularizar o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. O evento sai uma vez ao entrar no estado, e não a cada mensagem recusada: as mensagens recusadas chegam como message.status com status failed. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.awaiting_payment_since` | `string` | yes | Quando a Meta recusou o primeiro envio por falta de método de pagamento. É o mesmo valor que GET /v1/numbers/{id} devolve em awaitingPaymentSince enquanto a espera durar. |
| `event_type` | `"number.payment_required"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "50a49cee4b216c529e3f7cdd0be525f8902ff6aff66439e004dfe34a0c979fcf",
  "event_type": "number.payment_required",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "awaiting_payment_since": "2026-10-13T12:00:00.000Z"
  }
}
```

### Number sending again after the payment wait

`number.payment_resolved`

A send from this number was accepted by Meta again after a wait for a payment method. It is the only signal that payment was fixed: Meta does not announce it and offers no lookup. Messages refused during the wait are not resent on their own.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | Um envio deste número voltou a ser aceito pela Meta depois de uma espera por método de pagamento. É o único sinal de que o pagamento foi regularizado: a Meta não avisa e não oferece consulta. As mensagens recusadas durante a espera não são reenviadas sozinhas; envie de novo o que ainda interessa. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `event_type` | `"number.payment_resolved"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "6a956161dd17bb975533e63286e811ae62b77b3350107945952b2e53f0a9d1e2",
  "event_type": "number.payment_resolved",
  "occurred_at": "2026-10-13T15:30:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841"
  }
}
```

### Account restricted by Meta

`account.restricted`

Meta restricted the number’s WhatsApp Business account. It carries Meta’s type, deadline and guidance in restrictions. The notice belongs to the account: one event goes out per connected number of it, all with the same waba_id. The account owner fixes it in WhatsApp Manager. The Account health guide covers each case.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"account.restricted"` | yes |  |
| `waba` | `object` | yes | A Meta restringiu a conta de WhatsApp Business deste número. O que a restrição impede depende do tipo: confira restrictions[].restriction_type e o prazo em expiration. A Luna não levanta restrição; quem resolve é o dono da conta, no WhatsApp Manager da Meta. A Meta não avisa quando uma restrição por prazo termina. |
| `waba.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `waba.number_id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `waba.restrictions` | `array<object>` | yes | As restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar. |
| `waba.restrictions[].restriction_type` | `string \| null` | yes | O tipo da restrição, no vocabulário da Meta. |
| `waba.restrictions[].expiration` | `string \| null` | yes | Quando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo. |
| `waba.restrictions[].remediation` | `string \| null` | yes | O que a Meta diz que resolve a restrição, quando informa. |

```json
{
  "version": "2026-11-10",
  "event_id": "d3b1b97cb8b69ac0bf9db087b5200febbea3dcbcc8d0a4108913592b51fdaf29",
  "event_type": "account.restricted",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "waba": {
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "restrictions": [
      {
        "restriction_type": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2026-11-13T12:00:00Z",
        "remediation": null
      }
    ]
  }
}
```

### Policy violation on the account

`account.violation`

Meta recorded a policy violation on the number’s WhatsApp Business account. It is a warning: the account can be restricted or disabled if the violation is not handled. One event goes out per number of the account.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"account.violation"` | yes |  |
| `waba` | `object` | yes | A Meta registrou uma violação de política na conta de WhatsApp Business deste número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. O dono da conta lê os detalhes no WhatsApp Manager da Meta. |
| `waba.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `waba.number_id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `waba.violation_type` | `string \| null` | yes | O tipo da violação, no vocabulário da Meta. |

```json
{
  "version": "2026-11-10",
  "event_id": "a2fa828795bf24fd8e7460738c1a1e11a1bcd278fc09a0d238f92ba8c5994441",
  "event_type": "account.violation",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "waba": {
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "violation_type": "ALCOHOL_VIOLATION"
  }
}
```

### Account disabled by Meta

`account.disabled`

Meta disabled the number’s WhatsApp Business account, and sends stop being accepted. Luna does not reinstate accounts: the owner asks Meta for a review. One event goes out per number of the account, and account.reinstated announces it if the account comes back.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"account.disabled"` | yes |  |
| `waba` | `object` | yes | A Meta desativou a conta de WhatsApp Business deste número. Os envios param de ser aceitos. A Luna não reativa conta: o dono dela pede a revisão à Meta, e o evento account.reinstated avisa se a conta voltar. |
| `waba.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `waba.number_id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `waba.ban_date` | `string \| null` | yes | A data da desativação, como a Meta informou. |

```json
{
  "version": "2026-11-10",
  "event_id": "b0308dcc1ab6324eaea0474f1bcdec28146d3a6eb62668a1425fb3a7d6aad778",
  "event_type": "account.disabled",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "waba": {
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "ban_date": "2026-10-13"
  }
}
```

### Account reinstated by Meta

`account.reinstated`

Meta reinstated the number’s WhatsApp Business account after a deactivation. One event goes out per number of the account.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"account.reinstated"` | yes |  |
| `waba` | `object` | yes | A Meta reativou a conta de WhatsApp Business deste número depois de uma desativação. |
| `waba.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `waba.number_id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `waba.ban_date` | `string \| null` | yes | A data informada pela Meta junto com a reativação, quando houver. |

```json
{
  "version": "2026-11-10",
  "event_id": "135a9c7b3f192a7cab5ea55f68e0a8113e8d8e80acaa0ae8dad7f20aaf61f2db",
  "event_type": "account.reinstated",
  "occurred_at": "2026-10-14T09:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "waba": {
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "ban_date": null
  }
}
```

### Another account notice from Meta

`account.update`

An account notice from Meta that Luna does not translate into a type of its own, with Meta’s raw event field (for example ACCOUNT_DELETED, ACCOUNT_RECONNECTED or VOLUME_BASED_PRICING_TIER_UPDATE). If you do not use it, ignore it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"account.update"` | yes |  |
| `waba` | `object` | yes | Um aviso de conta da Meta que a Luna não traduz em um tipo próprio. Chega com o event cru da Meta para que o seu sistema decida o que fazer com ele. Se você não usa, ignore. |
| `waba.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `waba.number_id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `waba.event` | `string` | yes | O campo event do aviso account_update da Meta, sem tradução: ACCOUNT_DELETED, ACCOUNT_RECONNECTED, VOLUME_BASED_PRICING_TIER_UPDATE, DISABLED_UPDATE com um estado que não é desativação nem reativação, e outros. Novos valores podem aparecer. |
| `waba.details` | `object` | yes | O restante do aviso da Meta, como ela mandou, sem o campo event. |

```json
{
  "version": "2026-11-10",
  "event_id": "f663ad9f077e865db5d29245db96fe579e9aaa487bdf2f9d91a6e535af3d7949",
  "event_type": "account.update",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "waba": {
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "event": "ACCOUNT_DELETED",
    "details": {}
  }
}
```

### Account limit changed

`account.limit_changed`

Meta changed the account limit: the messaging limit, which counts unique people outside the customer service window (TIER_250, TIER_2K, TIER_10K, TIER_100K or TIER_UNLIMITED), or the number ceiling. It is the granted ceiling, never how much was used. It holds for the whole portfolio, so one event goes out per number of the account.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"account.limit_changed"` | yes |  |
| `waba` | `object` | yes | A Meta mudou o limite desta conta. O limite é do portfólio de negócio, e vale para todos os números da conta. O valor corrente de cada número está em limiteDiarioDeConversas, em GET /v1/numbers. |
| `waba.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `waba.number_id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `waba.daily_conversation_limit` | `string \| null` | yes | O limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Conta pessoas únicas a quem o negócio escreve fora da janela de atendimento, e é do portfólio empresarial. É o teto concedido, e nunca quanto foi usado. Nulo quando o aviso mudou só o limite de números. |
| `waba.max_phone_numbers_per_waba` | `number \| null` | yes | Quantos números a Meta permite nesta conta. Nulo quando o aviso mudou só o limite de conversas. |

```json
{
  "version": "2026-11-10",
  "event_id": "a3bddf693de91539edaebb432d0d4f936b40822085cafa5c7864ae149756dbff",
  "event_type": "account.limit_changed",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "waba": {
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "daily_conversation_limit": "TIER_2K",
    "max_phone_numbers_per_waba": null
  }
}
```

### Number disconnected

`number.disconnected`

The number is no longer connected to Luna: the customer removed the app, Luna was removed as the account’s partner, the account’s link to Luna was ended, or you disconnected it with DELETE /v1/numbers/{id} (reason requested_by_tenant). It is the pair of number.connected. To come back, your customer connects again with a new connect link. The reason is in the reason field.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | O número deixou de estar conectado à Luna. É o par de number.connected. Os envios deste número não funcionam mais; para voltar, o seu cliente precisa conectar de novo, com um novo link de conexão. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `number.reason` | `string` | yes | O motivo da desconexão: requested_by_tenant (você desconectou o número com DELETE /v1/numbers/{id}), ou o aviso da Meta que a causou, PARTNER_APP_UNINSTALLED (o cliente removeu o aplicativo), PARTNER_REMOVED (a Luna foi removida como parceira da conta) ou ACCOUNT_OFFBOARDED (o vínculo da conta com a Luna foi encerrado). Novos valores podem aparecer. |
| `number.disconnection_reason` | `string \| null` | yes | O motivo que a Meta informou em disconnection_info, quando informa. |
| `number.initiated_by` | `string \| null` | yes | Quem iniciou a desconexão, como a Meta informou. |
| `event_type` | `"number.disconnected"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "0dfe4e31d4e40e4a5da6d3f42f0d44b660f67ce551b2a43966e5fb0390fcd741",
  "event_type": "number.disconnected",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "waba_id": "102290129340398",
    "reason": "PARTNER_APP_UNINSTALLED",
    "disconnection_reason": null,
    "initiated_by": null
  }
}
```

### Number quality changed

`number.quality_changed`

The number’s quality rating changed (GREEN, YELLOW, RED). Meta has no webhook for this: Luna checks quality periodically, so the event arrives with a delay of up to about an hour. The history is in GET /v1/numbers/{id}/health.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | A avaliação de qualidade do número mudou. A Meta não tem webhook para isso: a Luna confere a qualidade de cada número periodicamente, então o evento chega com atraso de até a cadência da conferência (cerca de uma hora). O histórico está em GET /v1/numbers/{id}/health. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `number.previous_quality_rating` | `string` | yes | A avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED. |
| `number.quality_rating` | `string` | yes | A avaliação de qualidade atual, no vocabulário da Meta. |
| `event_type` | `"number.quality_changed"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "cc81de4eb28ad6a80e39c6cca13eb4b6db12f223f3c1346552cbc24795bcdbbe",
  "event_type": "number.quality_changed",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "waba_id": "102290129340398",
    "previous_quality_rating": "GREEN",
    "quality_rating": "YELLOW"
  }
}
```

### Display name reviewed

`number.display_name_reviewed`

The review state of the number’s display name changed (status: approved, pending_review, declined, expired or none), for example from pending_review to approved or declined. name is the name the state refers to. Meta does not report the reason for a refusal in this query. Luna checks the name periodically, so the event arrives with a delay of up to about an hour. An approved name only takes effect after the number is registered again. The current state is in displayNameStatus, in GET /v1/numbers/{id}.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | O estado da revisão do nome de exibição do número mudou, por exemplo de pending_review para approved ou declined. A Luna confere o nome de cada número periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo; o estado corrente está em displayNameStatus, em GET /v1/numbers/{id}. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `number.status` | `string` | yes | O estado da revisão do nome de exibição, o mesmo de displayNameStatus em GET /v1/numbers/{id}: approved, pending_review, declined, expired ou none. Novos valores podem aparecer. |
| `number.name` | `string \| null` | yes | O nome a que o estado se refere: o nome pedido, quando há um pedido, senão o nome em uso. Nulo quando a Meta não informou. |
| `event_type` | `"number.display_name_reviewed"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "23fd01fabc59f4c9ffda20955726e7e3e19c6a05cf609197c8b3c0aef8405e76",
  "event_type": "number.display_name_reviewed",
  "occurred_at": "2026-11-04T14:20:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "waba_id": "102290129340398",
    "status": "declined",
    "name": "Clínica Sorriso Centro"
  }
}
```

### Customer authorization about to expire

`number.credential_expiring`

The authorization the customer gave Luna to operate the number expires within 14 days (credential_expires_at). To renew it, the customer reconnects: create a link with POST /v1/onboarding/links passing numberId and it opens the reconnection of this number directly, without counting a new number. It goes out once per expiry and per number of the account. An authorization issued without an expiry never produces this event.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | A autorização que o cliente deu à Luna para operar este número vence em até 14 dias. Para renovar, o seu cliente refaz a conexão: abra um link com POST /v1/onboarding/links informando numberId, e ele cai direto na reconexão deste número, sem contar um número novo. O evento sai uma vez por vencimento e por número, e não se repete a cada dia. Se a autorização foi emitida sem prazo, ele não sai nunca. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `number.credential_expires_at` | `string` | yes | Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. É o mesmo valor que GET /v1/business-accounts devolve em credentialExpiresAt. Depois dessa data a Meta recusa as chamadas da Luna nesta conta, e o número para de enviar e de receber. |
| `event_type` | `"number.credential_expiring"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "33b03111fe7f1f225626ece55b50955389e78742a6b99059f05be056ce2b2260",
  "event_type": "number.credential_expiring",
  "occurred_at": "2026-11-21T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "waba_id": "102290129340398",
    "credential_expires_at": "2026-12-05T12:00:00.000Z"
  }
}
```

### Alert from Meta about the account

`account.alert`

Meta sent an alert about the number’s WhatsApp Business account (the account_alerts field), for example a denied limit increase or a lost profile picture. The fields arrive as Meta sent them, untranslated. The alert belongs to the account: one event goes out per connected number of it, all with the same waba_id.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"account.alert"` | yes |  |
| `waba` | `object` | yes | A Meta mandou um alerta sobre a conta de WhatsApp Business deste número (o campo account_alerts). Os campos chegam como a Meta mandou, sem tradução. O alerta é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. Quem resolve é o dono da conta, no WhatsApp Manager da Meta. |
| `waba.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. |
| `waba.number_id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `waba.entity_type` | `string \| null` | yes | A que o alerta se refere, como a Meta informou (por exemplo a conta, o portfólio ou um número). |
| `waba.entity_id` | `string \| null` | yes | O identificador, na Meta, do que o alerta cita. |
| `waba.alert_severity` | `string \| null` | yes | A gravidade que a Meta atribuiu ao alerta, no vocabulário dela. |
| `waba.alert_status` | `string \| null` | yes | Se o alerta está ativo ou foi resolvido, no vocabulário da Meta. |
| `waba.alert_type` | `string \| null` | yes | O tipo do alerta, no vocabulário da Meta: por exemplo INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED, INCREASED_CAPABILITIES_ELIGIBILITY_FAILED, INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO ou PROFILE_PICTURE_LOST. Novos valores podem aparecer. |
| `waba.alert_description` | `string \| null` | yes | A descrição do alerta, em texto, como a Meta mandou. |
| `waba.details` | `object` | yes | O restante do alerta, como a Meta mandou, para o que a Luna ainda não nomeia. |

```json
{
  "version": "2026-11-10",
  "event_id": "fb613a0660724669d9251d4185488ec26409b34345c592b908ce9747b8430f99",
  "event_type": "account.alert",
  "occurred_at": "2026-10-19T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "waba": {
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "entity_type": "WABA",
    "entity_id": "102290129340398",
    "alert_severity": "INFORMATIONAL",
    "alert_status": "ACTIVE",
    "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
    "alert_description": "Messaging limit increase deferred.",
    "details": {}
  }
}
```

### Number needs action

`number.action_required`

This number now needs an action from you or your customer: the customer authorization expiring or expired, no payment method at Meta, a restricted or disabled account, a PIN requested, registration blocked or a suspended plan. It carries status, can_send and reasons, each cause with code, message and solution, ready to show to your customer. It goes out when the list of causes goes from empty to non-empty, and not at every change to it; it is the same calculation as connection in GET /v1/numbers/{id}. When the list empties, number.action_resolved goes out.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | Este número passou a precisar de uma ação sua ou do seu cliente: autorização vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela. Mostra o motivo ao seu cliente com message e solution. Quando a lista esvazia, sai number.action_resolved. O estado corrente está em connection, em GET /v1/numbers/{id}. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.status` | `string` | yes | O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}. · Values: connected, connecting, action_required, disconnected |
| `number.can_send` | `boolean` | yes | Se o envio por este número vai funcionar agora, o mesmo de connection.canSend. |
| `number.reasons` | `array<object>` | yes | Os motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento. · at least 1 items |
| `number.reasons[].code` | `string` | yes | O código do motivo, para o seu código comparar: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired, account_blocked. Novos códigos podem aparecer. |
| `number.reasons[].message` | `string` | yes | O que está acontecendo, em português, pronto para repassar ao seu cliente. |
| `number.reasons[].solution` | `string` | yes | O que fazer a respeito, em português. |
| `event_type` | `"number.action_required"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "8832cdd12544436fce3b39d709158baa046091d010b5ed144a289c81b807c710",
  "event_type": "number.action_required",
  "occurred_at": "2026-10-28T15:02:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "status": "action_required",
    "can_send": false,
    "reasons": [
      {
        "code": "payment_required",
        "message": "A Meta recusou um envio deste número por falta de método de pagamento na conta de WhatsApp Business do negócio.",
        "solution": "O dono da conta cadastra o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. Quando um envio voltar a ser aceito, o aviso sai do ar."
      }
    ]
  }
}
```

### Number no longer needs action

`number.action_resolved`

The number no longer needs action: the list of causes in connection emptied, after a number.action_required. It is its pair, as number.payment_resolved is the pair of number.payment_required. status says how the connection ended up. A number you disconnected does not produce this event: number.disconnected already announced it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object` | yes | Este número não precisa mais de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou (connected, ou connecting se a conexão voltou a estar em curso). |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. |
| `number.status` | `string` | yes | O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}. · Values: connected, connecting, action_required, disconnected |
| `number.can_send` | `boolean` | yes | Se o envio por este número vai funcionar agora, o mesmo de connection.canSend. |
| `event_type` | `"number.action_resolved"` | yes |  |

```json
{
  "version": "2026-11-10",
  "event_id": "3279de99ef1bc2ade5d88bde7a2fd878b8faabddc179b8dceebded74d5b7394b",
  "event_type": "number.action_resolved",
  "occurred_at": "2026-10-28T15:40:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "status": "connected",
    "can_send": true
  }
}
```

### Connect link completed

`onboarding.link.completed`

Your customer completed the connection through a link: the link becomes used. It carries the link externalId and, when Luna has already registered the number, number_id; the number.connected event announces when the number is ready to send. It goes out once per link.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | yes | O número do link de reconexão ou o que resultou da conexão, ou null quando o evento não tem número. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número que resultou da conexão, no mesmo formato dos eventos number.*, com waba_id. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | yes | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `number.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. |
| `event_type` | `"onboarding.link.completed"` | yes |  |
| `link` | `object` | yes | O seu cliente concluiu a conexão por um link: ele aceitou os termos da Meta e a Luna recebeu o acesso à conta dele. É o fim do link, que passa a used. O número pode ainda estar sendo registrado: quem avisa que ele ficou pronto para enviar é number.connected. Sai uma vez por link. |
| `link.id` | `string (uuid)` | yes | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | yes | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. |
| `link.used_at` | `string` | yes | Quando a conexão por este link concluiu, o mesmo usedAt de GET /v1/onboarding/links/{id}. |
| `link.waba_id` | `string \| null` | yes | A conta de WhatsApp Business que o seu cliente conectou, o mesmo id que GET /v1/business-accounts devolve em wabaId. Está preenchido mesmo quando a conta foi conectada sem número (number_id nulo). Nulo só se a Luna não a leu. |
| `link.number_id` | `string (uuid) \| null` | yes | O número que resultou da conexão, o mesmo id de GET /v1/numbers. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto. |

```json
{
  "version": "2026-11-10",
  "event_id": "fd3596b2273541c7a77c69cb8a2ddb0e060052ddc84f251b5a76961053b578b1",
  "event_type": "onboarding.link.completed",
  "occurred_at": "2026-10-28T15:30:12.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "waba_id": "102290129340398"
  },
  "link": {
    "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
    "external_id": "cliente-8841",
    "used_at": "2026-10-28T15:30:12.000Z",
    "waba_id": "102290129340398",
    "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b"
  }
}
```

### Connect link opened

`onboarding.link.opened`

Your customer opened the link for the first time. It goes out once per link, and not again when they come back to the page or try again. It carries the link externalId and opened_at. It is the start of the cycle: onboarding.link.completed, onboarding.link.failed or onboarding.link.expired follow. Whoever opened and never completed shows up here without a completed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | yes | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"onboarding.link.opened"` | yes |  |
| `link` | `object` | yes | O seu cliente abriu o link pela primeira vez. Sai uma vez por link, na primeira abertura, e não de novo quando ele volta à página ou tenta outra vez. É o começo do ciclo: depois dele vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed. |
| `link.id` | `string (uuid)` | yes | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | yes | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. |
| `link.opened_at` | `string` | yes | Quando o seu cliente abriu o link pela primeira vez. |

```json
{
  "version": "2026-11-10",
  "event_id": "b8a277c5c9377c213ee4c3b79c3e83829f3bef5f69521db1a0434da05acfbc1d",
  "event_type": "onboarding.link.opened",
  "occurred_at": "2026-10-28T15:21:40.000Z",
  "phone_number_id": null,
  "number": null,
  "link": {
    "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
    "external_id": "cliente-8841",
    "opened_at": "2026-10-28T15:21:40.000Z"
  }
}
```

### A connect link attempt did not work out

`onboarding.link.failed`

A connection attempt through a link did not work out. reason says why: abandoned (the customer closed Meta’s window, and step carries the screen where they stopped), error (Meta’s window reported an error, in error_code), failed (Luna tried to complete and could not), country_not_supported (the number is not +55) or registration_blocked (Meta blocked registration for 72 hours). The link stays open until it expires. It goes out once per attempt.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | yes | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"onboarding.link.failed"` | yes |  |
| `link` | `object` | yes | Uma tentativa de conexão por um link não deu certo: o cliente desistiu em alguma tela, a janela da Meta relatou um erro, ou a conexão parou. O link continua aberto até vencer, e o cliente pode tentar de novo. Sai uma vez por tentativa. O que o cliente deve fazer para cada reason está no guia Conectar um número. |
| `link.id` | `string (uuid)` | yes | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | yes | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. |
| `link.session_id` | `string (uuid)` | yes | A tentativa de conexão que não deu certo. Um link aberto admite várias. |
| `link.reason` | `string` | yes | Por que a tentativa não deu certo: abandoned (o cliente fechou a janela da Meta e a tela em que parou está em step), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir várias vezes e não conseguiu), country_not_supported (o número escolhido não é +55) ou registration_blocked (a Meta bloqueou o registro do número por 72 horas). Novos motivos podem aparecer. · Values: abandoned, error, failed, country_not_supported, registration_blocked |
| `link.step` | `string \| null` | yes | O nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado. |
| `link.error_code` | `integer \| null` | yes | O código de erro que a janela da Meta relatou. Nulo quando não houve erro relatado. |

```json
{
  "version": "2026-11-10",
  "event_id": "cabf3f3478bda2efd0e9a3726d503dbcd575bec16cc0ccf5fc65cdcb4c88cea3",
  "event_type": "onboarding.link.failed",
  "occurred_at": "2026-10-28T15:12:40.000Z",
  "phone_number_id": null,
  "number": null,
  "link": {
    "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
    "external_id": "cliente-8841",
    "session_id": "2e8f4b60-1a3c-4d57-9b0e-6c7d8e9f0a12",
    "reason": "abandoned",
    "step": "phone_number_setup",
    "error_code": null
  }
}
```

### Connect link expired

`onboarding.link.expired`

The link expired with nobody completing the connection. Create another with POST /v1/onboarding/links whenever you want. A used link never produces this event. It goes out once per link.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | yes | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `object \| null` | yes | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. |
| `number.id` | `string (uuid)` | yes | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | yes | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | yes | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. |
| `event_type` | `"onboarding.link.expired"` | yes |  |
| `link` | `object` | yes | O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link que foi usado nunca gera este evento. Sai uma vez por link. |
| `link.id` | `string (uuid)` | yes | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | yes | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. |
| `link.expired_at` | `string` | yes | Quando o link venceu, o mesmo expiresAt de GET /v1/onboarding/links/{id}. |

```json
{
  "version": "2026-11-10",
  "event_id": "1df73af80cf86f74267290bc13fcd1f82551997dd79845170b35c78f40b563ad",
  "event_type": "onboarding.link.expired",
  "occurred_at": "2026-10-31T15:00:00.000Z",
  "phone_number_id": null,
  "number": null,
  "link": {
    "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
    "external_id": "cliente-8841",
    "expired_at": "2026-10-31T15:00:00.000Z"
  }
}
```

### A template category changed

`template.category`

Meta changed, or announced it will change, a template category. The category sets the price Meta charges the business: from UTILITY to MARKETING, the price goes up. It arrives as an advance notice (correct_category and scheduled_for) and as a change made (previous_category and new_category). It has no number and no message.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | yes | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `null` | yes | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"template.category"` | yes |  |
| `template` | `object` | yes | A Meta mudou, ou vai mudar, a categoria de um template. Chega de duas formas: o aviso prévio (correct_category e scheduled_for preenchidos) e a mudança feita (previous_category e new_category preenchidos). A categoria define o preço que a Meta cobra do negócio por mensagem: de UTILITY para MARKETING, o preço sobe. Quem paga é o dono da conta, direto à Meta. |
| `template.id` | `string (uuid)` | yes | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. |
| `template.name` | `string` | yes | O nome do template. |
| `template.language` | `string` | yes | O idioma do template, no código da Meta. |
| `template.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. |
| `template.external_id` | `string \| null` | yes | O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts). |
| `template.category` | `string` | yes | A categoria do template, no vocabulário da Meta. |
| `template.previous_category` | `string \| null` | yes | A categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio. |
| `template.new_category` | `string \| null` | yes | A categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio. |
| `template.correct_category` | `string \| null` | yes | No aviso prévio, a categoria para a qual a Meta vai mudar o template. Nulo quando a mudança já foi feita. |
| `template.scheduled_for` | `string \| null` | yes | No aviso prévio, quando a Meta aplica a mudança. Nulo quando a mudança já foi feita. |

```json
{
  "version": "2026-11-10",
  "event_id": "67e825cdeb1f139ea3f76761c2e087a272352caca49dea9ab471383293a8ca07",
  "event_type": "template.category",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": null,
  "number": null,
  "template": {
    "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
    "name": "pedido_confirmado",
    "language": "pt_BR",
    "waba_id": "102290129340398",
    "external_id": "cliente-8841",
    "category": "UTILITY",
    "previous_category": null,
    "new_category": null,
    "correct_category": "MARKETING",
    "scheduled_for": "2026-10-14T17:46:40.000Z"
  }
}
```

```json
{
  "version": "2026-11-10",
  "event_id": "a088e870f11e399bc1d40266c5d07e18d0b13da6d1cf4d2021cbb232451ed86d",
  "event_type": "template.category",
  "occurred_at": "2026-10-14T17:46:40.000Z",
  "phone_number_id": null,
  "number": null,
  "template": {
    "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
    "name": "pedido_confirmado",
    "language": "pt_BR",
    "waba_id": "102290129340398",
    "external_id": "cliente-8841",
    "category": "MARKETING",
    "previous_category": "UTILITY",
    "new_category": "MARKETING",
    "correct_category": null,
    "scheduled_for": null
  }
}
```

### A template quality changed

`template.quality`

A template quality score changed (GREEN, YELLOW, RED). A low score comes before Meta pauses the template. It has no number and no message.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | yes | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. |
| `event_id` | `string` | yes | O identificador estável deste evento. Use-o para descartar repetições. · 64 to 64 characters |
| `occurred_at` | `string` | yes | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | yes | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. |
| `test` | `true` | no | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. |
| `number` | `null` | yes | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"template.quality"` | yes |  |
| `template` | `object` | yes | A nota de qualidade de um template mudou. Nota baixa antecede a pausa do template pela Meta: é o momento de revisar o conteúdo ou o público. |
| `template.id` | `string (uuid)` | yes | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. |
| `template.name` | `string` | yes | O nome do template. |
| `template.language` | `string` | yes | O idioma do template, no código da Meta. |
| `template.waba_id` | `string` | yes | A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. |
| `template.external_id` | `string \| null` | yes | O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts). |
| `template.previous_quality_score` | `string \| null` | yes | A nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN. |
| `template.new_quality_score` | `string \| null` | yes | A nota de qualidade de agora, no vocabulário da Meta. |

```json
{
  "version": "2026-11-10",
  "event_id": "8624296410fe8b7631164b57d667847f22145595d3bac4ae644e32930aab9321",
  "event_type": "template.quality",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": null,
  "number": null,
  "template": {
    "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
    "name": "pedido_confirmado",
    "language": "pt_BR",
    "waba_id": "102290129340398",
    "external_id": "cliente-8841",
    "previous_quality_score": "GREEN",
    "new_quality_score": "YELLOW"
  }
}
```

## Errors

| HTTP status | Description |
| --- | --- |
| `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. |
| `401` | The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which. |
| `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. |
| `404` | The resource does not exist, or is not yours. The two answers are identical, byte for byte. |
| `409` | The request is well formed, but the resource state does not allow it. The error field says which case it is. |
| `410` | The connect link expired or was already used. The error field says which of the two. |
| `413` | The file is over the size ceiling, which is the same for every customer. |
| `415` | The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes. |
| `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. |
| `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. |
| `503` | The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one. |

| Error code (error) | HTTP status | When it happens |
| --- | --- | --- |
| `invalid_request` | 400 | Field refused, with the reason |
| `invalid_reset_token` | 400 | Invalid reset link |
| `unauthorized` | 401 | Key refused |
| `account_blocked` | 403 | Account blocked by Helsen |
| `connection_not_released` | 403 | Account not yet released to connect |
| `forbidden` | 403 | Insufficient scope |
| `test_key_not_allowed` | 403 | Test key on a route outside test mode |
| `trial_expired` | 403 | Free trial ended |
| `not_found` | 404 | Does not exist, or is not yours |
| `account_at_capacity` | 409 | The account that requested the link reached its maximum of numbers |
| `already_requeued` | 409 | Item already requeued |
| `idempotency_key_reused` | 409 | Idempotency-Key used with another body |
| `link_not_open` | 409 | Link that is not open |
| `media_not_ready` | 409 | Media not fetched yet |
| `message_not_cancelable` | 409 | Message that already left the queue |
| `no_webhook_endpoint` | 409 | No active webhook endpoint |
| `not_available_in_coexistence` | 409 | Unavailable in coexistence |
| `number_capacity_reached` | 409 | The account is already at its number capacity |
| `number_disconnected` | 409 | Number disconnected from Luna |
| `pin_not_applicable` | 409 | The number does not ask for a PIN |
| `reconnect_not_applicable` | 409 | The authorization does not allow reconnection |
| `register_budget_reserved` | 409 | Registration attempts reserved |
| `template_content_unknown` | 409 | Luna does not know the template content |
| `template_not_approved` | 409 | Template that is not approved yet |
| `webhook_endpoint_limit` | 409 | Endpoint limit |
| `window_closed` | 409 | Service window closed |
| `link_expired` | 410 | Link expired |
| `link_used` | 410 | Link already used |
| `file_too_large` | 413 | File over the ceiling |
| `unsupported_media_type` | 415 | Content type not read |
| `meta_rejected` | 422 | Meta refused the operation |
| `management_busy` | 429 | Account management busy |
| `number_rate_limited` | 429 | Number pace |
| `queue_full` | 429 | Send queue full |
| `rate_limited` | 429 | Request limit |
| `unavailable` | 503 | Unavailable |
