Webhook events
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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredmessageobjectrequiredUma 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)requiredO 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.wamidstringrequiredO identificador da mensagem na Meta.message.wa_idstring | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.message.usernamestring | nullrequiredO nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.message.typestringrequiredO tipo da mensagem, no vocabulário da Meta.message.textstring | nullrequiredO 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 | nullrequiredO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.message.mediaobject | nullrequiredmessage.media.mime_typestring | nullrequiredO 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 | nullrequiredO 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 | nullrequiredA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.message.media.filenamestring | nullrequiredO nome do arquivo. Só documento tem.message.media.voiceboolean | nullrequiredVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.message.media.animatedboolean | nullrequiredVerdadeiro quando a figurinha é animada. Só figurinha tem.message.media.urlstring | nullrequiredLink 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 | nullrequiredA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.message.interactive.typestring | nullrequiredQual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).message.interactive.idstring | nullrequiredO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.message.interactive.titlestring | nullrequiredO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.message.interactive.descriptionstring | nullrequiredA descrição do item da lista. Nula nos demais.message.interactive.namestring | nullrequiredO nome do Flow. Só em nfm_reply.message.interactive.response_jsonstring | nullrequiredAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.message.buttonobject | nullrequiredO clique num botão de resposta rápida de um template.message.button.payloadstring | nullrequiredO payload que você definiu no botão de resposta rápida do template.message.button.textstring | nullrequiredO texto do botão.message.locationobject | nullrequiredA localização que o interlocutor compartilhou.message.location.latitudenumber | nullrequiredA latitude, em graus decimais.message.location.longitudenumber | nullrequiredA longitude, em graus decimais.message.location.namestring | nullrequiredO nome do lugar, quando o interlocutor escolheu um.message.location.addressstring | nullrequiredO endereço, quando há.message.location.urlstring | nullrequiredO endereço web do lugar, quando há.message.contactsarray<object> | nullrequiredOs cartões de contato que o interlocutor compartilhou.message.contacts[].nameobject | nullrequiredO nome do contato, nos campos da Meta.message.contacts[].name.formatted_namestring | nullrequiredmessage.contacts[].name.first_namestring | nullrequiredmessage.contacts[].name.last_namestring | nullrequiredmessage.contacts[].name.middle_namestring | nullrequiredmessage.contacts[].name.prefixstring | nullrequiredmessage.contacts[].name.suffixstring | nullrequiredmessage.contacts[].phonesarray<object> | nullrequiredOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.message.contacts[].phones[].phonestring | nullrequiredmessage.contacts[].phones[].wa_idstring | nullrequiredmessage.contacts[].phones[].typestring | nullrequiredmessage.contacts[].emailsarray<object> | nullrequiredOs e-mails do contato.message.contacts[].emails[].emailstring | nullrequiredmessage.contacts[].emails[].typestring | nullrequiredmessage.contacts[].orgobject | nullrequiredA organização do contato.message.contacts[].org.companystring | nullrequiredmessage.contacts[].org.departmentstring | nullrequiredmessage.contacts[].org.titlestring | nullrequiredmessage.reactionobject | nullrequiredA reação a uma mensagem, ou a retirada dela.message.reaction.wamidstring | nullrequiredO wamid da mensagem que recebeu a reação.message.reaction.emojistring | nullrequiredO emoji. Nulo quando o interlocutor retirou a reação.message.contextobject | nullrequiredA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.message.context.wamidstring | nullrequiredO wamid da mensagem que o interlocutor citou ao responder.message.context.fromstring | nullrequiredQuem enviou a mensagem citada.message.context.forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada.message.context.frequently_forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada muitas vezes.message.referralobject | nullrequiredO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.message.referral.source_typestring | nullrequiredA origem do clique, como ad ou post.message.referral.source_idstring | nullrequiredO identificador do anúncio ou da publicação na Meta.message.referral.source_urlstring | nullrequiredO endereço do anúncio ou da publicação.message.referral.headlinestring | nullrequiredO título do anúncio.message.referral.bodystring | nullrequiredO texto do anúncio.message.referral.media_typestring | nullrequiredO tipo da mídia do anúncio, como image ou video.message.referral.ctwa_clidstring | nullrequiredO identificador do clique, para atribuição de conversão.message.unsupportedobject | nullrequiredPresente 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 | nullrequiredO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").message.unsupported.titlestring | nullrequiredO título do erro, como a Meta o mandou.message.unsupported.detailsstring | nullrequiredO detalhe do erro, como a Meta o mandou.message.editobject | nullrequiredPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).message.edit.wamidstring | nullrequiredO wamid da mensagem que foi editada.message.edit.typestring | nullrequiredO tipo do conteúdo novo, como text.message.edit.textstring | nullrequiredO texto novo, quando o conteúdo novo é texto.message.revokeobject | nullrequiredPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).message.revoke.wamidstring | nullrequiredO wamid da mensagem que o interlocutor apagou para todos.message.orderobject | nullrequiredO pedido que o interlocutor montou num catálogo e enviou (type é order).message.order.catalog_idstring | nullrequiredO catálogo de onde veio o pedido.message.order.textstring | nullrequiredO texto que o interlocutor escreveu junto com o pedido.message.order.itemsarray<object> | nullrequiredOs itens do pedido.message.order.items[].product_retailer_idstring | nullrequiredO identificador do produto no seu catálogo.message.order.items[].quantitystring | nullrequiredA quantidade pedida, como a Meta mandou.message.order.items[].item_pricestring | nullrequiredO preço unitário, como a Meta mandou.message.order.items[].currencystring | nullrequiredA moeda do preço.
Example of the delivered body
{
"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
}
}{
"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
}
}{
"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
}
}{
"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
}
}{
"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"
}
]
}
}
}{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredmessageobjectrequiredUma mudança de estado de uma mensagem que você enviou.message.idstring (uuid) | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id.message.user_idstring | nullrequiredO 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 | nullrequiredO BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.message.usernamestring | nullrequiredO nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.message.statusstringrequiredO estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer.message.error_codeinteger | nullrequiredO código de erro da Meta quando o estado é de falha. Nulo nos demais.message.errorobject | nullrequiredO 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 | nullrequiredO código do erro, como a Meta o informou.message.error.titlestring | nullrequiredO título do erro, como a Meta o informou.message.error.messagestring | nullrequiredA descrição do erro, como a Meta a informou.message.pricingobject | nullrequiredO 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 | nullrequiredSe a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.message.pricing.pricing_modelstring | nullrequiredO modelo de preço da Meta, como ela informou (hoje PMP ou CBP).message.pricing.typestring | nullrequiredO tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.message.pricing.categorystring | nullrequiredA categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.message.callback_datastring | nullrequiredA 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
{
"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"
}
}{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredcontactobjectrequiredO 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.wamidstringrequiredO identificador, na Meta, da mensagem de sistema que avisou a troca.contact.change_typestringrequiredO 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 | nullrequiredO 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 | nullrequiredO BSUID do contato depois da troca, como a Meta mandou.contact.previous_user_idstring | nullrequiredO BSUID de antes da troca, quando a Meta o informa. Use-o para achar o contato no seu cadastro.contact.parent_user_idstring | nullrequiredO BSUID pai do contato depois da troca, quando a Meta o informa.contact.previous_parent_user_idstring | nullrequiredO BSUID pai de antes da troca, quando a Meta o informa.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredcontactobjectrequiredQuem mudou a preferência.contact.wa_idstring | nullrequiredO 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 | nullrequiredO BSUID do contato, como a Meta mandou.contact.parent_user_idstring | nullrequiredO BSUID pai do contato, quando a Meta o informa.contact.usernamestring | nullrequiredO nome de usuário do contato, quando ele adotou um.contact.profile_namestring | nullrequiredO nome que o contato exibe no WhatsApp, quando a Meta o manda.preferenceobjectrequiredO que mudou.preference.categorystring | nullrequiredA categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer.preference.valuestring | nullrequiredO que o contato escolheu, como a Meta informou (por exemplo stop para parar de receber, resume para voltar). Novos valores podem aparecer.preference.detailstring | nullrequiredO texto que a Meta mandou para explicar a mudança.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredbacklogobjectrequiredEventos que a plataforma descartou sem entregar, e que não serão reenviados.backlog.motivostringrequiredQual 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:idadevolumebacklog.quantidadeintegerrequiredQuantos eventos foram descartados nesta ocorrência.backlog.janela_iniciostringrequiredO evento mais antigo descartado nesta ocorrência.backlog.janela_fimstringrequiredO evento mais recente descartado nesta ocorrência.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredhistory_syncobjectrequiredA 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.prazostringrequiredAté 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
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idnullrequiredSempre null neste tipo: o evento de teste não passa por nenhum número.testtrueoptionalPresente, 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.numbernullrequiredSempre null neste tipo: o evento não passa por um número.event_type"webhook.test"requiredwebhook_testobjectrequiredUm 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)requiredO endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredmessageobjectrequiredUma 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)requiredO 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.wamidstringrequiredO identificador da mensagem na Meta.message.wa_idstring | nullrequiredO 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 | nullrequiredO 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 | nullrequiredO BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.message.usernamestring | nullrequiredO nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.message.typestringrequiredO tipo da mensagem, no vocabulário da Meta.message.textstring | nullrequiredO 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 | nullrequiredO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.message.mediaobject | nullrequiredmessage.media.mime_typestring | nullrequiredO 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 | nullrequiredO 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 | nullrequiredA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.message.media.filenamestring | nullrequiredO nome do arquivo. Só documento tem.message.media.voiceboolean | nullrequiredVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.message.media.animatedboolean | nullrequiredVerdadeiro quando a figurinha é animada. Só figurinha tem.message.media.urlstring | nullrequiredLink 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 | nullrequiredA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.message.interactive.typestring | nullrequiredQual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).message.interactive.idstring | nullrequiredO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.message.interactive.titlestring | nullrequiredO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.message.interactive.descriptionstring | nullrequiredA descrição do item da lista. Nula nos demais.message.interactive.namestring | nullrequiredO nome do Flow. Só em nfm_reply.message.interactive.response_jsonstring | nullrequiredAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.message.buttonobject | nullrequiredO clique num botão de resposta rápida de um template.message.button.payloadstring | nullrequiredO payload que você definiu no botão de resposta rápida do template.message.button.textstring | nullrequiredO texto do botão.message.locationobject | nullrequiredA localização que o interlocutor compartilhou.message.location.latitudenumber | nullrequiredA latitude, em graus decimais.message.location.longitudenumber | nullrequiredA longitude, em graus decimais.message.location.namestring | nullrequiredO nome do lugar, quando o interlocutor escolheu um.message.location.addressstring | nullrequiredO endereço, quando há.message.location.urlstring | nullrequiredO endereço web do lugar, quando há.message.contactsarray<object> | nullrequiredOs cartões de contato que o interlocutor compartilhou.message.contacts[].nameobject | nullrequiredO nome do contato, nos campos da Meta.message.contacts[].name.formatted_namestring | nullrequiredmessage.contacts[].name.first_namestring | nullrequiredmessage.contacts[].name.last_namestring | nullrequiredmessage.contacts[].name.middle_namestring | nullrequiredmessage.contacts[].name.prefixstring | nullrequiredmessage.contacts[].name.suffixstring | nullrequiredmessage.contacts[].phonesarray<object> | nullrequiredOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.message.contacts[].phones[].phonestring | nullrequiredmessage.contacts[].phones[].wa_idstring | nullrequiredmessage.contacts[].phones[].typestring | nullrequiredmessage.contacts[].emailsarray<object> | nullrequiredOs e-mails do contato.message.contacts[].emails[].emailstring | nullrequiredmessage.contacts[].emails[].typestring | nullrequiredmessage.contacts[].orgobject | nullrequiredA organização do contato.message.contacts[].org.companystring | nullrequiredmessage.contacts[].org.departmentstring | nullrequiredmessage.contacts[].org.titlestring | nullrequiredmessage.reactionobject | nullrequiredA reação a uma mensagem, ou a retirada dela.message.reaction.wamidstring | nullrequiredO wamid da mensagem que recebeu a reação.message.reaction.emojistring | nullrequiredO emoji. Nulo quando o interlocutor retirou a reação.message.contextobject | nullrequiredA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.message.context.wamidstring | nullrequiredO wamid da mensagem que o interlocutor citou ao responder.message.context.fromstring | nullrequiredQuem enviou a mensagem citada.message.context.forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada.message.context.frequently_forwardedboolean | nullrequiredVerdadeiro quando a mensagem foi encaminhada muitas vezes.message.referralobject | nullrequiredO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.message.referral.source_typestring | nullrequiredA origem do clique, como ad ou post.message.referral.source_idstring | nullrequiredO identificador do anúncio ou da publicação na Meta.message.referral.source_urlstring | nullrequiredO endereço do anúncio ou da publicação.message.referral.headlinestring | nullrequiredO título do anúncio.message.referral.bodystring | nullrequiredO texto do anúncio.message.referral.media_typestring | nullrequiredO tipo da mídia do anúncio, como image ou video.message.referral.ctwa_clidstring | nullrequiredO identificador do clique, para atribuição de conversão.message.unsupportedobject | nullrequiredPresente 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 | nullrequiredO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").message.unsupported.titlestring | nullrequiredO título do erro, como a Meta o mandou.message.unsupported.detailsstring | nullrequiredO detalhe do erro, como a Meta o mandou.message.editobject | nullrequiredPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).message.edit.wamidstring | nullrequiredO wamid da mensagem que foi editada.message.edit.typestring | nullrequiredO tipo do conteúdo novo, como text.message.edit.textstring | nullrequiredO texto novo, quando o conteúdo novo é texto.message.revokeobject | nullrequiredPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).message.revoke.wamidstring | nullrequiredO wamid da mensagem que o interlocutor apagou para todos.message.orderobject | nullrequiredO pedido que o interlocutor montou num catálogo e enviou (type é order).message.order.catalog_idstring | nullrequiredO catálogo de onde veio o pedido.message.order.textstring | nullrequiredO texto que o interlocutor escreveu junto com o pedido.message.order.itemsarray<object> | nullrequiredOs itens do pedido.message.order.items[].product_retailer_idstring | nullrequiredO identificador do produto no seu catálogo.message.order.items[].quantitystring | nullrequiredA quantidade pedida, como a Meta mandou.message.order.items[].item_pricestring | nullrequiredO preço unitário, como a Meta mandou.message.order.items[].currencystring | nullrequiredA moeda do preço.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idnullrequiredSempre null neste tipo: o template pertence à conta de negócio, e não a um número.testtrueoptionalPresente, 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.numbernullrequiredSempre null neste tipo: o evento não passa por um número.event_type"template.status"requiredtemplateobjectrequiredO 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)requiredO identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.template.namestringrequiredO nome do template.template.languagestringrequiredO idioma do template, no código da Meta.template.waba_idstringrequiredA 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 | nullrequiredO 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.statusstringrequiredO novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer.template.categorystringrequiredA categoria do template, no vocabulário da Meta.template.reasonstring | nullrequiredO 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
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredUm 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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_idstringrequiredA 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.coexistencebooleanrequiredtrue 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
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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_sincestringrequiredQuando 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
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredUm 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredwabaobjectrequiredA 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_idstringrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullrequiredO 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>requiredAs restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar.waba.restrictions[].restriction_typestring | nullrequiredO tipo da restrição, no vocabulário da Meta.waba.restrictions[].expirationstring | nullrequiredQuando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo.waba.restrictions[].remediationstring | nullrequiredO que a Meta diz que resolve a restrição, quando informa.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredwabaobjectrequiredA 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_idstringrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullrequiredO 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 | nullrequiredO tipo da violação, no vocabulário da Meta.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredwabaobjectrequiredA 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_idstringrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullrequiredO 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 | nullrequiredA data da desativação, como a Meta informou.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredwabaobjectrequiredA Meta reativou a conta de WhatsApp Business deste número depois de uma desativação.waba.waba_idstringrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullrequiredO 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 | nullrequiredA data informada pela Meta junto com a reativação, quando houver.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredwabaobjectrequiredUm 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_idstringrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullrequiredO 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.eventstringrequiredO 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.detailsobjectrequiredO restante do aviso da Meta, como ela mandou, sem o campo event.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredwabaobjectrequiredA 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_idstringrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullrequiredO 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 | nullrequiredO 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 | nullrequiredQuantos números a Meta permite nesta conta. Nulo quando o aviso mudou só o limite de conversas.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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_idstringrequiredA 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.reasonstringrequiredO 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 | nullrequiredO motivo que a Meta informou em disconnection_info, quando informa.number.initiated_bystring | nullrequiredQuem iniciou a desconexão, como a Meta informou.event_type"number.disconnected"required
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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_idstringrequiredA 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_ratingstringrequiredA avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED.number.quality_ratingstringrequiredA avaliação de qualidade atual, no vocabulário da Meta.event_type"number.quality_changed"required
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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_idstringrequiredA 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.statusstringrequiredO 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 | nullrequiredO 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
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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_idstringrequiredA 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_atstringrequiredQuando 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
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO 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"requiredwabaobjectrequiredA 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_idstringrequiredA 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullrequiredO 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 | nullrequiredA que o alerta se refere, como a Meta informou (por exemplo a conta, o portfólio ou um número).waba.entity_idstring | nullrequiredO identificador, na Meta, do que o alerta cita.waba.alert_severitystring | nullrequiredA gravidade que a Meta atribuiu ao alerta, no vocabulário dela.waba.alert_statusstring | nullrequiredSe o alerta está ativo ou foi resolvido, no vocabulário da Meta.waba.alert_typestring | nullrequiredO 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 | nullrequiredA descrição do alerta, em texto, como a Meta mandou.waba.detailsobjectrequiredO restante do alerta, como a Meta mandou, para o que a Luna ainda não nomeia.
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredEste 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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.statusstringrequiredO estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}.Values:connectedconnectingaction_requireddisconnectednumber.can_sendbooleanrequiredSe o envio por este número vai funcionar agora, o mesmo de connection.canSend.number.reasonsarray<object>requiredOs motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento.at least 1 itemsnumber.reasons[].codestringrequiredO 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[].messagestringrequiredO que está acontecendo, em português, pronto para repassar ao seu cliente.number.reasons[].solutionstringrequiredO que fazer a respeito, em português.event_type"number.action_required"required
Example of the delivered body
{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstringrequiredO identificador do número na Meta, o mesmo que a listagem de números devolve.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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.numberobjectrequiredEste 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO 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.statusstringrequiredO estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}.Values:connectedconnectingaction_requireddisconnectednumber.can_sendbooleanrequiredSe 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
{
"version": "2026-11-10",
"event_id": "3279de99ef1bc2ade5d88bde7a2fd878b8faabddc179b8dceebded74d5b7394b",
"event_type": "number.action_resolved",
"occurred_at": "2026-10-28T15:40:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"status": "connected",
"can_send": true
}
}Connect link completed
EVENTonboarding.link.completed
Your customer completed the connection through a link: the link becomes used. It carries the link externalId and, when Luna has already registered the number, number_id; the number.connected event announces when the number is ready to send. It goes out once per link.
Request body
version"2026-11-10"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstring | nullrequiredO número do link de reconexão ou o que resultou da conexão, ou null quando o evento não tem número.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO número que resultou da conexão, no mesmo formato dos eventos number.*, com waba_id. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto.number.idstring (uuid)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullrequiredO rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes.number.waba_idstringrequiredA conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId.event_type"onboarding.link.completed"requiredlinkobjectrequiredO seu cliente concluiu a conexão por um link: ele aceitou os termos da Meta e a Luna recebeu o acesso à conta dele. É o fim do link, que passa a used. O número pode ainda estar sendo registrado: quem avisa que ele ficou pronto para enviar é number.connected. Sai uma vez por link.link.idstring (uuid)requiredO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullrequiredO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.used_atstringrequiredQuando a conexão por este link concluiu, o mesmo usedAt de GET /v1/onboarding/links/{id}.link.waba_idstring | nullrequiredA conta de WhatsApp Business que o seu cliente conectou, o mesmo id que GET /v1/business-accounts devolve em wabaId. Está preenchido mesmo quando a conta foi conectada sem número (number_id nulo). Nulo só se a Luna não a leu.link.number_idstring (uuid) | nullrequiredO número que resultou da conexão, o mesmo id de GET /v1/numbers. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto.
Example of the delivered body
{
"version": "2026-11-10",
"event_id": "fd3596b2273541c7a77c69cb8a2ddb0e060052ddc84f251b5a76961053b578b1",
"event_type": "onboarding.link.completed",
"occurred_at": "2026-10-28T15:30:12.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398"
},
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"used_at": "2026-10-28T15:30:12.000Z",
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b"
}
}Connect link opened
EVENTonboarding.link.opened
Your customer opened the link for the first time. It goes out once per link, and not again when they come back to the page or try again. It carries the link externalId and opened_at. It is the start of the cycle: onboarding.link.completed, onboarding.link.failed or onboarding.link.expired follow. Whoever opened and never completed shows up here without a completed.
Request body
version"2026-11-10"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstring | nullrequiredO número do link de reconexão, ou null quando o link é de uma conexão nova.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes.event_type"onboarding.link.opened"requiredlinkobjectrequiredO seu cliente abriu o link pela primeira vez. Sai uma vez por link, na primeira abertura, e não de novo quando ele volta à página ou tenta outra vez. É o começo do ciclo: depois dele vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed.link.idstring (uuid)requiredO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullrequiredO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.opened_atstringrequiredQuando o seu cliente abriu o link pela primeira vez.
Example of the delivered body
{
"version": "2026-11-10",
"event_id": "b8a277c5c9377c213ee4c3b79c3e83829f3bef5f69521db1a0434da05acfbc1d",
"event_type": "onboarding.link.opened",
"occurred_at": "2026-10-28T15:21:40.000Z",
"phone_number_id": null,
"number": null,
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"opened_at": "2026-10-28T15:21:40.000Z"
}
}A connect link attempt did not work out
EVENTonboarding.link.failed
A connection attempt through a link did not work out. reason says why: abandoned (the customer closed Meta’s window, and step carries the screen where they stopped), error (Meta’s window reported an error, in error_code), failed (Luna tried to complete and could not), country_not_supported (the number is not +55) or registration_blocked (Meta blocked registration for 72 hours). The link stays open until it expires. It goes out once per attempt.
Request body
version"2026-11-10"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstring | nullrequiredO número do link de reconexão, ou null quando o link é de uma conexão nova.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes.event_type"onboarding.link.failed"requiredlinkobjectrequiredUma tentativa de conexão por um link não deu certo: o cliente desistiu em alguma tela, a janela da Meta relatou um erro, ou a conexão parou. O link continua aberto até vencer, e o cliente pode tentar de novo. Sai uma vez por tentativa. O que o cliente deve fazer para cada reason está no guia Conectar um número.link.idstring (uuid)requiredO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullrequiredO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.session_idstring (uuid)requiredA tentativa de conexão que não deu certo. Um link aberto admite várias.link.reasonstringrequiredPor que a tentativa não deu certo: abandoned (o cliente fechou a janela da Meta e a tela em que parou está em step), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir várias vezes e não conseguiu), country_not_supported (o número escolhido não é +55) ou registration_blocked (a Meta bloqueou o registro do número por 72 horas). Novos motivos podem aparecer.Values:abandonederrorfailedcountry_not_supportedregistration_blockedlink.stepstring | nullrequiredO nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado.link.error_codeinteger | nullrequiredO código de erro que a janela da Meta relatou. Nulo quando não houve erro relatado.
Example of the delivered body
{
"version": "2026-11-10",
"event_id": "cabf3f3478bda2efd0e9a3726d503dbcd575bec16cc0ccf5fc65cdcb4c88cea3",
"event_type": "onboarding.link.failed",
"occurred_at": "2026-10-28T15:12:40.000Z",
"phone_number_id": null,
"number": null,
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"session_id": "2e8f4b60-1a3c-4d57-9b0e-6c7d8e9f0a12",
"reason": "abandoned",
"step": "phone_number_setup",
"error_code": null
}
}Connect link expired
EVENTonboarding.link.expired
The link expired with nobody completing the connection. Create another with POST /v1/onboarding/links whenever you want. A used link never produces this event. It goes out once per link.
Request body
version"2026-11-10"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idstring | nullrequiredO número do link de reconexão, ou null quando o link é de uma conexão nova.1 to 64 characters · /^[A-Za-z0-9_-]+$/testtrueoptionalPresente, 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 | nullrequiredO 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)requiredO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringrequiredO 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 | nullrequiredO rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes.event_type"onboarding.link.expired"requiredlinkobjectrequiredO link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link que foi usado nunca gera este evento. Sai uma vez por link.link.idstring (uuid)requiredO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullrequiredO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.expired_atstringrequiredQuando o link venceu, o mesmo expiresAt de GET /v1/onboarding/links/{id}.
Example of the delivered body
{
"version": "2026-11-10",
"event_id": "1df73af80cf86f74267290bc13fcd1f82551997dd79845170b35c78f40b563ad",
"event_type": "onboarding.link.expired",
"occurred_at": "2026-10-31T15:00:00.000Z",
"phone_number_id": null,
"number": null,
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"expired_at": "2026-10-31T15:00:00.000Z"
}
}A template category changed
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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idnullrequiredSempre null neste tipo: o template pertence à conta de negócio, e não a um número.testtrueoptionalPresente, 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.numbernullrequiredSempre null neste tipo: o evento não passa por um número.event_type"template.category"requiredtemplateobjectrequiredA 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)requiredO identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.template.namestringrequiredO nome do template.template.languagestringrequiredO idioma do template, no código da Meta.template.waba_idstringrequiredA 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 | nullrequiredO 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.categorystringrequiredA categoria do template, no vocabulário da Meta.template.previous_categorystring | nullrequiredA categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio.template.new_categorystring | nullrequiredA categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio.template.correct_categorystring | nullrequiredNo 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 | nullrequiredNo aviso prévio, quando a Meta aplica a mudança. Nulo quando a mudança já foi feita.
Example of the delivered body
{
"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"
}
}{
"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"requiredA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringrequiredO identificador estável deste evento. Use-o para descartar repetições.64 to 64 charactersoccurred_atstringrequiredQuando o evento ocorreu, em UTC.phone_number_idnullrequiredSempre null neste tipo: o template pertence à conta de negócio, e não a um número.testtrueoptionalPresente, 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.numbernullrequiredSempre null neste tipo: o evento não passa por um número.event_type"template.quality"requiredtemplateobjectrequiredA 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)requiredO identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.template.namestringrequiredO nome do template.template.languagestringrequiredO idioma do template, no código da Meta.template.waba_idstringrequiredA 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 | nullrequiredO 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 | nullrequiredA nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN.template.new_quality_scorestring | nullrequiredA nota de qualidade de agora, no vocabulário da Meta.
Example of the delivered body
{
"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"
}
}