# Mensagens

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