# Eventos de webhook

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

A Luna faz POST do evento no endpoint que você cadastrou, com o corpo em application/json e o cabeçalho de assinatura. Responda 2xx para confirmar; qualquer outra resposta, ou nenhuma, conta como falha e é repetida pela política de retentativa. Verifique a assinatura sobre o corpo bruto antes de confiar no conteúdo.

`x-luna-signature`: A assinatura da entrega: t=<segundos desde 1970>,v1=<HMAC-SHA256 em hexadecimal de "<t>.<corpo bruto>"> com o segredo do endpoint. Durante uma rotação de segredo o cabeçalho traz dois valores v1=, e basta um conferir. Rejeite entregas com t fora de 300 segundos do seu relógio.

### Mensagem recebida

`message.received`

Um contato escreveu para um dos seus números. Traz o texto, e o conteúdo quando a mensagem é de outro tipo (mídia, botão clicado, localização, contatos, reação).

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

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

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

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

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

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

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

### Estado de uma mensagem que você enviou

`message.status`

Uma mensagem que você enviou mudou de estado: sent, delivered, read ou failed. Em failed, o evento traz o erro. Em sent e em um entre delivered e read, traz o pricing: o custo que a Meta aplicou à mensagem, com os nomes dela.

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

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

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

### Contato trocou de telefone ou de BSUID

`contact.identity_changed`

Um contato trocou de telefone (user_changed_number) ou de BSUID (user_changed_user_id). A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro.

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

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

### Contato mudou uma preferência

`contact.preferences_changed`

Um contato mudou uma preferência na Meta, hoje a de receber mensagens de marketing: pediu para parar (por exemplo value stop) ou voltou a aceitar. Os valores chegam como a Meta mandou. A Luna não bloqueia nenhum envio por causa do aviso: o seu sistema decide, e deve parar de mandar marketing a quem pediu. Só chega se o campo user_preferences estiver assinado no app da Meta.

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

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

### Eventos descartados por indisponibilidade

`backlog.dropped`

O seu endpoint ficou fora do ar por tempo demais, e a plataforma descartou o que se acumulou. Diz quantos eventos e de que período. O aviso não é descartado junto.

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

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

### Prazo da importação do histórico se aproximando

`history_sync.deadline_approaching`

Num número conectado em coexistência, a importação das conversas anteriores ainda está em curso e o prazo dela se aproxima. Passado o prazo sem concluir, a Meta desconecta o negócio final.

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

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

### Evento de teste

`webhook.test`

O evento que POST /v1/webhooks/endpoints/{id}/test envia ao seu endpoint, para você conferir URL e verificação de assinatura. Não passa por nenhum número.

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

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

### Resposta dada pelo aplicativo do celular

`message.echo`

O dono do negócio respondeu a um cliente pelo aplicativo WhatsApp Business do celular. Só ocorre em número conectado em coexistência. message.wa_id é o destinatário.

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

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

### Estado de um template mudou

`template.status`

A Meta aprovou, rejeitou, pausou ou desativou um template, e quando houver motivo ele vem junto. Não tem número nem mensagem.

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

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

### Número conectado

`number.connected`

Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão que você abriu com o link de conexão, e traz o externalId dele.

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

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

### Número aguardando método de pagamento na Meta

`number.payment_required`

A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). Sai uma vez ao entrar no estado, e não a cada mensagem recusada. Quem resolve é o dono da conta, no WhatsApp Manager da Meta: a Luna não intermedeia esse pagamento. O guia Pagamento na Meta explica o que dizer ao seu cliente.

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

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

### Número voltou a enviar depois da espera por pagamento

`number.payment_resolved`

Um envio deste número voltou a ser aceito pela Meta depois de uma espera por método de pagamento. É o único sinal de que o pagamento foi regularizado: a Meta não avisa e não oferece consulta. As mensagens recusadas durante a espera não são reenviadas sozinhas.

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

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

### Conta restrita pela Meta

`account.restricted`

A Meta restringiu a conta de WhatsApp Business do número. Traz o tipo, o prazo e a orientação da Meta em restrictions. O aviso é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. Quem resolve é o dono da conta, no WhatsApp Manager. O guia Saúde da conta explica cada caso.

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

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

### Violação de política na conta

`account.violation`

A Meta registrou uma violação de política na conta de WhatsApp Business do número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. Sai um evento por número da conta.

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

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

### Conta desativada pela Meta

`account.disabled`

A Meta desativou a conta de WhatsApp Business do número, e os envios deixam de ser aceitos. A Luna não reativa conta: o dono pede revisão à Meta. Sai um evento por número da conta, e account.reinstated avisa se a conta voltar.

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

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

### Conta reativada pela Meta

`account.reinstated`

A Meta reativou a conta de WhatsApp Business do número depois de uma desativação. Sai um evento por número da conta.

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

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

### Outro aviso de conta da Meta

`account.update`

Um aviso de conta da Meta que a Luna não traduz em tipo próprio, com o campo event cru dela (por exemplo ACCOUNT_DELETED, ACCOUNT_RECONNECTED ou VOLUME_BASED_PRICING_TIER_UPDATE). Se você não usa, ignore.

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

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

### Limite da conta mudou

`account.limit_changed`

A Meta mudou o limite da conta: o limite de mensagens, que conta pessoas únicas fora da janela de atendimento (TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED), ou o de números. É o teto concedido, e nunca quanto foi usado. Vale para o portfólio inteiro, então sai um evento por número da conta.

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

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

### Número desconectado

`number.disconnected`

O número deixou de estar conectado à Luna: o cliente removeu o aplicativo, a Luna foi removida como parceira da conta, o vínculo da conta com a Luna foi encerrado, ou você o desconectou com DELETE /v1/numbers/{id} (reason requested_by_tenant). É o par de number.connected. Para voltar, o seu cliente conecta de novo com um novo link de conexão. Traz o motivo no campo reason.

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

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

### Qualidade do número mudou

`number.quality_changed`

A avaliação de qualidade do número mudou (GREEN, YELLOW, RED). A Meta não tem webhook para isso: a Luna confere a qualidade periodicamente, então o evento chega com atraso de até cerca de uma hora. O histórico está em GET /v1/numbers/{id}/health.

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

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

### Nome de exibição revisado

`number.display_name_reviewed`

O estado da revisão do nome de exibição do número mudou (status: approved, pending_review, declined, expired ou none), por exemplo de pending_review para approved ou declined. name é o nome a que o estado se refere. A Meta não informa o motivo de uma recusa nesta consulta. A Luna confere o nome periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo. O estado corrente está em displayNameStatus, em GET /v1/numbers/{id}.

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

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

### Autorização do cliente perto de vencer

`number.credential_expiring`

A autorização que o cliente deu à Luna para operar o número vence em até 14 dias (credential_expires_at). Para renovar, o cliente refaz a conexão: crie um link com POST /v1/onboarding/links informando numberId e ele abre direto a reconexão deste número, sem contar um número novo. Sai uma vez por vencimento e por número da conta. Autorização emitida sem prazo nunca gera este evento.

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

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

### Alerta da Meta sobre a conta

`account.alert`

A Meta mandou um alerta sobre a conta de WhatsApp Business do número (o campo account_alerts), por exemplo a negativa de um aumento de limite ou a perda da foto de perfil. Os campos chegam como a Meta mandou, sem tradução. O alerta é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id.

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

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

### Número precisa de ação

`number.action_required`

Este número passou a precisar de uma ação sua ou do seu cliente: autorização do cliente vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Traz status, can_send e reasons, cada motivo com code, message e solution, prontos para você mostrar ao seu cliente. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela; é o mesmo cálculo de connection em GET /v1/numbers/{id}. Quando a lista esvazia, sai number.action_resolved.

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

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

### Número não precisa mais de ação

`number.action_resolved`

O número deixou de precisar de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou. Um número que você desconectou não gera este evento: number.disconnected já avisou.

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

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

### Link de conexão concluído

`onboarding.link.completed`

O seu cliente concluiu a conexão por um link: o link passa a used. Traz o externalId do link e, quando a Luna já registrou o número, number_id; o evento number.connected avisa quando o número fica pronto para enviar. Sai uma vez por link.

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

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

### Link de conexão aberto

`onboarding.link.opened`

O seu cliente abriu o link pela primeira vez. Sai uma vez por link, e não de novo quando ele volta à página ou tenta outra vez. Traz o externalId do link e opened_at. É o começo do ciclo: depois vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed.

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

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

### Tentativa de conexão pelo link não deu certo

`onboarding.link.failed`

Uma tentativa de conexão por um link não deu certo. reason diz por quê: abandoned (o cliente fechou a janela da Meta, e step traz a tela em que parou), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir e não conseguiu), country_not_supported (o número não é +55) ou registration_blocked (a Meta bloqueou o registro por 72 horas). O link continua aberto até vencer. Sai uma vez por tentativa.

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

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

### Link de conexão venceu

`onboarding.link.expired`

O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link usado nunca gera este evento. Sai uma vez por link.

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

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

### Categoria de um template mudou

`template.category`

A Meta mudou, ou avisou que vai mudar, a categoria de um template. A categoria define o preço que a Meta cobra do negócio: de UTILITY para MARKETING, o preço sobe. Chega como aviso prévio (correct_category e scheduled_for) e como mudança feita (previous_category e new_category). Não tem número nem mensagem.

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

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

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

### Qualidade de um template mudou

`template.quality`

A nota de qualidade de um template mudou (GREEN, YELLOW, RED). Nota baixa antecede a pausa do template pela Meta. Não tem número nem mensagem.

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

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