# Webhook events

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

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

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

### Message received

`message.received`

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

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

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

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

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

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

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

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

### State of a message you sent

`message.status`

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

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

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

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

### Contact changed phone number or BSUID

`contact.identity_changed`

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

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

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

### Contact changed a preference

`contact.preferences_changed`

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

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

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

### Events dropped by unavailability

`backlog.dropped`

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

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

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

### History import deadline approaching

`history_sync.deadline_approaching`

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

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

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

### Test event

`webhook.test`

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

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

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

### Reply sent from the phone app

`message.echo`

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

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

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

### A template changed state

`template.status`

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

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

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

### Number connected

`number.connected`

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

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

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

### Number waiting for a payment method at Meta

`number.payment_required`

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

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

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

### Number sending again after the payment wait

`number.payment_resolved`

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

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

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

### Account restricted by Meta

`account.restricted`

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

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

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

### Policy violation on the account

`account.violation`

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

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

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

### Account disabled by Meta

`account.disabled`

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

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

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

### Account reinstated by Meta

`account.reinstated`

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

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

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

### Another account notice from Meta

`account.update`

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

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

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

### Account limit changed

`account.limit_changed`

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

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

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

### Number disconnected

`number.disconnected`

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

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

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

### Number quality changed

`number.quality_changed`

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

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

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

### Display name reviewed

`number.display_name_reviewed`

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

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

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

### Customer authorization about to expire

`number.credential_expiring`

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

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

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

### Alert from Meta about the account

`account.alert`

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

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

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

### Number needs action

`number.action_required`

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

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

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

### Number no longer needs action

`number.action_resolved`

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

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

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

### Connect link completed

`onboarding.link.completed`

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

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

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

### Connect link opened

`onboarding.link.opened`

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

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

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

### A connect link attempt did not work out

`onboarding.link.failed`

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

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

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

### Connect link expired

`onboarding.link.expired`

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

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

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

### A template category changed

`template.category`

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

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

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

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

### A template quality changed

`template.quality`

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

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

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