# Messages

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

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

### List messages

`GET /v1/messages`

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

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

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

#### Query parameters

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

#### Code examples

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

#### Responses

**200**: Success.

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

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

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

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

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

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

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

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

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

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

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

### Send a text message

`POST /v1/messages`

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

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

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

#### Request body

`application/json`

Shape 1: `type = "text"`

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

Shape 2: `type = "image"`

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

Shape 3: `type = "video"`

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

Shape 4: `type = "audio"`

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

Shape 5: `type = "document"`

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

Shape 6: `type = "sticker"`

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

Shape 7: `type = "location"`

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

Shape 8: `type = "contacts"`

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

Shape 9: `type = "reaction"`

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

Shape 10: `type = "interactive"`

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

Shape 11: `type = "template"`

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

#### Code examples

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

#### Responses

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Mark a message as read

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

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

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

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

#### Path parameters

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

#### Code examples

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

#### Responses

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

```json
{}
```

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

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

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

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

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

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

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

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

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

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

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

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

### Show the typing indicator

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

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

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

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

#### Path parameters

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

#### Code examples

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

#### Responses

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

```json
{}
```

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

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

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

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

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

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

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

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

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

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

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

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

### Read one message's state

`GET /v1/messages/{id}`

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

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

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

#### Path parameters

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

#### Code examples

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

#### Responses

**200**: Success.

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

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

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

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

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

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

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

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

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

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

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

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

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

### Cancel a message in the queue

`DELETE /v1/messages/{id}`

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

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

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

#### Path parameters

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

#### Code examples

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

#### Responses

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Replay a message's webhook

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

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

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

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

#### Path parameters

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

#### Code examples

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

#### Responses

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

```json
{
  "deliveryId": "9f2a1b0c-3d4e-4f5a-8b9c-0d1e2f3a4b5c",
  "requestedAt": "2026-08-26T18:30:00.000Z"
}
```

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

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

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

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

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

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

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

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

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

```json
{
  "error": "no_webhook_endpoint",
  "docsUrl": "https://lunahia.com.br/docs/receber-eventos",
  "message": "Não há endpoint de webhook ativo para entregar este reenvio. Cadastre um em POST /v1/webhooks/endpoints, ou retome um pausado em PATCH /v1/webhooks/endpoints/{id}, e peça de novo."
}
```

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

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

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

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

### Simulate a received message

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

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

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

#### Request body

`application/json`

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

#### Code examples

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

#### Responses

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

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

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

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

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

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

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

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

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

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

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

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

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

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