LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Webhook events

Use with AI

Luna delivers each event by POST to the endpoint you registered. Each type below carries the body schema and an example. A new event type does not change the contract version: ignore the types you do not know.

The Receive events guide explains the signature, the retries and how to handle each type.

How Luna delivers#

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

EVENTmessage.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).

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • messageobjectrequired
    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.idstring (uuid)required
    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.wamidstringrequired
    O identificador da mensagem na Meta.
  • message.wa_idstring | nullrequired
    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_idstring | nullrequired
    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_idstring | nullrequired
    O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.
  • message.usernamestring | nullrequired
    O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.
  • message.typestringrequired
    O tipo da mensagem, no vocabulário da Meta.
  • message.textstring | nullrequired
    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_namestring | nullrequired
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • message.mediaobject | nullrequired
  • message.media.mime_typestring | nullrequired
    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.sha256string | nullrequired
    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.captionstring | nullrequired
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • message.media.filenamestring | nullrequired
    O nome do arquivo. Só documento tem.
  • message.media.voiceboolean | nullrequired
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • message.media.animatedboolean | nullrequired
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • message.media.urlstring | nullrequired
    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.interactiveobject | nullrequired
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • message.interactive.typestring | nullrequired
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • message.interactive.idstring | nullrequired
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • message.interactive.titlestring | nullrequired
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • message.interactive.descriptionstring | nullrequired
    A descrição do item da lista. Nula nos demais.
  • message.interactive.namestring | nullrequired
    O nome do Flow. Só em nfm_reply.
  • message.interactive.response_jsonstring | nullrequired
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • message.buttonobject | nullrequired
    O clique num botão de resposta rápida de um template.
  • message.button.payloadstring | nullrequired
    O payload que você definiu no botão de resposta rápida do template.
  • message.button.textstring | nullrequired
    O texto do botão.
  • message.locationobject | nullrequired
    A localização que o interlocutor compartilhou.
  • message.location.latitudenumber | nullrequired
    A latitude, em graus decimais.
  • message.location.longitudenumber | nullrequired
    A longitude, em graus decimais.
  • message.location.namestring | nullrequired
    O nome do lugar, quando o interlocutor escolheu um.
  • message.location.addressstring | nullrequired
    O endereço, quando há.
  • message.location.urlstring | nullrequired
    O endereço web do lugar, quando há.
  • message.contactsarray<object> | nullrequired
    Os cartões de contato que o interlocutor compartilhou.
  • message.contacts[].nameobject | nullrequired
    O nome do contato, nos campos da Meta.
  • message.contacts[].name.formatted_namestring | nullrequired
  • message.contacts[].name.first_namestring | nullrequired
  • message.contacts[].name.last_namestring | nullrequired
  • message.contacts[].name.middle_namestring | nullrequired
  • message.contacts[].name.prefixstring | nullrequired
  • message.contacts[].name.suffixstring | nullrequired
  • message.contacts[].phonesarray<object> | nullrequired
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • message.contacts[].phones[].phonestring | nullrequired
  • message.contacts[].phones[].wa_idstring | nullrequired
  • message.contacts[].phones[].typestring | nullrequired
  • message.contacts[].emailsarray<object> | nullrequired
    Os e-mails do contato.
  • message.contacts[].emails[].emailstring | nullrequired
  • message.contacts[].emails[].typestring | nullrequired
  • message.contacts[].orgobject | nullrequired
    A organização do contato.
  • message.contacts[].org.companystring | nullrequired
  • message.contacts[].org.departmentstring | nullrequired
  • message.contacts[].org.titlestring | nullrequired
  • message.reactionobject | nullrequired
    A reação a uma mensagem, ou a retirada dela.
  • message.reaction.wamidstring | nullrequired
    O wamid da mensagem que recebeu a reação.
  • message.reaction.emojistring | nullrequired
    O emoji. Nulo quando o interlocutor retirou a reação.
  • message.contextobject | nullrequired
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • message.context.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor citou ao responder.
  • message.context.fromstring | nullrequired
    Quem enviou a mensagem citada.
  • message.context.forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada.
  • message.context.frequently_forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • message.referralobject | nullrequired
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • message.referral.source_typestring | nullrequired
    A origem do clique, como ad ou post.
  • message.referral.source_idstring | nullrequired
    O identificador do anúncio ou da publicação na Meta.
  • message.referral.source_urlstring | nullrequired
    O endereço do anúncio ou da publicação.
  • message.referral.headlinestring | nullrequired
    O título do anúncio.
  • message.referral.bodystring | nullrequired
    O texto do anúncio.
  • message.referral.media_typestring | nullrequired
    O tipo da mídia do anúncio, como image ou video.
  • message.referral.ctwa_clidstring | nullrequired
    O identificador do clique, para atribuição de conversão.
  • message.unsupportedobject | nullrequired
    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.codeinteger | nullrequired
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • message.unsupported.titlestring | nullrequired
    O título do erro, como a Meta o mandou.
  • message.unsupported.detailsstring | nullrequired
    O detalhe do erro, como a Meta o mandou.
  • message.editobject | nullrequired
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • message.edit.wamidstring | nullrequired
    O wamid da mensagem que foi editada.
  • message.edit.typestring | nullrequired
    O tipo do conteúdo novo, como text.
  • message.edit.textstring | nullrequired
    O texto novo, quando o conteúdo novo é texto.
  • message.revokeobject | nullrequired
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • message.revoke.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor apagou para todos.
  • message.orderobject | nullrequired
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • message.order.catalog_idstring | nullrequired
    O catálogo de onde veio o pedido.
  • message.order.textstring | nullrequired
    O texto que o interlocutor escreveu junto com o pedido.
  • message.order.itemsarray<object> | nullrequired
    Os itens do pedido.
  • message.order.items[].product_retailer_idstring | nullrequired
    O identificador do produto no seu catálogo.
  • message.order.items[].quantitystring | nullrequired
    A quantidade pedida, como a Meta mandou.
  • message.order.items[].item_pricestring | nullrequired
    O preço unitário, como a Meta mandou.
  • message.order.items[].currencystring | nullrequired
    A moeda do preço.

Example of the delivered body

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

EVENTmessage.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • messageobjectrequired
    Uma mudança de estado de uma mensagem que você enviou.
  • message.idstring (uuid) | nullrequired
    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.wamidstring | nullrequired
    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_idstring | nullrequired
    O identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id.
  • message.user_idstring | nullrequired
    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_idstring | nullrequired
    O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.
  • message.usernamestring | nullrequired
    O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.
  • message.statusstringrequired
    O estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer.
  • message.error_codeinteger | nullrequired
    O código de erro da Meta quando o estado é de falha. Nulo nos demais.
  • message.errorobject | nullrequired
    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.codeinteger | nullrequired
    O código do erro, como a Meta o informou.
  • message.error.titlestring | nullrequired
    O título do erro, como a Meta o informou.
  • message.error.messagestring | nullrequired
    A descrição do erro, como a Meta a informou.
  • message.pricingobject | nullrequired
    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.billableboolean | nullrequired
    Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.
  • message.pricing.pricing_modelstring | nullrequired
    O modelo de preço da Meta, como ela informou (hoje PMP ou CBP).
  • message.pricing.typestring | nullrequired
    O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.
  • message.pricing.categorystring | nullrequired
    A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.
  • message.callback_datastring | nullrequired
    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.

Example of the delivered body

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

EVENTcontact.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • contactobjectrequired
    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.wamidstringrequired
    O identificador, na Meta, da mensagem de sistema que avisou a troca.
  • contact.change_typestringrequired
    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_idstring | nullrequired
    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_idstring | nullrequired
    O BSUID do contato depois da troca, como a Meta mandou.
  • contact.previous_user_idstring | nullrequired
    O BSUID de antes da troca, quando a Meta o informa. Use-o para achar o contato no seu cadastro.
  • contact.parent_user_idstring | nullrequired
    O BSUID pai do contato depois da troca, quando a Meta o informa.
  • contact.previous_parent_user_idstring | nullrequired
    O BSUID pai de antes da troca, quando a Meta o informa.

Example of the delivered body

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

EVENTcontact.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • contactobjectrequired
    Quem mudou a preferência.
  • contact.wa_idstring | nullrequired
    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_idstring | nullrequired
    O BSUID do contato, como a Meta mandou.
  • contact.parent_user_idstring | nullrequired
    O BSUID pai do contato, quando a Meta o informa.
  • contact.usernamestring | nullrequired
    O nome de usuário do contato, quando ele adotou um.
  • contact.profile_namestring | nullrequired
    O nome que o contato exibe no WhatsApp, quando a Meta o manda.
  • preferenceobjectrequired
    O que mudou.
  • preference.categorystring | nullrequired
    A categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer.
  • preference.valuestring | nullrequired
    O que o contato escolheu, como a Meta informou (por exemplo stop para parar de receber, resume para voltar). Novos valores podem aparecer.
  • preference.detailstring | nullrequired
    O texto que a Meta mandou para explicar a mudança.

Example of the delivered body

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

EVENTbacklog.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • backlogobjectrequired
    Eventos que a plataforma descartou sem entregar, e que não serão reenviados.
  • backlog.motivostringrequired
    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.quantidadeintegerrequired
    Quantos eventos foram descartados nesta ocorrência.
  • backlog.janela_iniciostringrequired
    O evento mais antigo descartado nesta ocorrência.
  • backlog.janela_fimstringrequired
    O evento mais recente descartado nesta ocorrência.

Example of the delivered body

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

EVENThistory_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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • history_syncobjectrequired
    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.prazostringrequired
    Até quando a importação precisa terminar, em UTC. É o mesmo instante que sincronizacaoPrazo devolve na rota de saúde do número.

Example of the delivered body

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

EVENTwebhook.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idnullrequired
    Sempre null neste tipo: o evento de teste não passa por nenhum número.
  • testtrueoptional
    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.
  • numbernullrequired
    Sempre null neste tipo: o evento não passa por um número.
  • event_type"webhook.test"required
  • webhook_testobjectrequired
    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_idstring (uuid)required
    O endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu.

Example of the delivered body

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

EVENTmessage.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • messageobjectrequired
    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.idstring (uuid)required
    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.wamidstringrequired
    O identificador da mensagem na Meta.
  • message.wa_idstring | nullrequired
    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_idstring | nullrequired
    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_idstring | nullrequired
    O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.
  • message.usernamestring | nullrequired
    O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.
  • message.typestringrequired
    O tipo da mensagem, no vocabulário da Meta.
  • message.textstring | nullrequired
    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_namestring | nullrequired
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • message.mediaobject | nullrequired
  • message.media.mime_typestring | nullrequired
    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.sha256string | nullrequired
    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.captionstring | nullrequired
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • message.media.filenamestring | nullrequired
    O nome do arquivo. Só documento tem.
  • message.media.voiceboolean | nullrequired
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • message.media.animatedboolean | nullrequired
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • message.media.urlstring | nullrequired
    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.interactiveobject | nullrequired
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • message.interactive.typestring | nullrequired
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • message.interactive.idstring | nullrequired
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • message.interactive.titlestring | nullrequired
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • message.interactive.descriptionstring | nullrequired
    A descrição do item da lista. Nula nos demais.
  • message.interactive.namestring | nullrequired
    O nome do Flow. Só em nfm_reply.
  • message.interactive.response_jsonstring | nullrequired
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • message.buttonobject | nullrequired
    O clique num botão de resposta rápida de um template.
  • message.button.payloadstring | nullrequired
    O payload que você definiu no botão de resposta rápida do template.
  • message.button.textstring | nullrequired
    O texto do botão.
  • message.locationobject | nullrequired
    A localização que o interlocutor compartilhou.
  • message.location.latitudenumber | nullrequired
    A latitude, em graus decimais.
  • message.location.longitudenumber | nullrequired
    A longitude, em graus decimais.
  • message.location.namestring | nullrequired
    O nome do lugar, quando o interlocutor escolheu um.
  • message.location.addressstring | nullrequired
    O endereço, quando há.
  • message.location.urlstring | nullrequired
    O endereço web do lugar, quando há.
  • message.contactsarray<object> | nullrequired
    Os cartões de contato que o interlocutor compartilhou.
  • message.contacts[].nameobject | nullrequired
    O nome do contato, nos campos da Meta.
  • message.contacts[].name.formatted_namestring | nullrequired
  • message.contacts[].name.first_namestring | nullrequired
  • message.contacts[].name.last_namestring | nullrequired
  • message.contacts[].name.middle_namestring | nullrequired
  • message.contacts[].name.prefixstring | nullrequired
  • message.contacts[].name.suffixstring | nullrequired
  • message.contacts[].phonesarray<object> | nullrequired
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • message.contacts[].phones[].phonestring | nullrequired
  • message.contacts[].phones[].wa_idstring | nullrequired
  • message.contacts[].phones[].typestring | nullrequired
  • message.contacts[].emailsarray<object> | nullrequired
    Os e-mails do contato.
  • message.contacts[].emails[].emailstring | nullrequired
  • message.contacts[].emails[].typestring | nullrequired
  • message.contacts[].orgobject | nullrequired
    A organização do contato.
  • message.contacts[].org.companystring | nullrequired
  • message.contacts[].org.departmentstring | nullrequired
  • message.contacts[].org.titlestring | nullrequired
  • message.reactionobject | nullrequired
    A reação a uma mensagem, ou a retirada dela.
  • message.reaction.wamidstring | nullrequired
    O wamid da mensagem que recebeu a reação.
  • message.reaction.emojistring | nullrequired
    O emoji. Nulo quando o interlocutor retirou a reação.
  • message.contextobject | nullrequired
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • message.context.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor citou ao responder.
  • message.context.fromstring | nullrequired
    Quem enviou a mensagem citada.
  • message.context.forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada.
  • message.context.frequently_forwardedboolean | nullrequired
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • message.referralobject | nullrequired
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • message.referral.source_typestring | nullrequired
    A origem do clique, como ad ou post.
  • message.referral.source_idstring | nullrequired
    O identificador do anúncio ou da publicação na Meta.
  • message.referral.source_urlstring | nullrequired
    O endereço do anúncio ou da publicação.
  • message.referral.headlinestring | nullrequired
    O título do anúncio.
  • message.referral.bodystring | nullrequired
    O texto do anúncio.
  • message.referral.media_typestring | nullrequired
    O tipo da mídia do anúncio, como image ou video.
  • message.referral.ctwa_clidstring | nullrequired
    O identificador do clique, para atribuição de conversão.
  • message.unsupportedobject | nullrequired
    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.codeinteger | nullrequired
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • message.unsupported.titlestring | nullrequired
    O título do erro, como a Meta o mandou.
  • message.unsupported.detailsstring | nullrequired
    O detalhe do erro, como a Meta o mandou.
  • message.editobject | nullrequired
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • message.edit.wamidstring | nullrequired
    O wamid da mensagem que foi editada.
  • message.edit.typestring | nullrequired
    O tipo do conteúdo novo, como text.
  • message.edit.textstring | nullrequired
    O texto novo, quando o conteúdo novo é texto.
  • message.revokeobject | nullrequired
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • message.revoke.wamidstring | nullrequired
    O wamid da mensagem que o interlocutor apagou para todos.
  • message.orderobject | nullrequired
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • message.order.catalog_idstring | nullrequired
    O catálogo de onde veio o pedido.
  • message.order.textstring | nullrequired
    O texto que o interlocutor escreveu junto com o pedido.
  • message.order.itemsarray<object> | nullrequired
    Os itens do pedido.
  • message.order.items[].product_retailer_idstring | nullrequired
    O identificador do produto no seu catálogo.
  • message.order.items[].quantitystring | nullrequired
    A quantidade pedida, como a Meta mandou.
  • message.order.items[].item_pricestring | nullrequired
    O preço unitário, como a Meta mandou.
  • message.order.items[].currencystring | nullrequired
    A moeda do preço.

Example of the delivered body

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

EVENTtemplate.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idnullrequired
    Sempre null neste tipo: o template pertence à conta de negócio, e não a um número.
  • testtrueoptional
    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.
  • numbernullrequired
    Sempre null neste tipo: o evento não passa por um número.
  • event_type"template.status"required
  • templateobjectrequired
    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.idstring (uuid)required
    O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.
  • template.namestringrequired
    O nome do template.
  • template.languagestringrequired
    O idioma do template, no código da Meta.
  • template.waba_idstringrequired
    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_idstring | nullrequired
    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.statusstringrequired
    O novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer.
  • template.categorystringrequired
    A categoria do template, no vocabulário da Meta.
  • template.reasonstring | nullrequired
    O motivo que a Meta informou para a rejeição ou a pausa. Nulo quando ela não informa um, como nas aprovações.

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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_idstringrequired
    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.coexistencebooleanrequired
    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"required

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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_sincestringrequired
    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"required

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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"required

Example of the delivered body

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

EVENTaccount.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • wabaobjectrequired
    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_idstringrequired
    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_idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • waba.display_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • waba.external_idstring | nullrequired
    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.restrictionsarray<object>required
    As restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar.
  • waba.restrictions[].restriction_typestring | nullrequired
    O tipo da restrição, no vocabulário da Meta.
  • waba.restrictions[].expirationstring | nullrequired
    Quando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo.
  • waba.restrictions[].remediationstring | nullrequired
    O que a Meta diz que resolve a restrição, quando informa.

Example of the delivered body

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

EVENTaccount.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • wabaobjectrequired
    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_idstringrequired
    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_idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • waba.display_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • waba.external_idstring | nullrequired
    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_typestring | nullrequired
    O tipo da violação, no vocabulário da Meta.

Example of the delivered body

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

EVENTaccount.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • wabaobjectrequired
    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_idstringrequired
    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_idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • waba.display_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • waba.external_idstring | nullrequired
    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_datestring | nullrequired
    A data da desativação, como a Meta informou.

Example of the delivered body

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

EVENTaccount.reinstated

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

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • wabaobjectrequired
    A Meta reativou a conta de WhatsApp Business deste número depois de uma desativação.
  • waba.waba_idstringrequired
    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_idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • waba.display_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • waba.external_idstring | nullrequired
    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_datestring | nullrequired
    A data informada pela Meta junto com a reativação, quando houver.

Example of the delivered body

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

EVENTaccount.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • wabaobjectrequired
    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_idstringrequired
    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_idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • waba.display_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • waba.external_idstring | nullrequired
    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.eventstringrequired
    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.detailsobjectrequired
    O restante do aviso da Meta, como ela mandou, sem o campo event.

Example of the delivered body

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

EVENTaccount.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • wabaobjectrequired
    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_idstringrequired
    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_idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • waba.display_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • waba.external_idstring | nullrequired
    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_limitstring | nullrequired
    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_wabanumber | nullrequired
    Quantos números a Meta permite nesta conta. Nulo quando o aviso mudou só o limite de conversas.

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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_idstringrequired
    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.reasonstringrequired
    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_reasonstring | nullrequired
    O motivo que a Meta informou em disconnection_info, quando informa.
  • number.initiated_bystring | nullrequired
    Quem iniciou a desconexão, como a Meta informou.
  • event_type"number.disconnected"required

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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_idstringrequired
    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_ratingstringrequired
    A avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED.
  • number.quality_ratingstringrequired
    A avaliação de qualidade atual, no vocabulário da Meta.
  • event_type"number.quality_changed"required

Example of the delivered body

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

EVENTnumber.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}.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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_idstringrequired
    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.statusstringrequired
    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.namestring | nullrequired
    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"required

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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_idstringrequired
    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_atstringrequired
    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"required

Example of the delivered body

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

EVENTaccount.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobject | nullrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_idstring | nullrequired
    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"required
  • wabaobjectrequired
    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_idstringrequired
    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_idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • waba.display_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • waba.external_idstring | nullrequired
    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_typestring | nullrequired
    A que o alerta se refere, como a Meta informou (por exemplo a conta, o portfólio ou um número).
  • waba.entity_idstring | nullrequired
    O identificador, na Meta, do que o alerta cita.
  • waba.alert_severitystring | nullrequired
    A gravidade que a Meta atribuiu ao alerta, no vocabulário dela.
  • waba.alert_statusstring | nullrequired
    Se o alerta está ativo ou foi resolvido, no vocabulário da Meta.
  • waba.alert_typestring | nullrequired
    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_descriptionstring | nullrequired
    A descrição do alerta, em texto, como a Meta mandou.
  • waba.detailsobjectrequired
    O restante do alerta, como a Meta mandou, para o que a Luna ainda não nomeia.

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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.statusstringrequired
    O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}.Values: connected connecting action_required disconnected
  • number.can_sendbooleanrequired
    Se o envio por este número vai funcionar agora, o mesmo de connection.canSend.
  • number.reasonsarray<object>required
    Os motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento.at least 1 items
  • number.reasons[].codestringrequired
    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[].messagestringrequired
    O que está acontecendo, em português, pronto para repassar ao seu cliente.
  • number.reasons[].solutionstringrequired
    O que fazer a respeito, em português.
  • event_type"number.action_required"required

Example of the delivered body

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

EVENTnumber.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringrequired
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • testtrueoptional
    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.
  • numberobjectrequired
    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.idstring (uuid)required
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringrequired
    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_numberstring | nullrequired
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullrequired
    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.statusstringrequired
    O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}.Values: connected connecting action_required disconnected
  • number.can_sendbooleanrequired
    Se o envio por este número vai funcionar agora, o mesmo de connection.canSend.
  • event_type"number.action_resolved"required

Example of the delivered body

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

A template category changed

EVENTtemplate.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idnullrequired
    Sempre null neste tipo: o template pertence à conta de negócio, e não a um número.
  • testtrueoptional
    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.
  • numbernullrequired
    Sempre null neste tipo: o evento não passa por um número.
  • event_type"template.category"required
  • templateobjectrequired
    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.idstring (uuid)required
    O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.
  • template.namestringrequired
    O nome do template.
  • template.languagestringrequired
    O idioma do template, no código da Meta.
  • template.waba_idstringrequired
    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_idstring | nullrequired
    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.categorystringrequired
    A categoria do template, no vocabulário da Meta.
  • template.previous_categorystring | nullrequired
    A categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio.
  • template.new_categorystring | nullrequired
    A categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio.
  • template.correct_categorystring | nullrequired
    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_forstring | nullrequired
    No aviso prévio, quando a Meta aplica a mudança. Nulo quando a mudança já foi feita.

Example of the delivered body

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

EVENTtemplate.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.

Request body

  • version"2026-11-10"required
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringrequired
    O identificador estável deste evento. Use-o para descartar repetições.64 to 64 characters
  • occurred_atstringrequired
    Quando o evento ocorreu, em UTC.
  • phone_number_idnullrequired
    Sempre null neste tipo: o template pertence à conta de negócio, e não a um número.
  • testtrueoptional
    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.
  • numbernullrequired
    Sempre null neste tipo: o evento não passa por um número.
  • event_type"template.quality"required
  • templateobjectrequired
    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.idstring (uuid)required
    O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.
  • template.namestringrequired
    O nome do template.
  • template.languagestringrequired
    O idioma do template, no código da Meta.
  • template.waba_idstringrequired
    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_idstring | nullrequired
    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_scorestring | nullrequired
    A nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN.
  • template.new_quality_scorestring | nullrequired
    A nota de qualidade de agora, no vocabulário da Meta.

Example of the delivered body

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