# Referência da API

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

## Mensagens

Enviar mensagens e consultar o que entrou e saiu. O envio é assíncrono: a resposta é 202 e a entrega acontece no ritmo que a Meta permite.

### Listar mensagens

`GET /v1/messages`

O registro do que entrou e saiu, do mais recente para o mais antigo. Cada mensagem traz o número, o rótulo do cliente, a conversa e, quando falhou, o resumo do erro. Filtros: phoneNumberId, externalId, conversationId, waId, userId, wamid, direction, status, since e until. Parâmetro que a rota não conhece volta 400. format=csv devolve text/csv, com os mesmos filtros.

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

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

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `limit` | `integer` | não | 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` | não | 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` | não | O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. |
| `externalId` | `string` | não | O rótulo que você deu ao seu cliente (externalId): só as mensagens dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia. |
| `conversationId` | `string` | não |  |
| `waId` | `string` | não | 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` | não | 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` | não | inbound: só o que chegou. outbound: só o que você enviou. |
| `status` | `string` | não | 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` | não | 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` | não | Só as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until). |
| `wamid` | `string` | não | 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` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

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

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

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

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

### Enviar mensagem

`POST /v1/messages`

Aceita a mensagem, devolve 202 com o identificador, e entrega à Meta de forma assíncrona. Com uma chave de teste, a mensagem NÃO vai à Meta: a Luna devolve o 202 e entrega ao seu webhook os estados simulados sent, delivered e read, com test: true. O cabeçalho opcional Idempotency-Key (de 1 a 255 caracteres visíveis, sem espaço) faz repetir o pedido devolver a mensagem original; vazio ou fora do formato volta 400.

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

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

#### Corpo da requisição

`application/json`

Forma 1: `type = "text"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | não | Sempre text. Pode ser omitido: um corpo sem type é interpretado como texto, para não quebrar quem integrou antes dos demais tipos existirem. · padrão: "text" · Valores: text |
| `text` | `object` | sim |  |
| `text.body` | `string` | sim | O texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API. · 1 a 4096 caracteres |
| `text.preview_url` | `boolean` | não | 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. |

Forma 2: `type = "image"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre image. · Valores: image |
| `image` | `object` | sim |  |
| `image.id` | `string` | não | 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 a 128 caracteres |
| `image.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `image.caption` | `string` | não | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · até 1024 caracteres |

Forma 3: `type = "video"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre video. · Valores: video |
| `video` | `object` | sim |  |
| `video.id` | `string` | não | 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 a 128 caracteres |
| `video.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `video.caption` | `string` | não | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · até 1024 caracteres |

Forma 4: `type = "audio"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre audio. · Valores: audio |
| `audio` | `object` | sim |  |
| `audio.id` | `string` | não | 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 a 128 caracteres |
| `audio.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `audio.voice` | `boolean` | não | 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. |

Forma 5: `type = "document"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre document. · Valores: document |
| `document` | `object` | sim |  |
| `document.id` | `string` | não | 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 a 128 caracteres |
| `document.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `document.caption` | `string` | não | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · até 1024 caracteres |
| `document.filename` | `string` | não | O nome com que o arquivo aparece para quem recebe. Sem ele, quem recebe vê o nome que a Meta derivar da origem. · 1 a 240 caracteres |

Forma 6: `type = "sticker"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre sticker. · Valores: sticker |
| `sticker` | `object` | sim |  |
| `sticker.id` | `string` | não | 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 a 128 caracteres |
| `sticker.link` | `string (uri)` | não | 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. · até 2048 caracteres |

Forma 7: `type = "location"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre location. · Valores: location |
| `location` | `object` | sim |  |
| `location.latitude` | `number` | sim | A latitude em graus decimais, entre -90 e 90. · mínimo -90 · máximo 90 |
| `location.longitude` | `number` | sim | A longitude em graus decimais, entre -180 e 180. · mínimo -180 · máximo 180 |
| `location.name` | `string` | não | O nome do lugar, exibido acima do endereço. · até 1000 caracteres |
| `location.address` | `string` | não | O endereço do lugar, exibido abaixo do nome. · até 1000 caracteres |

Forma 8: `type = "contacts"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre contacts. · Valores: contacts |
| `contacts` | `array<object>` | sim | Os cartões de contato a enviar. Ao menos um, no máximo vinte. · 1 a 20 itens |
| `contacts[].name` | `object` | sim |  |
| `contacts[].name.formatted_name` | `string` | sim | O nome como ele aparece no cartão. · 1 a 512 caracteres |
| `contacts[].name.first_name` | `string` | não | O primeiro nome. · até 256 caracteres |
| `contacts[].name.last_name` | `string` | não | O sobrenome. · até 256 caracteres |
| `contacts[].name.middle_name` | `string` | não | O nome do meio. · até 256 caracteres |
| `contacts[].name.prefix` | `string` | não | O prefixo, como Dr. ou Sra. · até 64 caracteres |
| `contacts[].name.suffix` | `string` | não | O sufixo, como Jr. ou Neto. · até 64 caracteres |
| `contacts[].birthday` | `string` | não | A data de nascimento em AAAA-MM-DD. · /^\d{4}-\d{2}-\d{2}$/ |
| `contacts[].org` | `object` | não | Os dados profissionais do contato. |
| `contacts[].org.company` | `string` | não | A empresa. · até 256 caracteres |
| `contacts[].org.department` | `string` | não | O departamento. · até 256 caracteres |
| `contacts[].org.title` | `string` | não | O cargo. · até 256 caracteres |
| `contacts[].phones` | `array<object>` | não | Os telefones do contato. · até 20 itens |
| `contacts[].phones[].phone` | `string` | não | O telefone, como ele deve aparecer. · até 64 caracteres |
| `contacts[].phones[].type` | `string` | não | O rótulo do telefone, como CELL ou WORK. · até 64 caracteres |
| `contacts[].phones[].wa_id` | `string` | não | O identificador do contato no WhatsApp, se conhecido. · até 64 caracteres |
| `contacts[].emails` | `array<object>` | não | Os e-mails do contato. · até 20 itens |
| `contacts[].emails[].email` | `string` | não | O endereço de e-mail. · até 320 caracteres |
| `contacts[].emails[].type` | `string` | não | O rótulo do e-mail, como HOME ou WORK. · até 64 caracteres |
| `contacts[].addresses` | `array<object>` | não | Os endereços do contato. · até 20 itens |
| `contacts[].addresses[].street` | `string` | não | O logradouro e o número. · até 512 caracteres |
| `contacts[].addresses[].city` | `string` | não | A cidade. · até 256 caracteres |
| `contacts[].addresses[].state` | `string` | não | O estado. · até 256 caracteres |
| `contacts[].addresses[].zip` | `string` | não | O CEP. · até 64 caracteres |
| `contacts[].addresses[].country` | `string` | não | O país. · até 256 caracteres |
| `contacts[].addresses[].country_code` | `string` | não | O código do país em duas letras. · até 8 caracteres |
| `contacts[].addresses[].type` | `string` | não | O rótulo do endereço, como HOME ou WORK. · até 64 caracteres |
| `contacts[].urls` | `array<object>` | não | As páginas do contato. · até 20 itens |
| `contacts[].urls[].url` | `string` | não | O endereço na web. · até 2048 caracteres |
| `contacts[].urls[].type` | `string` | não | O rótulo da URL, como HOME ou WORK. · até 64 caracteres |

Forma 9: `type = "reaction"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre reaction. · Valores: reaction |
| `reaction` | `object` | sim |  |
| `reaction.message_id` | `string` | sim | 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 a 256 caracteres |
| `reaction.emoji` | `string` | sim | O emoji da reação. Mande vazio para remover uma reação que já tinha sido posta. · até 16 caracteres |

Forma 10: `type = "interactive"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre interactive. · Valores: interactive |
| `interactive` | `object` | sim | 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` | não | Sempre button. · Valores: button |
| `interactive.header` | `object` | não | O cabeçalho, exibido acima do corpo. |
| `interactive.header.type` | `string` | sim | O que o cabeçalho carrega. · Valores: text, image, video, document |
| `interactive.header.text` | `string` | não | O texto do cabeçalho, quando type é text. · até 60 caracteres |
| `interactive.header.image` | `object` | não | A imagem do cabeçalho, quando type é image. |
| `interactive.header.image.id` | `string` | não | 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 a 128 caracteres |
| `interactive.header.image.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `interactive.header.video` | `object` | não | O vídeo do cabeçalho, quando type é video. |
| `interactive.header.video.id` | `string` | não | 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 a 128 caracteres |
| `interactive.header.video.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `interactive.header.document` | `object` | não | O documento do cabeçalho, quando type é document. |
| `interactive.header.document.id` | `string` | não | 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 a 128 caracteres |
| `interactive.header.document.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `interactive.header.document.filename` | `string` | não | até 240 caracteres |
| `interactive.body` | `object` | não | O corpo da mensagem interativa. |
| `interactive.body.text` | `string` | sim | O texto do corpo. · 1 a 1024 caracteres |
| `interactive.footer` | `object` | não | O rodapé, exibido abaixo dos botões. |
| `interactive.footer.text` | `string` | sim | O texto do rodapé. · até 60 caracteres |
| `interactive.action` | `object` | não |  |
| `interactive.action.buttons` | `array<object>` | sim | Os botões de resposta. De um a três, o teto da Cloud API. · 1 a 3 itens |
| `interactive.action.buttons[].type` | `string` | sim | Sempre reply. · Valores: reply |
| `interactive.action.buttons[].reply` | `object` | sim |  |
| `interactive.action.buttons[].reply.id` | `string` | sim | O identificador que volta no webhook quando o botão é tocado. · 1 a 256 caracteres |
| `interactive.action.buttons[].reply.title` | `string` | sim | O rótulo do botão. Limite de 20 caracteres. · 1 a 20 caracteres |
| `interactive.action.button` | `string` | sim | O rótulo do botão que abre a lista. Limite de 20 caracteres. · 1 a 20 caracteres |
| `interactive.action.sections` | `array<object>` | sim | As seções da lista. De uma a dez, o teto da Cloud API. · 1 a 10 itens |
| `interactive.action.sections[].title` | `string` | não | O título da seção. · até 24 caracteres |
| `interactive.action.sections[].rows` | `array<object>` | sim | As linhas da seção. De uma a dez. · 1 a 10 itens |
| `interactive.action.sections[].rows[].id` | `string` | sim | O identificador que volta no webhook quando a linha é escolhida. · 1 a 200 caracteres |
| `interactive.action.sections[].rows[].title` | `string` | sim | O título da linha. · 1 a 24 caracteres |
| `interactive.action.sections[].rows[].description` | `string` | não | A descrição da linha. · até 72 caracteres |
| `interactive.action.name` | `string` | não | Sempre cta_url. · padrão: "cta_url" · Valores: cta_url |
| `interactive.action.parameters` | `object` | sim |  |
| `interactive.action.parameters.display_text` | `string` | sim | O rótulo do botão. Limite de 20 caracteres. · 1 a 20 caracteres |
| `interactive.action.parameters.url` | `string (uri)` | sim | O endereço que o botão abre. · até 2048 caracteres |
| `interactive.action.parameters.country` | `string` | não | O país do endereço, em duas letras (ISO 3166). O padrão é BR. · /^[A-Za-z]{2}$/ · padrão: "BR" |
| `interactive.action.parameters.values` | `object` | não | 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>` | não | Endereços salvos que o usuário pode escolher, no máximo vinte. · até 20 itens |
| `interactive.action.parameters.saved_addresses[].id` | `string` | sim | O identificador do endereço salvo. · 1 a 128 caracteres |
| `interactive.action.parameters.saved_addresses[].value` | `object` | sim | Os campos do endereço salvo. |
| `interactive.action.parameters.validation_errors` | `object` | não | Mensagens de erro por campo, para quando você devolve o formulário depois de uma validação. |
| `interactive.action.cards` | `array<object>` | sim | Os cartões, de dois a dez. · 2 a 10 itens |
| `interactive.action.cards[].card_index` | `integer` | sim | A posição do cartão, de 0 a 9. Não repita. · mínimo 0 · máximo 9 |
| `interactive.action.cards[].type` | `string` | não | Sempre cta_url. · padrão: "cta_url" · Valores: cta_url |
| `interactive.action.cards[].header` | `object` | sim | A mídia do cartão. |
| `interactive.action.cards[].header.type` | `string` | sim | O que o cartão mostra. · Valores: image, video |
| `interactive.action.cards[].header.image` | `object` | não | A imagem do cartão, quando type é image. |
| `interactive.action.cards[].header.image.id` | `string` | não | 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 a 128 caracteres |
| `interactive.action.cards[].header.image.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `interactive.action.cards[].header.video` | `object` | não | O vídeo do cartão, quando type é video. |
| `interactive.action.cards[].header.video.id` | `string` | não | 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 a 128 caracteres |
| `interactive.action.cards[].header.video.link` | `string (uri)` | não | 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. · até 2048 caracteres |
| `interactive.action.cards[].body` | `object` | não | O texto do cartão. |
| `interactive.action.cards[].body.text` | `string` | sim | O texto do cartão. Limite de 160 caracteres. · 1 a 160 caracteres |
| `interactive.action.cards[].action` | `object` | sim |  |
| `interactive.action.cards[].action.name` | `string` | não | Sempre cta_url. · padrão: "cta_url" · Valores: cta_url |
| `interactive.action.cards[].action.parameters` | `object` | sim |  |
| `interactive.action.cards[].action.parameters.display_text` | `string` | sim | O rótulo do botão. Limite de 20 caracteres. · 1 a 20 caracteres |
| `interactive.action.cards[].action.parameters.url` | `string (uri)` | sim | O endereço que o botão abre. · até 2048 caracteres |
| `interactive.action.parameters.flow_message_version` | `string` | não | A versão do formato da mensagem de Flow. O padrão é 3, a corrente na Meta. · 1 a 8 caracteres · padrão: "3" |
| `interactive.action.parameters.flow_id` | `string` | não | O identificador do Flow. Use este OU flow_name. · 1 a 64 caracteres |
| `interactive.action.parameters.flow_name` | `string` | não | O nome do Flow. Use este OU flow_id. · 1 a 200 caracteres |
| `interactive.action.parameters.flow_cta` | `string` | sim | 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 a 40 caracteres |
| `interactive.action.parameters.flow_token` | `string` | não | O que você quer receber de volta na resposta do Flow, para ligá-la a este envio. · até 256 caracteres |
| `interactive.action.parameters.flow_action` | `string` | não | navigate (padrão da Meta) ou data_exchange. · 1 a 32 caracteres |
| `interactive.action.parameters.flow_action_payload` | `object` | não | A tela e os dados de abertura, quando flow_action é navigate. |
| `interactive.action.parameters.flow_action_payload.screen` | `string` | sim | A tela do Flow que abre primeiro. · 1 a 200 caracteres |
| `interactive.action.parameters.flow_action_payload.data` | `object` | não | Os dados que o Flow recebe nessa tela. |
| `interactive.action.parameters.mode` | `string` | não | draft para testar um Flow ainda não publicado, ou published (padrão da Meta). · 1 a 16 caracteres |
| `interactive.action.catalog_id` | `string` | sim | O identificador do catálogo na conta de negócio do número (catalog_id da Meta). · 1 a 64 caracteres |
| `interactive.action.product_retailer_id` | `string` | sim | O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta). · 1 a 256 caracteres |
| `interactive.action.sections[].product_items` | `array<object>` | sim | Os produtos da seção. · 1 a 30 itens |
| `interactive.action.sections[].product_items[].product_retailer_id` | `string` | sim | O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta). · 1 a 256 caracteres |

Forma 11: `type = "template"`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `from` | `string` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `to` | `string` | não | 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` | não | 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` | não | 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` | sim | 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 a 256 caracteres |
| `callbackData` | `string` | não | 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 a 512 caracteres |
| `typingMs` | `integer` | não | 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. · mínimo 1 · máximo 25000 |
| `type` | `string` | sim | Sempre template. · Valores: template |
| `template` | `object` | sim |  |
| `template.name` | `string` | sim | O nome do template já aprovado pela Meta. · 1 a 512 caracteres |
| `template.language` | `object` | sim |  |
| `template.language.code` | `string` | sim | O código do idioma do template, como pt_BR. Ele precisa bater com o aprovado. · 2 a 16 caracteres |
| `template.components` | `array<object>` | não | Os componentes que preenchem as variáveis do template. · até 32 itens |
| `template.components[].type` | `string` | sim | Qual parte do template este componente preenche. · Valores: header, body, button |
| `template.components[].sub_type` | `string` | não | O subtipo, exigido pela Cloud API quando type é button. · até 64 caracteres |
| `template.components[].index` | `string` | não | A posição do botão, exigida pela Cloud API quando type é button. · até 8 caracteres |
| `template.components[].parameters` | `array<object>` | não | Os valores das variáveis desta parte, na forma que a Cloud API define. · até 64 itens |

#### Exemplos de código

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

#### Respostas

**202**: Aceito: o pedido foi registrado e será processado.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Marcar uma mensagem como lida

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

Marca na Meta uma mensagem que você recebeu como lida, e responde 200 quando ela aceitou.

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

Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-messages-id-read

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Exemplos de código

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

#### Respostas

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

```json
{}
```

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Mostrar o indicador de digitando

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

Mostra ao destinatário que você está escrevendo, e responde 200 quando a Meta aceitou.

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

Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-messages-id-typing

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Exemplos de código

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

#### Respostas

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

```json
{}
```

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Consultar o estado de uma mensagem

`GET /v1/messages/{id}`

Devolve o estado atual da mensagem, os instantes de cada etapa e o que a Meta disse quando recusou alguma coisa.

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

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Cancelar uma mensagem na fila

`DELETE /v1/messages/{id}`

Cancela uma mensagem que ainda está na fila de saída (accepted) e responde 204. Ela passa ao estado canceled, que é terminal, e o evento message.status com status canceled chega ao seu webhook. Se a mensagem já saiu para a Meta ou já tem desfecho, responde 409 message_not_cancelable com o estado atual.

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

Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-delete-v1-messages-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador da mensagem na Luna, como POST /v1/messages o devolveu. |

#### Exemplos de código

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

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Reenviar o webhook de uma mensagem

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

Pede que o evento desta mensagem seja entregue de novo ao seu endpoint: o message.received, se ela foi recebida, ou o último message.status, se ela foi enviada, no mesmo formato do original e assinado do mesmo jeito. A resposta é 202: o pedido foi registrado, e a entrega acontece de forma assíncrona. Mensagem enviada que ainda não tem estado, ou que ainda não foi aceita pela Meta, responde 400.

Autenticação: Chave de API. Escopo exigido: `webhooks:write`

Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-messages-id-replay

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Simular uma mensagem recebida

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

Entrega aos seus endpoints de webhook UMA message.received de exemplo, assinada e com test: true no envelope, para você exercitar o seu código sem esperar um contato escrever. A mensagem sai em cerca de meio segundo, e nada é gravado nem passa por número seu ou pela Meta. Funciona com a chave de teste e com a chave comum.

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

#### Corpo da requisição

`application/json`

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

#### Exemplos de código

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

#### Respostas

**202**: Aceito: o pedido foi registrado e será processado.

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

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

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

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

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

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

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

## Conversas

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

### Listar conversas

`GET /v1/conversations`

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

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

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

#### Parâmetros de consulta

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

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

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

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

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

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

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

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

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

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

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

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

## Mídia

Enviar um arquivo para a Meta e baixar a mídia que chegou numa mensagem.

### Obter a mídia de uma mensagem

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

Devolve uma URL assinada, emitida pela Luna, para baixar a mídia que já foi persistida.

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

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Baixar a mídia pelo link do aviso

`GET /v1/media/{token}`

O link que vem em media.url nos avisos message.received e message.echo. Não pede chave de API: o token no endereço é a credencial. Mídia pronta responde 302 para uma URL assinada de vida curta; ainda sendo baixada da Meta, 409 com Retry-After; token que não existe ou vencido, 404.

Autenticação: Pública, sem chave

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim | O token do link, como veio em media.url. |

#### Exemplos de código

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

#### Respostas

**302**: Redirecionamento: siga o cabeçalho Location, que leva à URL assinada do arquivo.

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Subir um arquivo e obter o identificador de mídia

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

Recebe um arquivo em multipart/form-data no campo file, sobe para a Meta e devolve o identificador dele.

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

Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-numbers-id-media

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Corpo da requisição

`multipart/form-data`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `file` | `string (binary)` | sim | O arquivo a enviar, no campo file. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**413**: O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

## Templates

Mensagens pré-aprovadas pela Meta, necessárias para iniciar conversa fora da janela de 24 horas.

Aprovado não é liberado para volume: a Meta aplica um ritmo próprio sobre os primeiros envios de um template novo, e não publica prazo nem mecânica. Escalone o primeiro disparo em vez de programá-lo para uma data, e acompanhe o estado do template.

Acima de três botões, apenas dois aparecem na mensagem entregue. A Meta aceita o template com mais e entrega dois, então o arranjo precisa ser decidido antes de o fluxo ser desenhado.

### Listar templates

`GET /v1/templates`

Os templates deste cliente, do mais recente para o mais antigo.

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

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

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `status` | `string` | não | 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` | não | 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` | não | 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. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

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

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

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

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

### Criar um template

`POST /v1/templates`

Cria o template na conta do cliente e o submete à Meta para aprovação.

Autenticação: Chave de API. Escopo exigido: `templates:write`

Guia do tema: https://lunahia.com.br/docs/templates#rota-post-v1-templates

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `wabaId` | `string` | sim | 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `name` | `string` | sim | /^[a-z0-9_]{1,512}$/ |
| `bodyText` | `string` | sim | 1 a 1024 caracteres |
| `examples` | `object` | não | 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` | não | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 a 60 caracteres |
| `headerMedia` | `object` | não | 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` | sim | IMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF. · Valores: IMAGE, VIDEO, DOCUMENT |
| `headerMedia.handle` | `string` | sim | O handle devolvido por POST /v1/template-assets. · 1 a 2048 caracteres |
| `footer` | `string` | não | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 a 60 caracteres |
| `buttons` | `array<object>` | não | 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` | não | Valores: QUICK_REPLY |
| `buttons[].text` | `string` | não | 1 a 25 caracteres |
| `buttons[].url` | `string` | não | 1 a 2000 caracteres |
| `buttons[].example` | `array<string>` | não | até 1 itens |
| `buttons[].phone_number` | `string` | não | 1 a 20 caracteres |
| `category` | `string` | não | 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. · Valores: MARKETING, UTILITY |
| `language` | `string` | não | 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})?$/ |

#### Exemplos de código

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

#### Respostas

**201**: Criado.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Consultar um template

`GET /v1/templates/{id}`

O estado atual do template na Meta, o conteúdo que você escreveu e o que a Meta avisou sobre ele.

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

Guia do tema: https://lunahia.com.br/docs/templates#rota-get-v1-templates-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Editar um template

`PATCH /v1/templates/{id}`

Altera os componentes de um template existente.

Autenticação: Chave de API. Escopo exigido: `templates:write`

Guia do tema: https://lunahia.com.br/docs/templates#rota-patch-v1-templates-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `bodyText` | `string` | não | 1 a 1024 caracteres |
| `examples` | `object` | não |  |
| `header` | `string` | não | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 a 60 caracteres |
| `footer` | `string` | não | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 a 60 caracteres |
| `buttons` | `array<object>` | não | 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` | não | Valores: QUICK_REPLY |
| `buttons[].text` | `string` | não | 1 a 25 caracteres |
| `buttons[].url` | `string` | não | 1 a 2000 caracteres |
| `buttons[].example` | `array<string>` | não | até 1 itens |
| `buttons[].phone_number` | `string` | não | 1 a 20 caracteres |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Remover um template

`DELETE /v1/templates/{id}`

Remove o template na Meta e da sua listagem.

Autenticação: Chave de API. Escopo exigido: `templates:write`

Guia do tema: https://lunahia.com.br/docs/templates#rota-delete-v1-templates-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Ler as regras de um template

`GET /v1/templates/rules`

As categorias, os idiomas sugeridos, o formato do nome, os tamanhos máximos de corpo, cabeçalho e rodapé, e os limites de botões. É o que POST /v1/templates cobra, servido para você mostrar o mesmo limite sem copiar o número.

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

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

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

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

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

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

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

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

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

### Criar um template de autenticação

`POST /v1/templates/authentication`

Cria um template de autenticação com botão de copiar código, e o submete à Meta para aprovação.

Autenticação: Chave de API. Escopo exigido: `templates:write`

Guia do tema: https://lunahia.com.br/docs/templates#rota-post-v1-templates-authentication

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `wabaId` | `string` | sim | 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `name` | `string` | sim | /^[a-z0-9_]{1,512}$/ |
| `language` | `string` | não | 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` | não | 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` | sim | 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. · mínimo 1 · máximo 1440 |
| `buttonText` | `string` | não | 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 a 25 caracteres |
| `messageSendTtlSeconds` | `integer` | não | 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. · mínimo 1 |

#### Exemplos de código

```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
}'
```

#### Respostas

**201**: Criado.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Copiar um template para outros clientes

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

Cria uma cópia do template em até 50 destinos, cada um uma conta de negócio (wabaId) ou um cliente seu (externalId). Responde 200 com um resultado por destino, e um destino que falha não derruba os outros. A cópia passa pelo mesmo caminho e pelas mesmas regras de POST /v1/templates.

Autenticação: Chave de API. Escopo exigido: `templates:write`

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `targets` | `array<object>` | sim | Os destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }. · 1 a 50 itens |
| `targets[].wabaId` | `string` | não | A conta de negócio de destino, pelo id dela na Meta (wabaId). · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `targets[].externalId` | `string` | não | O rótulo do cliente de destino (externalId): a cópia vai para cada conta de WhatsApp Business dos números dele. · 1 a 128 caracteres |
| `headerMediaHandle` | `string` | não | 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 a 1024 caracteres |
| `authentication` | `object` | não | 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` | não | 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` | sim | 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. · mínimo 1 · máximo 1440 |
| `authentication.buttonText` | `string` | não | 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 a 25 caracteres |
| `authentication.messageSendTtlSeconds` | `integer` | não | 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. · mínimo 1 |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Subir o arquivo de exemplo de um cabeçalho de mídia

`POST /v1/template-assets`

Recebe um arquivo em multipart/form-data no campo file e devolve o handle que a criação de template aceita em headerMedia.handle.

Autenticação: Chave de API. Escopo exigido: `templates:write`

Guia do tema: https://lunahia.com.br/docs/templates#rota-post-v1-template-assets

#### Corpo da requisição

`multipart/form-data`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `file` | `string (binary)` | sim | O arquivo a enviar, no campo file. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

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

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

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

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

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

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

**413**: O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

## Números

Os números conectados: conectar, ver estado, qualidade e vazão, editar e desconectar.

Migrar um número que já está na API de outro provedor é caminho suportado, e não exige número novo nem perda do número atual. Um número já registrado na Cloud API de outro provedor quase sempre tem verificação em duas etapas configurada lá, e a Meta exige o PIN existente para registrá-lo de novo: não há endpoint para ler nem para desligar esse PIN, então ele precisa vir do negócio final. Informe o PIN em POST /v1/numbers/{id}/pin, ou peça ao negócio final que desligue a verificação em duas etapas no WhatsApp Manager dele. Os outros pré-requisitos também são do lado dele: ser o dono da conta de WhatsApp Business e ter o número liberado no provedor anterior.

Um número que hoje só existe no WhatsApp Business App, o aplicativo de celular, é o outro caso, e a Meta o chama de coexistência. Ele nunca passou por API nenhuma. A conexão parte da mesma janela da Meta, e a opção só aparece quando a conta do negócio final está habilitada para isso do lado da Meta e o aplicativo no aparelho está na versão 2.24.17 ou maior.

Conectado assim, o número continua funcionando no aplicativo de celular, e as conversas anteriores do aparelho são importadas para a plataforma: elas aparecem em GET /v1/messages junto das novas. A importação tem prazo para concluir, e quem diz onde ela está é GET /v1/numbers/{id}, nos campos sincronizacaoDoHistorico e sincronizacaoPrazo. O mesmo recurso traz tetoDeVazaoPorSegundo, que é o teto fixo de vazão de um número em coexistência e não sobe com o tempo. E o que o dono do negócio responder pelo aplicativo de celular também chega, na conversa do destinatário.

### Ler o perfil do negócio

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

O perfil que o contato vê no WhatsApp: recado, endereço, descrição, e-mail, sites, ramo e a foto. Não vale para número em coexistência.

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Mudar o perfil do negócio

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

Troca os campos que você mandar, e deixa os outros como estão. Com displayName, pede a mudança do nome de exibição e responde 202: o nome fica em revisão na Meta. Não vale para número em coexistência.

Autenticação: Chave de API. Escopo exigido: `numbers:write`

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `about` | `string` | não | O recado curto. Até 139 caracteres. · 1 a 139 caracteres |
| `address` | `string` | não | O endereço. Até 256 caracteres. · 1 a 256 caracteres |
| `description` | `string` | não | A descrição. Até 512 caracteres. · 1 a 512 caracteres |
| `email` | `string` | não | O e-mail de contato. Até 128 caracteres. · 1 a 128 caracteres |
| `websites` | `array<string (uri)>` | não | Até dois sites. A lista inteira substitui a que existe. · até 2 itens |
| `vertical` | `string` | não | O ramo de atividade, no vocabulário da Meta. · 1 a 64 caracteres |
| `displayName` | `string` | não | 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 a 512 caracteres |
| `profilePictureHandle` | `string` | não | 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 a 1024 caracteres |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

**202**: Aceito: o pedido foi registrado e será processado.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

**422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Listar os usuários bloqueados

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

Quem este número bloqueou, em páginas. O cursor é o da Meta, e não muda de forma.

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `limit` | `integer` | não | Quantos por página, de 1 a 100. |
| `cursor` | `string` | não | O nextCursor da página anterior. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Bloquear usuários

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

Bloqueia quem escreveu ao número nas últimas 24 horas. Cada usuário é um telefone ou um BSUID, e a resposta separa os que a Meta aceitou dos que ela recusou, com o motivo.

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `users` | `array<string>` | sim | Os usuários a bloquear, de um a cinquenta. · 1 a 50 itens |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

**422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Desbloquear um usuário

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

Desbloqueia um usuário, pelo telefone ou pelo BSUID que está no caminho. Fica aberta na conta suspensa: desbloquear nunca é o problema.

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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` | sim | O telefone (só dígitos) ou o BSUID do usuário. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Listar os QR codes

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

Os códigos que existem neste número, com o link curto de cada um.

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Criar um QR code e um link curto

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

Cria um código que abre uma conversa com o número, com a mensagem já escrita. Devolve o código, o link curto e, se você pediu, o endereço da imagem.

Autenticação: Chave de API. Escopo exigido: `numbers:write`

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `prefilledMessage` | `string` | sim | A mensagem que já vem escrita. Até 140 caracteres, o limite da Meta, que está a confirmar na doc dela. · 1 a 140 caracteres |
| `imageFormat` | `string` | não | Peça a imagem do QR em PNG ou SVG. Sem isto, só o código e o link voltam. · Valores: PNG, SVG |

#### Exemplos de código

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

#### Respostas

**201**: Criado.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

**422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Apagar um QR code

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

Apaga o código e o link curto: quem ainda tem o QR impresso deixa de abrir a conversa. Fica aberta na conta suspensa.

Autenticação: Chave de API. Escopo exigido: `numbers:write`

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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` | sim | O código do QR, como a criação o devolveu. |

#### Exemplos de código

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

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Abrir uma sessão de conexão

`POST /v1/onboarding/sessions`

Cria a sessão que o fluxo de conexão da Meta preenche, e devolve o sessionId e o csrfState.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-sessions

#### Exemplos de código

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

#### Respostas

**201**: Criado.

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

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

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

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

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

### Consultar uma sessão de conexão

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

O estado atual da sessão e a orientação correspondente, em português, pronta para exibir.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-get-v1-onboarding-sessions-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Registrar abandono ou erro do fluxo

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

Telemetria do que aconteceu na janela da Meta quando o fluxo não completou: em que tela o cliente parou, ou que erro a Meta reportou.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-sessions-id-abandon

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `csrfState` | `string` | sim |  |
| `currentStep` | `string \| null` | não | 1 a 120 caracteres |
| `errorCode` | `integer \| null` | não |  |
| `errorMessage` | `string \| null` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Concluir a conexão

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

Troca o código do fluxo embutido por acesso permanente à conta do cliente, e leva a sessão até o fim: token selado, aplicativo inscrito na conta, número registrado.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-sessions-id-complete

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `code` | `string` | sim |  |
| `csrfState` | `string` | sim |  |
| `wabaId` | `string \| null` | não |  |
| `phoneNumberId` | `string \| null` | não |  |
| `businessId` | `string \| null` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Listar números conectados

`GET /v1/numbers`

Todos os números de WhatsApp conectados a este cliente, com estado, qualidade, velocidade de envio e limite diário de conversas. Filtros: externalId (igualdade exata), q (busca por prefixo em externalId, label e displayNumber), state, wabaId, qualityRating, connectionStatus, ready e canSend. Parâmetro que a rota não conhece volta 400.

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

Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-get-v1-numbers

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `externalId` | `string` | não | O rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia. |
| `state` | `string` | não | O estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED. |
| `q` | `string` | não | 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` | não | 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` | não | 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` | não | Só os números com este connection.status: connected, connecting, action_required ou disconnected. |
| `ready` | `string` | não | true: só os números prontos para enviar e receber. false: só os que ainda não estão. |
| `canSend` | `string` | não | true: só os números por onde enviar funciona agora (connection.canSend). false: só os que não. |
| `limit` | `integer` | não | Quantos números por página: de 1 a 100, 50 se omitido. |
| `cursor` | `string` | não | O nextCursor da resposta anterior. Opaco: carrega posição, não contagem. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

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

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

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

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

### Consultar um número

`GET /v1/numbers/{id}`

Um número, com tudo que a listagem traz mais a saúde da conexão com a Meta.

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

Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-get-v1-numbers-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Editar um número

`PATCH /v1/numbers/{id}`

Troca o externalId e o label de um número, e liga ou desliga o autoRead (marcar como lida sozinho cada mensagem recebida). É o jeito de reaproveitar um número para outro cliente seu, ou de dar nome a um número que foi conectado pelo console, sem link.

Autenticação: Chave de API. Escopo exigido: `numbers:write`

Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-patch-v1-numbers-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `externalId` | `string \| null` | não | O seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa. · 1 a 128 caracteres |
| `label` | `string \| null` | não | Um nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa. · 1 a 128 caracteres |
| `autoRead` | `boolean` | não | 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. |

#### Exemplos de código

```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
}'
```

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Desconectar um número

`DELETE /v1/numbers/{id}`

Tira o número da Luna. É o jeito de abrir uma vaga na capacidade do plano: o número deixa de contar a partir deste instante, e o seu cliente pode ser trocado por outro.

Autenticação: Chave de API. Escopo exigido: `numbers:write`

Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-delete-v1-numbers-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Exemplos de código

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

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Informar o PIN de verificação em duas etapas de um número

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

Informa o PIN de verificação em duas etapas de um número que já está registrado na Cloud API de outro provedor, para que a Luna consiga registrá-lo sem que o negócio final precise desligar a verificação.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-numbers-id-pin

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `pin` | `string` | sim | 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}$/ |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Reconectar um número cuja autorização morreu

`POST /v1/onboarding/reconnect`

Abre uma sessão de conexão para um número que já existe, quando a autorização concedida pelo cliente expirou ou foi revogada.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-reconnect

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `numberId` | `string` | sim | O número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |

#### Exemplos de código

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

#### Respostas

**201**: Criado.

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

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Listar contas de negócio

`GET /v1/business-accounts`

As contas de WhatsApp Business que este cliente conectou, da mais recente para a mais antiga, cada uma com o nome na Meta, o endereço no WhatsApp Manager e os números.

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

Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-get-v1-business-accounts

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

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

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

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

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

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

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

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

### Conferir agora a forma de pagamento da conta na Meta

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

Lê na Meta se a conta tem forma de pagamento cadastrada, sem esperar a leitura de hora em hora, e devolve o resultado. O aviso por webhook segue o caminho de sempre: number.action_required (motivo payment_method_missing) quando falta e number.action_resolved quando aparece. Leitura com menos de 60 segundos é devolvida sem chamar a Meta, e a chamada respeita o orçamento de chamadas da conta.

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O id da conta de negócio na Luna, o mesmo que GET /v1/business-accounts devolve em id. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Consultar a saúde de um número

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

A avaliação de qualidade, o nível de vazão e o limite diário de conversas que a Meta atribui a este número agora, e as mudanças que a plataforma observou ao longo do tempo.

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

Guia do tema: https://lunahia.com.br/docs/saude-da-conta#rota-get-v1-numbers-id-health

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | 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. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Ler o consumo da Meta de um número ou de um cliente

`GET /v1/usage`

O consumo que a Meta mede para um número (numberId) ou para todos os números de um cliente seu (externalId), repassado como ela informa, com a moeda de cada conta e sem somar. format=csv devolve text/csv. A Luna só lê e mostra: nada disto entra na assinatura da Luna.

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

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `numberId` | `string` | não | 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` | não | 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` | não | 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` | não | O fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos). |
| `granularity` | `string` | não | 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` | não | 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. |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

## Links de conexão

Um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console. Um link por cliente seu, amarrado ao externalId que você escolheu.

### Listar os links de conexão

`GET /v1/onboarding/links`

Os links que você criou, do mais recente para o mais antigo, inclusive os revogados. Filtros: externalId (igualdade), q (começo do externalId) e status (open, used, expired ou revoked).

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

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-get-v1-onboarding-links

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `q` | `string` | não | 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` | não | 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` | não | Só os links neste estado: open, used, expired ou revoked. |
| `limit` | `integer` | não |  |
| `cursor` | `string` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

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

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

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

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

### Criar um link de conexão para o seu cliente

`POST /v1/onboarding/links`

Cria um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-onboarding-links

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `externalId` | `string` | não | 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 a 128 caracteres |
| `displayName` | `string` | não | 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 a 120 caracteres |
| `redirectUrl` | `string` | não | 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. · até 2048 caracteres · /^https:\/\/[^\s]+$/ |
| `numberId` | `string` | não | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |

#### Exemplos de código

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

#### Respostas

**201**: Criado.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Consultar um link de conexão

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

O estado de um link: open, used, expired ou revoked, com a finalidade, a última falha e o que a conta pode fazer com ele.

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

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-get-v1-onboarding-links-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Revogar um link de conexão

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

Revoga o link. A url deixa de funcionar na hora e passa a responder 404 a quem a abrir, como uma que nunca existiu. Uma conexão que o cliente já tinha começado na janela da Meta não pode mais ser concluída por ela. O link continua na sua lista, com status revoked e revokedAt. Revogar de novo um link já revogado responde 404.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-delete-v1-onboarding-links-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Criar vários links de conexão de uma vez

`POST /v1/onboarding/links/batch`

Cria até 100 links, cada item no mesmo formato de POST /v1/onboarding/links e com as mesmas regras, inclusive a capacidade do plano. Responde 200 com um resultado por item, com a url de cada link criado; um item que falha não derruba os outros.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `links` | `array<object>` | sim | 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 a 100 itens |
| `links[].externalId` | `string` | não | 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 a 128 caracteres |
| `links[].displayName` | `string` | não | 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 a 120 caracteres |
| `links[].redirectUrl` | `string` | não | 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. · até 2048 caracteres · /^https:\/\/[^\s]+$/ |
| `links[].numberId` | `string` | não | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Gerar de novo a url de um link de conexão

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

Gera um token novo para o mesmo link (mesmo id, mesmo rótulo, mesmo prazo): a url antiga deixa de funcionar na hora e a nova aparece só nesta resposta. Só vale para um link aberto; usado, vencido ou revogado responde 409. Use quando o seu cliente perdeu a url, em vez de revogar e criar outro.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

## Webhooks e eventos

Para onde a Luna entrega o que chega no seu número, o segredo que assina essas entregas e os tipos de evento, cada um com o esquema e um exemplo.

### Listar os endpoints de webhook

`GET /v1/webhooks/endpoints`

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). Cada endpoint traz deliveryStatus.

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

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-endpoints

#### Exemplos de código

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

#### Respostas

**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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

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

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

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

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

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

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

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

### Cadastrar o endpoint de webhook

`POST /v1/webhooks/endpoints`

Registra a URL do seu servidor e devolve o segredo que assina as entregas. headers, opcional, leva até 5 cabeçalhos HTTP próprios que a Luna envia em cada entrega (para um gateway que exige um token fixo); os valores são segredo e nenhuma resposta os devolve.

Autenticação: Chave de API. Escopo exigido: `webhooks:write`

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-endpoints

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `url` | `string` | sim | A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público. · até 2048 caracteres |
| `eventTypes` | `array<string>` | não | 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. · até 30 itens |
| `externalIds` | `array<string>` | não | 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. · até 100 itens |
| `phoneNumberIds` | `array<string>` | não | 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. · até 100 itens |
| `headers` | `object` | não | 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. |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Listar os tipos de evento

`GET /v1/webhooks/event-types`

Os tipos de evento que a Luna entrega, e que eventTypes aceita no cadastro e na alteração do endpoint. Cada item traz o type, que é o valor a enviar, uma frase que diz o que o evento é e o grupo a que pertence (group e groupLabel).

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

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-event-types

#### Exemplos de código

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

#### Respostas

**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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

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

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

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

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

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

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

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

### Consultar o endpoint de webhook

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

A configuração do endpoint.

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

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-endpoints-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Alterar o endpoint de webhook

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

Muda a URL, pausa ou retoma o endpoint, ou troca os tipos de evento que ele recebe. Envie url, paused, eventTypes, externalIds, phoneNumberIds, headers ou qualquer combinação: um corpo sem nenhum deles responde 400.

Autenticação: Chave de API. Escopo exigido: `webhooks:write`

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-patch-v1-webhooks-endpoints-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `url` | `string` | não | A URL nova. Passa pela mesma validação do cadastro: https e endereço público. O segredo de assinatura continua o mesmo. · até 2048 caracteres |
| `paused` | `boolean` | não | 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>` | não | 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. · até 30 itens |
| `externalIds` | `array<string>` | não | 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. · até 100 itens |
| `phoneNumberIds` | `array<string>` | não | 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. · até 100 itens |
| `headers` | `object` | não | 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. |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Remover o endpoint de webhook

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

Remove o endpoint. A resposta é 204, e o endpoint deixa de receber eventos.

Autenticação: Chave de API. Escopo exigido: `webhooks:write`

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-delete-v1-webhooks-endpoints-id

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. |

#### Exemplos de código

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

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Listar as entregas do endpoint

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

O histórico das tentativas de entrega ao endpoint nos últimos 7 dias, da mais recente à mais antiga: eventId, eventType, status, httpStatus (nulo quando o seu servidor não respondeu), durationMs, attempt e at. Filtros: status (success ou failed), eventType e since. Não traz o corpo enviado nem o que o seu servidor respondeu.

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

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-endpoints-id-deliveries

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. |

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `limit` | `integer` | não | Quantos itens trazer. Padrão 50, máximo 100, igual para todos. |
| `status` | `string` | não | success: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta. |
| `eventType` | `string` | não | Só as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types). |
| `since` | `any` | não | 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` | não | O nextCursor da página anterior. Omita na primeira. |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Enviar um evento de teste

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

Envia UM evento webhook.test ao endpoint, agora, e devolve o resultado na própria resposta. O evento sai assinado, com os mesmos cabeçalhos, a mesma assinatura e as mesmas defesas de destino de uma entrega real, então um teste que passa prova que a URL e a verificação da assinatura funcionam. Com eventType no corpo, o evento é um exemplo daquele tipo, com corpo de mentira e test: true no envelope.

Autenticação: Chave de API. Escopo exigido: `webhooks:write`

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-endpoints-id-test

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `eventType` | `string` | não | 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. · Valores: 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 |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Rotacionar o segredo de assinatura

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

Emite um segredo novo e devolve ele uma vez. Guarde-o agora, como no cadastro.

Autenticação: Chave de API. Escopo exigido: `webhooks:write`

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-endpoints-id-rotacionar

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `revokePrevious` | `boolean` | não | 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. |

#### Exemplos de código

```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
}'
```

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Listar as entregas que falharam definitivamente

`GET /v1/webhooks/dlq`

Os eventos que a Luna tentou entregar ao seu endpoint e desistiu, do mais recente ao mais antigo, cada um com o número, o rótulo do cliente, as tentativas, o último status HTTP e o que se pode fazer com ele (allowedActions). Filtros: endpointId, externalId e requeued.

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

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-dlq

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `cursor` | `string` | não | O cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página. |
| `limit` | `integer` | não | Quantos itens trazer nesta página. Máximo 100, igual para todos. |
| `endpointId` | `string` | não | Só os itens deste endpoint. |
| `externalId` | `string` | não | 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` | não | true: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions). |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

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

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

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

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

### Re-enfileirar uma entrega que falhou

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

Recoloca o evento na fila de entrega. A resposta é 202: o pedido foi registrado, e a entrega acontece de forma assíncrona.

Autenticação: Chave de API. Escopo exigido: `webhooks:write`

Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-dlq-id-reenfileirar

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | O identificador deste item na fila de rejeitados. |

#### Exemplos de código

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

#### Respostas

**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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

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

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

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

## Chaves

Criar, listar e revogar as credenciais que autenticam as suas chamadas.

### Listar chaves

`GET /v1/api-keys`

As chaves deste cliente, com escopos, perfil, status (active, revoked ou expired), data de criação, último uso, revogação e o que a conta pode fazer com cada uma (allowedActions).

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

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-api-keys

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `kind` | `string` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

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

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

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

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

### Criar uma chave

`POST /v1/api-keys`

Cunha uma chave nova e devolve o segredo uma única vez. Guarde-o no momento em que recebe, porque não há rota que o devolva depois.

Autenticação: Chave de API. Escopo exigido: `keys:write`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-api-keys

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `label` | `string` | não | 1 a 120 caracteres |
| `scopes` | `array<string>` | não | 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. · no mínimo 1 itens |
| `profile` | `string` | não | 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. · Valores: agent, full, read_only |
| `expiresAt` | `string (date-time)` | não |  |
| `mode` | `string` | não | 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. · Valores: live, test |
| `externalId` | `string` | não | 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 a 128 caracteres |

#### Exemplos de código

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

#### Respostas

**201**: Criado.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

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

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

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

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

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

### Listar os escopos que uma chave pode ter

`GET /v1/api-keys/scopes`

Os escopos que uma chave de integração pode receber, cada um com o nome em português, o que ele permite e se dá um poder que exige cuidado.

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

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

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

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

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

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

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

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

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

### Listar os perfis de chave

`GET /v1/api-keys/profiles`

Os perfis prontos de chave (agent, full e read_only) e os escopos que cada um concede. Em POST /v1/api-keys, profile vale no lugar de scopes.

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

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

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

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

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

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

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

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

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

### Consultar uma chave

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

Os metadados de uma chave. O segredo não volta, pelo mesmo motivo descrito na listagem.

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

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

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

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

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

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

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

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

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

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

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

### Revogar uma chave

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

Invalida a chave imediatamente. A operação é idempotente, então revogar de novo devolve o mesmo resultado, sem erro.

Autenticação: Chave de API. Escopo exigido: `keys:write`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-api-keys-id-revoke

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

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

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

## Conta e plano

A conta da credencial, o plano, a capacidade de números e quantos estão em uso no período.

### Consultar o plano e a assinatura

`GET /v1/subscription`

O plano da conta (teste grátis ou contratado), a capacidade de números e quantos estão em uso, e o que é cobrado pela Helsen no período: a capacidade de números ativos, e nada além disso.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-subscription

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `inicio` | `string` | não |  |
| `fim` | `string` | não |  |

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/subscription" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler os limites técnicos da plataforma

`GET /v1/limits`

Os tetos que a API aplica, cada um com o valor, a unidade e o motivo. São iguais para todos os clientes e não dependem do plano: existem por capacidade de infraestrutura ou porque a Meta os impõe. Não são contagem do seu uso e não entram em cobrança.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/limits" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler as regras de preço da Meta

`GET /v1/meta-pricing`

As regras com que a Meta cobra o uso do WhatsApp do negócio dono do número, e o dia em que a Luna as leu. Não traz valor em moeda: a tabela de tarifas fica na Meta. A Luna não cobra nada disto.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/meta-pricing" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler a própria conta

`GET /v1/account`

Devolve a conta da credencial apresentada: identificador, nome, se o e-mail já foi confirmado e quando a conta foi criada.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-account

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/account" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "YOUR_NAME",
  "emailConfirmed": true,
  "createdAt": "YOUR_CREATEDAT",
  "operatorEmail": "YOUR_OPERATOREMAIL"
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Trocar o nome da conta

`PATCH /v1/account`

Troca o nome da conta, o mesmo que GET /v1/account devolve. Devolve a conta já com o nome novo. Só a sessão do console faz isto.

Autenticação: Chave de API. Escopo exigido: `session:end`

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `name` | `string` | sim | O novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro. · 1 a 120 caracteres |

#### Exemplos de código

```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"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "YOUR_NAME",
  "emailConfirmed": true,
  "createdAt": "YOUR_CREATEDAT",
  "operatorEmail": "YOUR_OPERATOREMAIL"
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ver o resumo da conta

`GET /v1/account/overview`

O que a conta precisa olhar agora (avisos em ordem de gravidade), os quatro primeiros passos e os números por estado de conexão. Tudo decidido pela API, para uma tela inicial não precisar calcular nada.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/account/overview" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

## Status

Sondas de disponibilidade e o estado da plataforma. Sem autenticação.

### Verificar se a API está no ar

`GET /healthz`

Responde 200 quando o processo está de pé. Não exige autenticação e não consulta banco nem fila, porque é sonda de processo e não de dependência. Um 200 aqui não promete que o envio de mensagem está funcionando.

Autenticação: Pública, sem chave

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/healthz"
```

#### Respostas

**200**: Sucesso.

### Ver se a Luna está recebendo e entregando

`GET /status`

Responde 200 com o estado da plataforma, medido a cada poucos minutos por uma mensagem sintética que entra pela mesma porta que a Meta usa e precisa chegar a um destino por HTTPS. Não exige autenticação e não revela dado de nenhuma conta. Quando ainda não há verificação recente, o estado é unknown, e nunca ok.

Autenticação: Pública, sem chave

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/status"
```

#### Respostas

**200**: Sucesso.

```json
{
  "status": "ok",
  "checkedAt": "YOUR_CHECKEDAT",
  "components": {
    "ingestion": "ok",
    "delivery": "ok",
    "partitions": "ok"
  },
  "since": "YOUR_SINCE"
}
```

### Apresentar a API

`GET /`

Responde 200 com o nome da API e os endereços da documentação e da especificação OpenAPI. Não exige autenticação e não consulta banco nem fila.

Autenticação: Pública, sem chave

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/"
```

#### Respostas

**200**: Sucesso.

```json
{
  "name": "YOUR_NAME",
  "docs": "YOUR_DOCS",
  "openapi": "YOUR_OPENAPI"
}
```

## Console e páginas públicas

Rotas que o console da Luna e a página pública do link de conexão usam: cadastro, login, sessão e conclusão do fluxo. Você normalmente não precisa delas. Elas existem aqui porque o console é cliente desta mesma API, sem rota privilegiada.

### Ler o link de conexão (página do cliente)

`GET /v1/public/onboarding-links/{token}`

Para a página que o seu cliente abre. Devolve o nome da conta que pediu a conexão, o status do link e os identificadores públicos do aplicativo da Meta que a janela de conexão usa. Nada mais da sua conta sai aqui.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-get-v1-public-onboarding-links-token

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN"
```

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Abrir a sessão de conexão pelo link

`POST /v1/public/onboarding-links/{token}/sessions`

Abre a sessão que a janela da Meta preenche, para a conta dona do link. É a mesma abertura de POST /v1/onboarding/sessions, pela porta do token.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions"
```

#### Respostas

**201**: Criado.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "configId": "YOUR_CONFIGID",
  "sdkVersion": "YOUR_SDKVERSION",
  "csrfState": "YOUR_CSRFSTATE",
  "expiresAt": "YOUR_EXPIRESAT"
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```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**: O link de conexão venceu ou já foi usado. O campo error diz qual dos dois.

```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**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Concluir a conexão pelo link

`POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/complete`

Troca o código da janela da Meta por acesso à conta do cliente. É a mesma conclusão de POST /v1/onboarding/sessions/{id}/complete, pela porta do token, e vale o mesmo aviso: o código dura 30 segundos, então chame no instante em que ele chega.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions-sessionid-complete

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |
| `sessionId` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `code` | `string` | sim |  |
| `csrfState` | `string` | sim |  |
| `wabaId` | `string \| null` | não |  |
| `phoneNumberId` | `string \| null` | não |  |
| `businessId` | `string \| null` | não |  |

#### Exemplos de código

```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"
}'
```

#### Respostas

**200**: Sucesso.

```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**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**410**: O link de conexão venceu ou já foi usado. O campo error diz qual dos dois.

```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**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Registrar abandono ou erro pelo link

`POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon`

Telemetria do que aconteceu na janela da Meta quando o cliente não concluiu. É o mesmo relato de POST /v1/onboarding/sessions/{id}/abandon, pela porta do token, e só vale para uma sessão aberta por este mesmo link.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions-sessionid-abandon

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |
| `sessionId` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `csrfState` | `string` | sim |  |
| `currentStep` | `string \| null` | não | 1 a 120 caracteres |
| `errorCode` | `integer \| null` | não |  |
| `errorMessage` | `string \| null` | não |  |

#### Exemplos de código

```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"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "abandonedAtStep": "YOUR_ABANDONEDATSTEP"
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Criar uma conta

`POST /v1/operators/signup`

Cria a conta e o primeiro operador dela, numa única chamada e sem credencial.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-signup

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `email` | `string` | sim | até 254 caracteres |
| `password` | `string` | sim | 12 a 512 caracteres |
| `tenantName` | `string` | sim | 1 a 120 caracteres |

#### Exemplos de código

```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"
}'
```

#### Respostas

**201**: Criado.

```json
{
  "nextStep": "login"
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Confirmar o e-mail de uma conta

`GET /v1/operators/confirm`

Destino do link enviado por e-mail quando a conta é criada. Ela responde com um redirecionamento para o console, e não com JSON, porque quem a abre é uma pessoa num navegador.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-operators-confirm

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | não |  |

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/operators/confirm"
```

#### Respostas

**200**: Sucesso.

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Pedir a redefinição da senha

`POST /v1/operators/password/forgot`

Pede o envio de um link para escolher uma senha nova. Recebe só o e-mail da conta.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-password-forgot

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `email` | `string` | sim | até 254 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br"
}'
```

#### Respostas

**202**: Aceito: o pedido foi registrado e será processado.

```json
{
  "accepted": true
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Escolher uma senha nova

`POST /v1/operators/password/reset`

Troca a senha do operador a partir do token do link enviado por e-mail, e responde 204.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-password-reset

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim | até 512 caracteres |
| `password` | `string` | sim | 12 a 512 caracteres |

#### Exemplos de código

```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"
}'
```

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Conferir o link de redefinição

`POST /v1/operators/password/reset/check`

Responde 204 quando o token do link ainda vale e 400 quando não vale, sem consumi-lo. Serve para a tela avisar antes de a pessoa digitar a senha nova.

Autenticação: Pública, sem chave

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim | até 512 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset/check" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "YOUR_TOKEN"
}'
```

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler a regra de senha

`GET /v1/public/password-policy`

O comprimento mínimo de uma senha de operador, o mesmo no cadastro, na redefinição e na troca. Não pede credencial.

Autenticação: Pública, sem chave

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/password-policy"
```

#### Respostas

**200**: Sucesso.

```json
{
  "minLength": 12
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Trocar a senha

`POST /v1/operators/password/change`

Troca a senha do operador da sessão apresentada, conferindo a senha atual, e responde 204. As outras sessões do mesmo operador são encerradas e a apresentada continua valendo. Senha atual errada, ou credencial sem operador (chave de integração), responde 401.

Autenticação: Chave de API. Escopo exigido: `session:elevate`

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `currentPassword` | `string` | sim | A senha de hoje do operador da sessão. · até 512 caracteres |
| `newPassword` | `string` | sim | A senha nova, pela mesma regra do cadastro (GET /v1/public/password-policy diz o mínimo). · 12 a 512 caracteres |

#### Exemplos de código

```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"
}'
```

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Reenviar o e-mail de confirmação

`POST /v1/operators/confirmation/resend`

Envia de novo o link de confirmação para o e-mail do operador da sessão, e invalida o link anterior que ainda não tinha sido aberto. O link novo vale por sete dias e é aceito uma única vez.

Autenticação: Chave de API. Escopo exigido: `session:end`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-confirmation-resend

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/confirmation/resend" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**202**: Aceito: o pedido foi registrado e será processado.

```json
{
  "emailConfirmed": true
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Autenticar um operador

`POST /v1/operators/login`

Troca email e senha por uma credencial de sessão de oito horas, usada pelo console web.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-login

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `email` | `string` | sim | 1 a 254 caracteres |
| `password` | `string` | sim | 1 a 512 caracteres |

#### Exemplos de código

```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"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "operatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "YOUR_TOKEN",
  "expiresAt": "YOUR_EXPIRESAT",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Reautenticar para uma ação sensível

`POST /v1/operators/step-up`

Confirma a senha do operador da sessão apresentada e abre uma janela de duas horas em que essa mesma sessão pode criar e revogar chaves de API.

Autenticação: Chave de API. Escopo exigido: `session:elevate`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-step-up

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `password` | `string` | sim | 1 a 512 caracteres |

#### Exemplos de código

```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"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "elevatedUntil": "YOUR_ELEVATEDUNTIL",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler a sessão apresentada

`GET /v1/operators/session`

Quando a credencial apresentada expira, até quando vale a elevação aberta por POST /v1/operators/step-up (nulo sem elevação ou com a janela fechada) e os escopos que ela tem agora. Lê só a própria credencial: o identificador vem da autenticação e nunca do caminho.

Autenticação: Chave de API. Escopo exigido: `session:end`

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/operators/session" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```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**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Encerrar a sessão

`POST /v1/operators/logout`

Revoga a credencial apresentada, e apenas ela. O identificador vem da própria autenticação e nunca do corpo, então esta rota não consegue revogar chave de terceiro.

Autenticação: Chave de API. Escopo exigido: `session:end`

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/logout" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

## Eventos de webhook

A Luna faz POST do evento no endpoint que você cadastrou, com o corpo em application/json e o cabeçalho de assinatura. Responda 2xx para confirmar; qualquer outra resposta, ou nenhuma, conta como falha e é repetida pela política de retentativa. Verifique a assinatura sobre o corpo bruto antes de confiar no conteúdo.

`x-luna-signature`: A assinatura da entrega: t=<segundos desde 1970>,v1=<HMAC-SHA256 em hexadecimal de "<t>.<corpo bruto>"> com o segredo do endpoint. Durante uma rotação de segredo o cabeçalho traz dois valores v1=, e basta um conferir. Rejeite entregas com t fora de 300 segundos do seu relógio.

### Mensagem recebida

`message.received`

Um contato escreveu para um dos seus números. Traz o texto, e o conteúdo quando a mensagem é de outro tipo (mídia, botão clicado, localização, contatos, reação).

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `message` | `object` | sim | 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)` | sim | 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` | sim | O identificador da mensagem na Meta. |
| `message.wa_id` | `string \| null` | sim | 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` | sim | 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` | sim | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. |
| `message.username` | `string \| null` | sim | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. |
| `message.type` | `string` | sim | O tipo da mensagem, no vocabulário da Meta. |
| `message.text` | `string \| null` | sim | 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` | sim | O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou. |
| `message.media` | `object \| null` | sim |  |
| `message.media.mime_type` | `string \| null` | sim | 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` | sim | 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` | sim | A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma. |
| `message.media.filename` | `string \| null` | sim | O nome do arquivo. Só documento tem. |
| `message.media.voice` | `boolean \| null` | sim | Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem. |
| `message.media.animated` | `boolean \| null` | sim | Verdadeiro quando a figurinha é animada. Só figurinha tem. |
| `message.media.url` | `string \| null` | sim | 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` | sim | A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu. |
| `message.interactive.type` | `string \| null` | sim | 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` | sim | O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply. |
| `message.interactive.title` | `string \| null` | sim | O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply. |
| `message.interactive.description` | `string \| null` | sim | A descrição do item da lista. Nula nos demais. |
| `message.interactive.name` | `string \| null` | sim | O nome do Flow. Só em nfm_reply. |
| `message.interactive.response_json` | `string \| null` | sim | As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply. |
| `message.button` | `object \| null` | sim | O clique num botão de resposta rápida de um template. |
| `message.button.payload` | `string \| null` | sim | O payload que você definiu no botão de resposta rápida do template. |
| `message.button.text` | `string \| null` | sim | O texto do botão. |
| `message.location` | `object \| null` | sim | A localização que o interlocutor compartilhou. |
| `message.location.latitude` | `number \| null` | sim | A latitude, em graus decimais. |
| `message.location.longitude` | `number \| null` | sim | A longitude, em graus decimais. |
| `message.location.name` | `string \| null` | sim | O nome do lugar, quando o interlocutor escolheu um. |
| `message.location.address` | `string \| null` | sim | O endereço, quando há. |
| `message.location.url` | `string \| null` | sim | O endereço web do lugar, quando há. |
| `message.contacts` | `array<object> \| null` | sim | Os cartões de contato que o interlocutor compartilhou. |
| `message.contacts[].name` | `object \| null` | sim | O nome do contato, nos campos da Meta. |
| `message.contacts[].name.formatted_name` | `string \| null` | sim |  |
| `message.contacts[].name.first_name` | `string \| null` | sim |  |
| `message.contacts[].name.last_name` | `string \| null` | sim |  |
| `message.contacts[].name.middle_name` | `string \| null` | sim |  |
| `message.contacts[].name.prefix` | `string \| null` | sim |  |
| `message.contacts[].name.suffix` | `string \| null` | sim |  |
| `message.contacts[].phones` | `array<object> \| null` | sim | Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp. |
| `message.contacts[].phones[].phone` | `string \| null` | sim |  |
| `message.contacts[].phones[].wa_id` | `string \| null` | sim |  |
| `message.contacts[].phones[].type` | `string \| null` | sim |  |
| `message.contacts[].emails` | `array<object> \| null` | sim | Os e-mails do contato. |
| `message.contacts[].emails[].email` | `string \| null` | sim |  |
| `message.contacts[].emails[].type` | `string \| null` | sim |  |
| `message.contacts[].org` | `object \| null` | sim | A organização do contato. |
| `message.contacts[].org.company` | `string \| null` | sim |  |
| `message.contacts[].org.department` | `string \| null` | sim |  |
| `message.contacts[].org.title` | `string \| null` | sim |  |
| `message.reaction` | `object \| null` | sim | A reação a uma mensagem, ou a retirada dela. |
| `message.reaction.wamid` | `string \| null` | sim | O wamid da mensagem que recebeu a reação. |
| `message.reaction.emoji` | `string \| null` | sim | O emoji. Nulo quando o interlocutor retirou a reação. |
| `message.context` | `object \| null` | sim | A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada. |
| `message.context.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor citou ao responder. |
| `message.context.from` | `string \| null` | sim | Quem enviou a mensagem citada. |
| `message.context.forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada. |
| `message.context.frequently_forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada muitas vezes. |
| `message.referral` | `object \| null` | sim | O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever. |
| `message.referral.source_type` | `string \| null` | sim | A origem do clique, como ad ou post. |
| `message.referral.source_id` | `string \| null` | sim | O identificador do anúncio ou da publicação na Meta. |
| `message.referral.source_url` | `string \| null` | sim | O endereço do anúncio ou da publicação. |
| `message.referral.headline` | `string \| null` | sim | O título do anúncio. |
| `message.referral.body` | `string \| null` | sim | O texto do anúncio. |
| `message.referral.media_type` | `string \| null` | sim | O tipo da mídia do anúncio, como image ou video. |
| `message.referral.ctwa_clid` | `string \| null` | sim | O identificador do clique, para atribuição de conversão. |
| `message.unsupported` | `object \| null` | sim | 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` | sim | O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte"). |
| `message.unsupported.title` | `string \| null` | sim | O título do erro, como a Meta o mandou. |
| `message.unsupported.details` | `string \| null` | sim | O detalhe do erro, como a Meta o mandou. |
| `message.edit` | `object \| null` | sim | Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit). |
| `message.edit.wamid` | `string \| null` | sim | O wamid da mensagem que foi editada. |
| `message.edit.type` | `string \| null` | sim | O tipo do conteúdo novo, como text. |
| `message.edit.text` | `string \| null` | sim | O texto novo, quando o conteúdo novo é texto. |
| `message.revoke` | `object \| null` | sim | Presente quando o interlocutor apagou uma mensagem para todos (type é revoke). |
| `message.revoke.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor apagou para todos. |
| `message.order` | `object \| null` | sim | O pedido que o interlocutor montou num catálogo e enviou (type é order). |
| `message.order.catalog_id` | `string \| null` | sim | O catálogo de onde veio o pedido. |
| `message.order.text` | `string \| null` | sim | O texto que o interlocutor escreveu junto com o pedido. |
| `message.order.items` | `array<object> \| null` | sim | Os itens do pedido. |
| `message.order.items[].product_retailer_id` | `string \| null` | sim | O identificador do produto no seu catálogo. |
| `message.order.items[].quantity` | `string \| null` | sim | A quantidade pedida, como a Meta mandou. |
| `message.order.items[].item_price` | `string \| null` | sim | O preço unitário, como a Meta mandou. |
| `message.order.items[].currency` | `string \| null` | sim | 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
  }
}
```

### Estado de uma mensagem que você enviou

`message.status`

Uma mensagem que você enviou mudou de estado: sent, delivered, read ou failed. Em failed, o evento traz o erro. Em sent e em um entre delivered e read, traz o pricing: o custo que a Meta aplicou à mensagem, com os nomes dela.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `message` | `object` | sim | Uma mudança de estado de uma mensagem que você enviou. |
| `message.id` | `string (uuid) \| null` | sim | 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` | sim | 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` | sim | O identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id. |
| `message.user_id` | `string \| null` | sim | 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` | sim | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. |
| `message.username` | `string \| null` | sim | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. |
| `message.status` | `string` | sim | O estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer. |
| `message.error_code` | `integer \| null` | sim | O código de erro da Meta quando o estado é de falha. Nulo nos demais. |
| `message.error` | `object \| null` | sim | 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` | sim | O código do erro, como a Meta o informou. |
| `message.error.title` | `string \| null` | sim | O título do erro, como a Meta o informou. |
| `message.error.message` | `string \| null` | sim | A descrição do erro, como a Meta a informou. |
| `message.pricing` | `object \| null` | sim | 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` | sim | 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` | sim | O modelo de preço da Meta, como ela informou (hoje PMP ou CBP). |
| `message.pricing.type` | `string \| null` | sim | 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` | sim | A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer. |
| `message.callback_data` | `string \| null` | sim | 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
  }
}
```

### Contato trocou de telefone ou de BSUID

`contact.identity_changed`

Um contato trocou de telefone (user_changed_number) ou de BSUID (user_changed_user_id). A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `contact` | `object` | sim | 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` | sim | O identificador, na Meta, da mensagem de sistema que avisou a troca. |
| `contact.change_type` | `string` | sim | 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` | sim | 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` | sim | O BSUID do contato depois da troca, como a Meta mandou. |
| `contact.previous_user_id` | `string \| null` | sim | 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` | sim | O BSUID pai do contato depois da troca, quando a Meta o informa. |
| `contact.previous_parent_user_id` | `string \| null` | sim | 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
  }
}
```

### Contato mudou uma preferência

`contact.preferences_changed`

Um contato mudou uma preferência na Meta, hoje a de receber mensagens de marketing: pediu para parar (por exemplo value stop) ou voltou a aceitar. Os valores chegam como a Meta mandou. A Luna não bloqueia nenhum envio por causa do aviso: o seu sistema decide, e deve parar de mandar marketing a quem pediu. Só chega se o campo user_preferences estiver assinado no app da Meta.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `contact` | `object` | sim | Quem mudou a preferência. |
| `contact.wa_id` | `string \| null` | sim | 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` | sim | O BSUID do contato, como a Meta mandou. |
| `contact.parent_user_id` | `string \| null` | sim | O BSUID pai do contato, quando a Meta o informa. |
| `contact.username` | `string \| null` | sim | O nome de usuário do contato, quando ele adotou um. |
| `contact.profile_name` | `string \| null` | sim | O nome que o contato exibe no WhatsApp, quando a Meta o manda. |
| `preference` | `object` | sim | O que mudou. |
| `preference.category` | `string \| null` | sim | A categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer. |
| `preference.value` | `string \| null` | sim | 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` | sim | 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"
  }
}
```

### Eventos descartados por indisponibilidade

`backlog.dropped`

O seu endpoint ficou fora do ar por tempo demais, e a plataforma descartou o que se acumulou. Diz quantos eventos e de que período. O aviso não é descartado junto.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `backlog` | `object` | sim | Eventos que a plataforma descartou sem entregar, e que não serão reenviados. |
| `backlog.motivo` | `string` | sim | 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. · Valores: idade, volume |
| `backlog.quantidade` | `integer` | sim | Quantos eventos foram descartados nesta ocorrência. |
| `backlog.janela_inicio` | `string` | sim | O evento mais antigo descartado nesta ocorrência. |
| `backlog.janela_fim` | `string` | sim | 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"
  }
}
```

### Prazo da importação do histórico se aproximando

`history_sync.deadline_approaching`

Num número conectado em coexistência, a importação das conversas anteriores ainda está em curso e o prazo dela se aproxima. Passado o prazo sem concluir, a Meta desconecta o negócio final.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `history_sync` | `object` | sim | 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` | sim | 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"
  }
}
```

### Evento de teste

`webhook.test`

O evento que POST /v1/webhooks/endpoints/{id}/test envia ao seu endpoint, para você conferir URL e verificação de assinatura. Não passa por nenhum número.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | sim | Sempre null neste tipo: o evento de teste não passa por nenhum número. |
| `test` | `true` | não | 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` | sim | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"webhook.test"` | sim |  |
| `webhook_test` | `object` | sim | 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)` | sim | 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"
  }
}
```

### Resposta dada pelo aplicativo do celular

`message.echo`

O dono do negócio respondeu a um cliente pelo aplicativo WhatsApp Business do celular. Só ocorre em número conectado em coexistência. message.wa_id é o destinatário.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `message` | `object` | sim | 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)` | sim | 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` | sim | O identificador da mensagem na Meta. |
| `message.wa_id` | `string \| null` | sim | 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` | sim | 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` | sim | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. |
| `message.username` | `string \| null` | sim | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. |
| `message.type` | `string` | sim | O tipo da mensagem, no vocabulário da Meta. |
| `message.text` | `string \| null` | sim | 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` | sim | O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou. |
| `message.media` | `object \| null` | sim |  |
| `message.media.mime_type` | `string \| null` | sim | 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` | sim | 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` | sim | A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma. |
| `message.media.filename` | `string \| null` | sim | O nome do arquivo. Só documento tem. |
| `message.media.voice` | `boolean \| null` | sim | Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem. |
| `message.media.animated` | `boolean \| null` | sim | Verdadeiro quando a figurinha é animada. Só figurinha tem. |
| `message.media.url` | `string \| null` | sim | 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` | sim | A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu. |
| `message.interactive.type` | `string \| null` | sim | 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` | sim | O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply. |
| `message.interactive.title` | `string \| null` | sim | O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply. |
| `message.interactive.description` | `string \| null` | sim | A descrição do item da lista. Nula nos demais. |
| `message.interactive.name` | `string \| null` | sim | O nome do Flow. Só em nfm_reply. |
| `message.interactive.response_json` | `string \| null` | sim | As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply. |
| `message.button` | `object \| null` | sim | O clique num botão de resposta rápida de um template. |
| `message.button.payload` | `string \| null` | sim | O payload que você definiu no botão de resposta rápida do template. |
| `message.button.text` | `string \| null` | sim | O texto do botão. |
| `message.location` | `object \| null` | sim | A localização que o interlocutor compartilhou. |
| `message.location.latitude` | `number \| null` | sim | A latitude, em graus decimais. |
| `message.location.longitude` | `number \| null` | sim | A longitude, em graus decimais. |
| `message.location.name` | `string \| null` | sim | O nome do lugar, quando o interlocutor escolheu um. |
| `message.location.address` | `string \| null` | sim | O endereço, quando há. |
| `message.location.url` | `string \| null` | sim | O endereço web do lugar, quando há. |
| `message.contacts` | `array<object> \| null` | sim | Os cartões de contato que o interlocutor compartilhou. |
| `message.contacts[].name` | `object \| null` | sim | O nome do contato, nos campos da Meta. |
| `message.contacts[].name.formatted_name` | `string \| null` | sim |  |
| `message.contacts[].name.first_name` | `string \| null` | sim |  |
| `message.contacts[].name.last_name` | `string \| null` | sim |  |
| `message.contacts[].name.middle_name` | `string \| null` | sim |  |
| `message.contacts[].name.prefix` | `string \| null` | sim |  |
| `message.contacts[].name.suffix` | `string \| null` | sim |  |
| `message.contacts[].phones` | `array<object> \| null` | sim | Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp. |
| `message.contacts[].phones[].phone` | `string \| null` | sim |  |
| `message.contacts[].phones[].wa_id` | `string \| null` | sim |  |
| `message.contacts[].phones[].type` | `string \| null` | sim |  |
| `message.contacts[].emails` | `array<object> \| null` | sim | Os e-mails do contato. |
| `message.contacts[].emails[].email` | `string \| null` | sim |  |
| `message.contacts[].emails[].type` | `string \| null` | sim |  |
| `message.contacts[].org` | `object \| null` | sim | A organização do contato. |
| `message.contacts[].org.company` | `string \| null` | sim |  |
| `message.contacts[].org.department` | `string \| null` | sim |  |
| `message.contacts[].org.title` | `string \| null` | sim |  |
| `message.reaction` | `object \| null` | sim | A reação a uma mensagem, ou a retirada dela. |
| `message.reaction.wamid` | `string \| null` | sim | O wamid da mensagem que recebeu a reação. |
| `message.reaction.emoji` | `string \| null` | sim | O emoji. Nulo quando o interlocutor retirou a reação. |
| `message.context` | `object \| null` | sim | A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada. |
| `message.context.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor citou ao responder. |
| `message.context.from` | `string \| null` | sim | Quem enviou a mensagem citada. |
| `message.context.forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada. |
| `message.context.frequently_forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada muitas vezes. |
| `message.referral` | `object \| null` | sim | O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever. |
| `message.referral.source_type` | `string \| null` | sim | A origem do clique, como ad ou post. |
| `message.referral.source_id` | `string \| null` | sim | O identificador do anúncio ou da publicação na Meta. |
| `message.referral.source_url` | `string \| null` | sim | O endereço do anúncio ou da publicação. |
| `message.referral.headline` | `string \| null` | sim | O título do anúncio. |
| `message.referral.body` | `string \| null` | sim | O texto do anúncio. |
| `message.referral.media_type` | `string \| null` | sim | O tipo da mídia do anúncio, como image ou video. |
| `message.referral.ctwa_clid` | `string \| null` | sim | O identificador do clique, para atribuição de conversão. |
| `message.unsupported` | `object \| null` | sim | 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` | sim | O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte"). |
| `message.unsupported.title` | `string \| null` | sim | O título do erro, como a Meta o mandou. |
| `message.unsupported.details` | `string \| null` | sim | O detalhe do erro, como a Meta o mandou. |
| `message.edit` | `object \| null` | sim | Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit). |
| `message.edit.wamid` | `string \| null` | sim | O wamid da mensagem que foi editada. |
| `message.edit.type` | `string \| null` | sim | O tipo do conteúdo novo, como text. |
| `message.edit.text` | `string \| null` | sim | O texto novo, quando o conteúdo novo é texto. |
| `message.revoke` | `object \| null` | sim | Presente quando o interlocutor apagou uma mensagem para todos (type é revoke). |
| `message.revoke.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor apagou para todos. |
| `message.order` | `object \| null` | sim | O pedido que o interlocutor montou num catálogo e enviou (type é order). |
| `message.order.catalog_id` | `string \| null` | sim | O catálogo de onde veio o pedido. |
| `message.order.text` | `string \| null` | sim | O texto que o interlocutor escreveu junto com o pedido. |
| `message.order.items` | `array<object> \| null` | sim | Os itens do pedido. |
| `message.order.items[].product_retailer_id` | `string \| null` | sim | O identificador do produto no seu catálogo. |
| `message.order.items[].quantity` | `string \| null` | sim | A quantidade pedida, como a Meta mandou. |
| `message.order.items[].item_price` | `string \| null` | sim | O preço unitário, como a Meta mandou. |
| `message.order.items[].currency` | `string \| null` | sim | 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
  }
}
```

### Estado de um template mudou

`template.status`

A Meta aprovou, rejeitou, pausou ou desativou um template, e quando houver motivo ele vem junto. Não tem número nem mensagem.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | sim | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. |
| `test` | `true` | não | 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` | sim | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"template.status"` | sim |  |
| `template` | `object` | sim | 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)` | sim | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. |
| `template.name` | `string` | sim | O nome do template. |
| `template.language` | `string` | sim | O idioma do template, no código da Meta. |
| `template.waba_id` | `string` | sim | 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` | sim | 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` | sim | O novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer. |
| `template.category` | `string` | sim | A categoria do template, no vocabulário da Meta. |
| `template.reason` | `string \| null` | sim | 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"
  }
}
```

### Número conectado

`number.connected`

Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão que você abriu com o link de conexão, e traz o externalId dele.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | 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"` | sim |  |

```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
  }
}
```

### Número aguardando método de pagamento na Meta

`number.payment_required`

A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). Sai uma vez ao entrar no estado, e não a cada mensagem recusada. Quem resolve é o dono da conta, no WhatsApp Manager da Meta: a Luna não intermedeia esse pagamento. O guia Pagamento na Meta explica o que dizer ao seu cliente.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | 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"` | sim |  |

```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"
  }
}
```

### Número voltou a enviar depois da espera por pagamento

`number.payment_resolved`

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.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |

```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"
  }
}
```

### Conta restrita pela Meta

`account.restricted`

A Meta restringiu a conta de WhatsApp Business do número. Traz o tipo, o prazo e a orientação da Meta em restrictions. O aviso é 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. O guia Saúde da conta explica cada caso.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `waba` | `object` | sim | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | sim | 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>` | sim | As restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar. |
| `waba.restrictions[].restriction_type` | `string \| null` | sim | O tipo da restrição, no vocabulário da Meta. |
| `waba.restrictions[].expiration` | `string \| null` | sim | Quando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo. |
| `waba.restrictions[].remediation` | `string \| null` | sim | 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
      }
    ]
  }
}
```

### Violação de política na conta

`account.violation`

A Meta registrou uma violação de política na conta de WhatsApp Business do número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. Sai um evento por número da conta.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `waba` | `object` | sim | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | sim | 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` | sim | 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"
  }
}
```

### Conta desativada pela Meta

`account.disabled`

A Meta desativou a conta de WhatsApp Business do número, e os envios deixam de ser aceitos. A Luna não reativa conta: o dono pede revisão à Meta. Sai um evento por número da conta, e account.reinstated avisa se a conta voltar.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `waba` | `object` | sim | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | sim | 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` | sim | 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"
  }
}
```

### Conta reativada pela Meta

`account.reinstated`

A Meta reativou a conta de WhatsApp Business do número depois de uma desativação. Sai um evento por número da conta.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `waba` | `object` | sim | A Meta reativou a conta de WhatsApp Business deste número depois de uma desativação. |
| `waba.waba_id` | `string` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | sim | 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` | sim | 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
  }
}
```

### Outro aviso de conta da Meta

`account.update`

Um aviso de conta da Meta que a Luna não traduz em tipo próprio, com o campo event cru dela (por exemplo ACCOUNT_DELETED, ACCOUNT_RECONNECTED ou VOLUME_BASED_PRICING_TIER_UPDATE). Se você não usa, ignore.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `waba` | `object` | sim | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | 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": {}
  }
}
```

### Limite da conta mudou

`account.limit_changed`

A Meta mudou o limite da conta: o limite de mensagens, que conta pessoas únicas fora da janela de atendimento (TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED), ou o de números. É o teto concedido, e nunca quanto foi usado. Vale para o portfólio inteiro, então sai um evento por número da conta.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `waba` | `object` | sim | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | 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
  }
}
```

### Número desconectado

`number.disconnected`

O número deixou de estar conectado à Luna: o cliente removeu o aplicativo, a Luna foi removida como parceira da conta, o vínculo da conta com a Luna foi encerrado, ou você o desconectou com DELETE /v1/numbers/{id} (reason requested_by_tenant). É o par de number.connected. Para voltar, o seu cliente conecta de novo com um novo link de conexão. Traz o motivo no campo reason.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | 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` | sim | O motivo que a Meta informou em disconnection_info, quando informa. |
| `number.initiated_by` | `string \| null` | sim | Quem iniciou a desconexão, como a Meta informou. |
| `event_type` | `"number.disconnected"` | sim |  |

```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
  }
}
```

### Qualidade do número mudou

`number.quality_changed`

A avaliação de qualidade do número mudou (GREEN, YELLOW, RED). A Meta não tem webhook para isso: a Luna confere a qualidade periodicamente, então o evento chega com atraso de até cerca de uma hora. O histórico está em GET /v1/numbers/{id}/health.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | A avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED. |
| `number.quality_rating` | `string` | sim | A avaliação de qualidade atual, no vocabulário da Meta. |
| `event_type` | `"number.quality_changed"` | sim |  |

```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"
  }
}
```

### Nome de exibição revisado

`number.display_name_reviewed`

O estado da revisão do nome de exibição do número mudou (status: approved, pending_review, declined, expired ou none), por exemplo de pending_review para approved ou declined. name é o nome a que o estado se refere. A Meta não informa o motivo de uma recusa nesta consulta. A Luna confere o nome 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}.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | 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` | sim | 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"` | sim |  |

```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"
  }
}
```

### Autorização do cliente perto de vencer

`number.credential_expiring`

A autorização que o cliente deu à Luna para operar o número vence em até 14 dias (credential_expires_at). Para renovar, o cliente refaz a conexão: crie um link com POST /v1/onboarding/links informando numberId e ele abre direto a reconexão deste número, sem contar um número novo. Sai uma vez por vencimento e por número da conta. Autorização emitida sem prazo nunca gera este evento.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | 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"` | sim |  |

```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"
  }
}
```

### Alerta da Meta sobre a conta

`account.alert`

A Meta mandou um alerta sobre a conta de WhatsApp Business do número (o campo account_alerts), por exemplo a negativa de um aumento de limite ou a perda da foto de perfil. 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.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `waba` | `object` | sim | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `waba.external_id` | `string \| null` | sim | 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` | sim | 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` | sim | O identificador, na Meta, do que o alerta cita. |
| `waba.alert_severity` | `string \| null` | sim | A gravidade que a Meta atribuiu ao alerta, no vocabulário dela. |
| `waba.alert_status` | `string \| null` | sim | Se o alerta está ativo ou foi resolvido, no vocabulário da Meta. |
| `waba.alert_type` | `string \| null` | sim | 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` | sim | A descrição do alerta, em texto, como a Meta mandou. |
| `waba.details` | `object` | sim | 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": {}
  }
}
```

### Número precisa de ação

`number.action_required`

Este número passou a precisar de uma ação sua ou do seu cliente: autorização do cliente vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Traz status, can_send e reasons, cada motivo com code, message e solution, prontos para você mostrar ao seu cliente. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela; é o mesmo cálculo de connection em GET /v1/numbers/{id}. Quando a lista esvazia, sai number.action_resolved.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}. · Valores: connected, connecting, action_required, disconnected |
| `number.can_send` | `boolean` | sim | Se o envio por este número vai funcionar agora, o mesmo de connection.canSend. |
| `number.reasons` | `array<object>` | sim | Os motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento. · no mínimo 1 itens |
| `number.reasons[].code` | `string` | sim | 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` | sim | O que está acontecendo, em português, pronto para repassar ao seu cliente. |
| `number.reasons[].solution` | `string` | sim | O que fazer a respeito, em português. |
| `event_type` | `"number.action_required"` | sim |  |

```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."
      }
    ]
  }
}
```

### Número não precisa mais de ação

`number.action_resolved`

O número deixou de precisar 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. Um número que você desconectou não gera este evento: number.disconnected já avisou.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}. · Valores: connected, connecting, action_required, disconnected |
| `number.can_send` | `boolean` | sim | Se o envio por este número vai funcionar agora, o mesmo de connection.canSend. |
| `event_type` | `"number.action_resolved"` | sim |  |

```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
  }
}
```

### Link de conexão concluído

`onboarding.link.completed`

O seu cliente concluiu a conexão por um link: o link passa a used. Traz o externalId do link e, quando a Luna já registrou o número, number_id; o evento number.connected avisa quando o número fica pronto para enviar. Sai uma vez por link.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | sim | 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 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. |
| `number.external_id` | `string \| null` | sim | 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` | sim | 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"` | sim |  |
| `link` | `object` | sim | 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)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | sim | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. |
| `link.used_at` | `string` | sim | Quando a conexão por este link concluiu, o mesmo usedAt de GET /v1/onboarding/links/{id}. |
| `link.waba_id` | `string \| null` | sim | 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` | sim | 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"
  }
}
```

### Link de conexão aberto

`onboarding.link.opened`

O seu cliente abriu o link pela primeira vez. Sai uma vez por link, e não de novo quando ele volta à página ou tenta outra vez. Traz o externalId do link e opened_at. É o começo do ciclo: depois vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | sim | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `link` | `object` | sim | 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)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | sim | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. |
| `link.opened_at` | `string` | sim | 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"
  }
}
```

### Tentativa de conexão pelo link não deu certo

`onboarding.link.failed`

Uma tentativa de conexão por um link não deu certo. reason diz por quê: abandoned (o cliente fechou a janela da Meta, e step traz a tela em que parou), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir e não conseguiu), country_not_supported (o número não é +55) ou registration_blocked (a Meta bloqueou o registro por 72 horas). O link continua aberto até vencer. Sai uma vez por tentativa.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | sim | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `link` | `object` | sim | 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)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | sim | 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)` | sim | A tentativa de conexão que não deu certo. Um link aberto admite várias. |
| `link.reason` | `string` | sim | 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. · Valores: abandoned, error, failed, country_not_supported, registration_blocked |
| `link.step` | `string \| null` | sim | 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` | sim | 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
  }
}
```

### Link de conexão venceu

`onboarding.link.expired`

O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link usado nunca gera este evento. Sai uma vez por link.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `string \| null` | sim | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `test` | `true` | não | 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` | sim | 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)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. |
| `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |
| `number.external_id` | `string \| null` | sim | 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"` | sim |  |
| `link` | `object` | sim | 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)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. |
| `link.external_id` | `string \| null` | sim | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. |
| `link.expired_at` | `string` | sim | 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"
  }
}
```

### Categoria de um template mudou

`template.category`

A Meta mudou, ou avisou que vai mudar, a categoria de um template. A categoria define o preço que a Meta cobra do negócio: de UTILITY para MARKETING, o preço sobe. Chega como aviso prévio (correct_category e scheduled_for) e como mudança feita (previous_category e new_category). Não tem número nem mensagem.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | sim | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. |
| `test` | `true` | não | 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` | sim | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"template.category"` | sim |  |
| `template` | `object` | sim | 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)` | sim | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. |
| `template.name` | `string` | sim | O nome do template. |
| `template.language` | `string` | sim | O idioma do template, no código da Meta. |
| `template.waba_id` | `string` | sim | 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` | sim | 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` | sim | A categoria do template, no vocabulário da Meta. |
| `template.previous_category` | `string \| null` | sim | A categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio. |
| `template.new_category` | `string \| null` | sim | A categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio. |
| `template.correct_category` | `string \| null` | sim | 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` | sim | 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
  }
}
```

### Qualidade de um template mudou

`template.quality`

A nota de qualidade de um template mudou (GREEN, YELLOW, RED). Nota baixa antecede a pausa do template pela Meta. Não tem número nem mensagem.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `version` | `"2026-11-10"` | sim | 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` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres |
| `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. |
| `phone_number_id` | `null` | sim | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. |
| `test` | `true` | não | 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` | sim | Sempre null neste tipo: o evento não passa por um número. |
| `event_type` | `"template.quality"` | sim |  |
| `template` | `object` | sim | 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)` | sim | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. |
| `template.name` | `string` | sim | O nome do template. |
| `template.language` | `string` | sim | O idioma do template, no código da Meta. |
| `template.waba_id` | `string` | sim | 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` | sim | 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` | sim | A nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN. |
| `template.new_quality_score` | `string \| null` | sim | 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"
  }
}
```

## Erros

| Status HTTP | Descrição |
| --- | --- |
| `400` | O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. |
| `401` | A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. |
| `403` | A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. |
| `404` | O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. |
| `409` | O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. |
| `410` | O link de conexão venceu ou já foi usado. O campo error diz qual dos dois. |
| `413` | O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes. |
| `415` | O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. |
| `422` | O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. |
| `429` | Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. |
| `503` | A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. |

| Código do erro (error) | Status HTTP | Quando acontece |
| --- | --- | --- |
| `invalid_request` | 400 | Campo recusado, com o motivo |
| `invalid_reset_token` | 400 | Link de redefinição inválido |
| `unauthorized` | 401 | Chave recusada |
| `account_blocked` | 403 | Conta bloqueada pela Helsen |
| `connection_not_released` | 403 | Conta ainda sem liberação para conectar |
| `forbidden` | 403 | Escopo insuficiente |
| `test_key_not_allowed` | 403 | Chave de teste numa rota que não é do modo de teste |
| `trial_expired` | 403 | Teste grátis terminado |
| `not_found` | 404 | Não existe, ou não é seu |
| `account_at_capacity` | 409 | A conta que pediu o link atingiu o máximo de números |
| `already_requeued` | 409 | Item já re-enfileirado |
| `idempotency_key_reused` | 409 | Idempotency-Key usada com outro corpo |
| `link_not_open` | 409 | Link que não está aberto |
| `media_not_ready` | 409 | Mídia ainda não obtida |
| `message_not_cancelable` | 409 | Mensagem que já saiu da fila |
| `no_webhook_endpoint` | 409 | Sem endpoint de webhook ativo |
| `not_available_in_coexistence` | 409 | Indisponível em coexistência |
| `number_capacity_reached` | 409 | A conta já está na capacidade de números |
| `number_disconnected` | 409 | Número desconectado da Luna |
| `pin_not_applicable` | 409 | O número não pede PIN |
| `reconnect_not_applicable` | 409 | A autorização não admite reconexão |
| `register_budget_reserved` | 409 | Tentativas de registro reservadas |
| `template_content_unknown` | 409 | A Luna não conhece o conteúdo do template |
| `template_not_approved` | 409 | Template que ainda não está aprovado |
| `webhook_endpoint_limit` | 409 | Limite de endpoints |
| `window_closed` | 409 | Janela de atendimento fechada |
| `link_expired` | 410 | Link vencido |
| `link_used` | 410 | Link já usado |
| `file_too_large` | 413 | Arquivo acima do teto |
| `unsupported_media_type` | 415 | Tipo de conteúdo não lido |
| `meta_rejected` | 422 | A Meta recusou a operação |
| `management_busy` | 429 | Gestão da conta ocupada |
| `number_rate_limited` | 429 | Ritmo do número |
| `queue_full` | 429 | Fila de envio cheia |
| `rate_limited` | 429 | Limite de requisições |
| `unavailable` | 503 | Indisponível |
