Eventos de webhook
A Luna entrega cada evento por POST ao endpoint que você cadastrou. Cada tipo abaixo traz o esquema do corpo e um exemplo. Um tipo novo de evento não muda a versão do contrato: ignore os tipos que você não conhece.
O guia Receber eventos explica a assinatura, as repetições e como tratar cada tipo.
Como a Luna entrega#
A Luna faz POST do evento no endpoint que você cadastrou, com o corpo em application/json e o cabeçalho de assinatura. Responda 2xx para confirmar; qualquer outra resposta, ou nenhuma, conta como falha e é repetida pela política de retentativa. Verifique a assinatura sobre o corpo bruto antes de confiar no conteúdo.
x-luna-signature: A assinatura da entrega: t=<segundos desde 1970>,v1=<HMAC-SHA256 em hexadecimal de "<t>.<corpo bruto>"> com o segredo do endpoint. Durante uma rotação de segredo o cabeçalho traz dois valores v1=, e basta um conferir. Rejeite entregas com t fora de 300 segundos do seu relógio.
Mensagem recebida
EVENTmessage.received
Um contato escreveu para um dos seus números. Traz o texto, e o conteúdo quando a mensagem é de outro tipo (mídia, botão clicado, localização, contatos, reação).
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriomessageobjectobrigatórioUma 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)obrigatórioO 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.wamidstringobrigatórioO identificador da mensagem na Meta.message.wa_idstring | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.message.usernamestring | nullobrigatórioO nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.message.typestringobrigatórioO tipo da mensagem, no vocabulário da Meta.message.textstring | nullobrigatórioO 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 | nullobrigatórioO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.message.mediaobject | nullobrigatóriomessage.media.mime_typestring | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.message.media.filenamestring | nullobrigatórioO nome do arquivo. Só documento tem.message.media.voiceboolean | nullobrigatórioVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.message.media.animatedboolean | nullobrigatórioVerdadeiro quando a figurinha é animada. Só figurinha tem.message.media.urlstring | nullobrigatórioLink 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 | nullobrigatórioA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.message.interactive.typestring | nullobrigatórioQual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).message.interactive.idstring | nullobrigatórioO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.message.interactive.titlestring | nullobrigatórioO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.message.interactive.descriptionstring | nullobrigatórioA descrição do item da lista. Nula nos demais.message.interactive.namestring | nullobrigatórioO nome do Flow. Só em nfm_reply.message.interactive.response_jsonstring | nullobrigatórioAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.message.buttonobject | nullobrigatórioO clique num botão de resposta rápida de um template.message.button.payloadstring | nullobrigatórioO payload que você definiu no botão de resposta rápida do template.message.button.textstring | nullobrigatórioO texto do botão.message.locationobject | nullobrigatórioA localização que o interlocutor compartilhou.message.location.latitudenumber | nullobrigatórioA latitude, em graus decimais.message.location.longitudenumber | nullobrigatórioA longitude, em graus decimais.message.location.namestring | nullobrigatórioO nome do lugar, quando o interlocutor escolheu um.message.location.addressstring | nullobrigatórioO endereço, quando há.message.location.urlstring | nullobrigatórioO endereço web do lugar, quando há.message.contactsarray<object> | nullobrigatórioOs cartões de contato que o interlocutor compartilhou.message.contacts[].nameobject | nullobrigatórioO nome do contato, nos campos da Meta.message.contacts[].name.formatted_namestring | nullobrigatóriomessage.contacts[].name.first_namestring | nullobrigatóriomessage.contacts[].name.last_namestring | nullobrigatóriomessage.contacts[].name.middle_namestring | nullobrigatóriomessage.contacts[].name.prefixstring | nullobrigatóriomessage.contacts[].name.suffixstring | nullobrigatóriomessage.contacts[].phonesarray<object> | nullobrigatórioOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.message.contacts[].phones[].phonestring | nullobrigatóriomessage.contacts[].phones[].wa_idstring | nullobrigatóriomessage.contacts[].phones[].typestring | nullobrigatóriomessage.contacts[].emailsarray<object> | nullobrigatórioOs e-mails do contato.message.contacts[].emails[].emailstring | nullobrigatóriomessage.contacts[].emails[].typestring | nullobrigatóriomessage.contacts[].orgobject | nullobrigatórioA organização do contato.message.contacts[].org.companystring | nullobrigatóriomessage.contacts[].org.departmentstring | nullobrigatóriomessage.contacts[].org.titlestring | nullobrigatóriomessage.reactionobject | nullobrigatórioA reação a uma mensagem, ou a retirada dela.message.reaction.wamidstring | nullobrigatórioO wamid da mensagem que recebeu a reação.message.reaction.emojistring | nullobrigatórioO emoji. Nulo quando o interlocutor retirou a reação.message.contextobject | nullobrigatórioA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.message.context.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor citou ao responder.message.context.fromstring | nullobrigatórioQuem enviou a mensagem citada.message.context.forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada.message.context.frequently_forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada muitas vezes.message.referralobject | nullobrigatórioO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.message.referral.source_typestring | nullobrigatórioA origem do clique, como ad ou post.message.referral.source_idstring | nullobrigatórioO identificador do anúncio ou da publicação na Meta.message.referral.source_urlstring | nullobrigatórioO endereço do anúncio ou da publicação.message.referral.headlinestring | nullobrigatórioO título do anúncio.message.referral.bodystring | nullobrigatórioO texto do anúncio.message.referral.media_typestring | nullobrigatórioO tipo da mídia do anúncio, como image ou video.message.referral.ctwa_clidstring | nullobrigatórioO identificador do clique, para atribuição de conversão.message.unsupportedobject | nullobrigatórioPresente 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 | nullobrigatórioO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").message.unsupported.titlestring | nullobrigatórioO título do erro, como a Meta o mandou.message.unsupported.detailsstring | nullobrigatórioO detalhe do erro, como a Meta o mandou.message.editobject | nullobrigatórioPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).message.edit.wamidstring | nullobrigatórioO wamid da mensagem que foi editada.message.edit.typestring | nullobrigatórioO tipo do conteúdo novo, como text.message.edit.textstring | nullobrigatórioO texto novo, quando o conteúdo novo é texto.message.revokeobject | nullobrigatórioPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).message.revoke.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor apagou para todos.message.orderobject | nullobrigatórioO pedido que o interlocutor montou num catálogo e enviou (type é order).message.order.catalog_idstring | nullobrigatórioO catálogo de onde veio o pedido.message.order.textstring | nullobrigatórioO texto que o interlocutor escreveu junto com o pedido.message.order.itemsarray<object> | nullobrigatórioOs itens do pedido.message.order.items[].product_retailer_idstring | nullobrigatórioO identificador do produto no seu catálogo.message.order.items[].quantitystring | nullobrigatórioA quantidade pedida, como a Meta mandou.message.order.items[].item_pricestring | nullobrigatórioO preço unitário, como a Meta mandou.message.order.items[].currencystring | nullobrigatórioA moeda do preço.
Exemplo do corpo entregue
{
"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
}
}Estado de uma mensagem que você enviou
EVENTmessage.status
Uma mensagem que você enviou mudou de estado: sent, delivered, read ou failed. Em failed, o evento traz o erro. Em sent e em um entre delivered e read, traz o pricing: o custo que a Meta aplicou à mensagem, com os nomes dela.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriomessageobjectobrigatórioUma mudança de estado de uma mensagem que você enviou.message.idstring (uuid) | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id.message.user_idstring | nullobrigatórioO 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 | nullobrigatórioO BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.message.usernamestring | nullobrigatórioO nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.message.statusstringobrigatórioO estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer.message.error_codeinteger | nullobrigatórioO código de erro da Meta quando o estado é de falha. Nulo nos demais.message.errorobject | nullobrigatórioO 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 | nullobrigatórioO código do erro, como a Meta o informou.message.error.titlestring | nullobrigatórioO título do erro, como a Meta o informou.message.error.messagestring | nullobrigatórioA descrição do erro, como a Meta a informou.message.pricingobject | nullobrigatórioO 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 | nullobrigatórioSe a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos.message.pricing.pricing_modelstring | nullobrigatórioO modelo de preço da Meta, como ela informou (hoje PMP ou CBP).message.pricing.typestring | nullobrigatórioO tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer.message.pricing.categorystring | nullobrigatórioA categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer.message.callback_datastring | nullobrigatórioA 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.
Exemplo do corpo entregue
{
"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
}
}Contato trocou de telefone ou de BSUID
EVENTcontact.identity_changed
Um contato trocou de telefone (user_changed_number) ou de BSUID (user_changed_user_id). A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriocontactobjectobrigatórioO 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.wamidstringobrigatórioO identificador, na Meta, da mensagem de sistema que avisou a troca.contact.change_typestringobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO BSUID do contato depois da troca, como a Meta mandou.contact.previous_user_idstring | nullobrigatórioO BSUID de antes da troca, quando a Meta o informa. Use-o para achar o contato no seu cadastro.contact.parent_user_idstring | nullobrigatórioO BSUID pai do contato depois da troca, quando a Meta o informa.contact.previous_parent_user_idstring | nullobrigatórioO BSUID pai de antes da troca, quando a Meta o informa.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "f73a65b1f155f86f94e0886ad29bac662a822fabf796b626cdf865c7060f0db9",
"event_type": "contact.identity_changed",
"occurred_at": "2026-11-03T15:20:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"contact": {
"wamid": "wamid.EXAMPLE_IDENTITY_CHANGE",
"change_type": "user_changed_user_id",
"wa_id": null,
"user_id": "BR.98765432109876543210",
"previous_user_id": "BR.13491208655302741918",
"parent_user_id": null,
"previous_parent_user_id": null
}
}Contato mudou uma preferência
EVENTcontact.preferences_changed
Um contato mudou uma preferência na Meta, hoje a de receber mensagens de marketing: pediu para parar (por exemplo value stop) ou voltou a aceitar. Os valores chegam como a Meta mandou. A Luna não bloqueia nenhum envio por causa do aviso: o seu sistema decide, e deve parar de mandar marketing a quem pediu. Só chega se o campo user_preferences estiver assinado no app da Meta.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriocontactobjectobrigatórioQuem mudou a preferência.contact.wa_idstring | nullobrigatórioO 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 | nullobrigatórioO BSUID do contato, como a Meta mandou.contact.parent_user_idstring | nullobrigatórioO BSUID pai do contato, quando a Meta o informa.contact.usernamestring | nullobrigatórioO nome de usuário do contato, quando ele adotou um.contact.profile_namestring | nullobrigatórioO nome que o contato exibe no WhatsApp, quando a Meta o manda.preferenceobjectobrigatórioO que mudou.preference.categorystring | nullobrigatórioA categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer.preference.valuestring | nullobrigatórioO que o contato escolheu, como a Meta informou (por exemplo stop para parar de receber, resume para voltar). Novos valores podem aparecer.preference.detailstring | nullobrigatórioO texto que a Meta mandou para explicar a mudança.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "4236ccfb21e7cec359d1e1b5b5f3f8e65cb3e8a8db0fc86e4d95da037796e97c",
"event_type": "contact.preferences_changed",
"occurred_at": "2026-11-04T16:45:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"contact": {
"wa_id": "5511900000000",
"user_id": "BR.13491208655302741918",
"parent_user_id": null,
"username": null,
"profile_name": "Maria Souza"
},
"preference": {
"category": "marketing_messages",
"value": "stop",
"detail": "User requested to stop marketing messages"
}
}Eventos descartados por indisponibilidade
EVENTbacklog.dropped
O seu endpoint ficou fora do ar por tempo demais, e a plataforma descartou o que se acumulou. Diz quantos eventos e de que período. O aviso não é descartado junto.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriobacklogobjectobrigatórioEventos que a plataforma descartou sem entregar, e que não serão reenviados.backlog.motivostringobrigatórioQual limite foi atingido: idade, quando as mensagens ficaram velhas demais para serem acionáveis; volume, quando o acumulado deste endpoint passou do teto da plataforma.Valores:idadevolumebacklog.quantidadeintegerobrigatórioQuantos eventos foram descartados nesta ocorrência.backlog.janela_iniciostringobrigatórioO evento mais antigo descartado nesta ocorrência.backlog.janela_fimstringobrigatórioO evento mais recente descartado nesta ocorrência.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "f76937420c2e818b87ce9b6acc5cb192c059ed2e33cda23339d5cf650b762ce5",
"event_type": "backlog.dropped",
"occurred_at": "2026-10-06T14:30:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"backlog": {
"motivo": "idade",
"quantidade": 37,
"janela_inicio": "2026-10-06T09:00:00.000Z",
"janela_fim": "2026-10-06T14:30:00.000Z"
}
}Prazo da importação do histórico se aproximando
EVENThistory_sync.deadline_approaching
Num número conectado em coexistência, a importação das conversas anteriores ainda está em curso e o prazo dela se aproxima. Passado o prazo sem concluir, a Meta desconecta o negócio final.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriohistory_syncobjectobrigatórioA 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.prazostringobrigatórioAté quando a importação precisa terminar, em UTC. É o mesmo instante que sincronizacaoPrazo devolve na rota de saúde do número.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "d42ca56e44ef023d52b0a0739dcf3afb0d5054a8b84321c41e432ed6707b043f",
"event_type": "history_sync.deadline_approaching",
"occurred_at": "2026-10-07T03:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"history_sync": {
"prazo": "2026-10-07T09:00:00.000Z"
}
}Evento de teste
EVENTwebhook.test
O evento que POST /v1/webhooks/endpoints/{id}/test envia ao seu endpoint, para você conferir URL e verificação de assinatura. Não passa por nenhum número.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idnullobrigatórioSempre null neste tipo: o evento de teste não passa por nenhum número.testtrueopcionalPresente, 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.numbernullobrigatórioSempre null neste tipo: o evento não passa por um número.event_type"webhook.test"obrigatóriowebhook_testobjectobrigatórioUm 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)obrigatórioO endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "6af3f85d8fedc8bb0f6d5bb6b4631e324574c539763c25cf113fd40db822cea8",
"event_type": "webhook.test",
"occurred_at": "2026-10-07T12:00:00.000Z",
"phone_number_id": null,
"number": null,
"webhook_test": {
"endpoint_id": "5c0e9a52-3a0e-4c3f-9f3e-0b3f6f1a2c77"
}
}Resposta dada pelo aplicativo do celular
EVENTmessage.echo
O dono do negócio respondeu a um cliente pelo aplicativo WhatsApp Business do celular. Só ocorre em número conectado em coexistência. message.wa_id é o destinatário.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriomessageobjectobrigatórioUma 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)obrigatórioO 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.wamidstringobrigatórioO identificador da mensagem na Meta.message.wa_idstring | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioO BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.message.usernamestring | nullobrigatórioO nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.message.typestringobrigatórioO tipo da mensagem, no vocabulário da Meta.message.textstring | nullobrigatórioO 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 | nullobrigatórioO nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.message.mediaobject | nullobrigatóriomessage.media.mime_typestring | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioA legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.message.media.filenamestring | nullobrigatórioO nome do arquivo. Só documento tem.message.media.voiceboolean | nullobrigatórioVerdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.message.media.animatedboolean | nullobrigatórioVerdadeiro quando a figurinha é animada. Só figurinha tem.message.media.urlstring | nullobrigatórioLink 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 | nullobrigatórioA resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.message.interactive.typestring | nullobrigatórioQual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).message.interactive.idstring | nullobrigatórioO id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.message.interactive.titlestring | nullobrigatórioO título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.message.interactive.descriptionstring | nullobrigatórioA descrição do item da lista. Nula nos demais.message.interactive.namestring | nullobrigatórioO nome do Flow. Só em nfm_reply.message.interactive.response_jsonstring | nullobrigatórioAs respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.message.buttonobject | nullobrigatórioO clique num botão de resposta rápida de um template.message.button.payloadstring | nullobrigatórioO payload que você definiu no botão de resposta rápida do template.message.button.textstring | nullobrigatórioO texto do botão.message.locationobject | nullobrigatórioA localização que o interlocutor compartilhou.message.location.latitudenumber | nullobrigatórioA latitude, em graus decimais.message.location.longitudenumber | nullobrigatórioA longitude, em graus decimais.message.location.namestring | nullobrigatórioO nome do lugar, quando o interlocutor escolheu um.message.location.addressstring | nullobrigatórioO endereço, quando há.message.location.urlstring | nullobrigatórioO endereço web do lugar, quando há.message.contactsarray<object> | nullobrigatórioOs cartões de contato que o interlocutor compartilhou.message.contacts[].nameobject | nullobrigatórioO nome do contato, nos campos da Meta.message.contacts[].name.formatted_namestring | nullobrigatóriomessage.contacts[].name.first_namestring | nullobrigatóriomessage.contacts[].name.last_namestring | nullobrigatóriomessage.contacts[].name.middle_namestring | nullobrigatóriomessage.contacts[].name.prefixstring | nullobrigatóriomessage.contacts[].name.suffixstring | nullobrigatóriomessage.contacts[].phonesarray<object> | nullobrigatórioOs telefones do contato. wa_id só existe quando o telefone tem WhatsApp.message.contacts[].phones[].phonestring | nullobrigatóriomessage.contacts[].phones[].wa_idstring | nullobrigatóriomessage.contacts[].phones[].typestring | nullobrigatóriomessage.contacts[].emailsarray<object> | nullobrigatórioOs e-mails do contato.message.contacts[].emails[].emailstring | nullobrigatóriomessage.contacts[].emails[].typestring | nullobrigatóriomessage.contacts[].orgobject | nullobrigatórioA organização do contato.message.contacts[].org.companystring | nullobrigatóriomessage.contacts[].org.departmentstring | nullobrigatóriomessage.contacts[].org.titlestring | nullobrigatóriomessage.reactionobject | nullobrigatórioA reação a uma mensagem, ou a retirada dela.message.reaction.wamidstring | nullobrigatórioO wamid da mensagem que recebeu a reação.message.reaction.emojistring | nullobrigatórioO emoji. Nulo quando o interlocutor retirou a reação.message.contextobject | nullobrigatórioA resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.message.context.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor citou ao responder.message.context.fromstring | nullobrigatórioQuem enviou a mensagem citada.message.context.forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada.message.context.frequently_forwardedboolean | nullobrigatórioVerdadeiro quando a mensagem foi encaminhada muitas vezes.message.referralobject | nullobrigatórioO anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.message.referral.source_typestring | nullobrigatórioA origem do clique, como ad ou post.message.referral.source_idstring | nullobrigatórioO identificador do anúncio ou da publicação na Meta.message.referral.source_urlstring | nullobrigatórioO endereço do anúncio ou da publicação.message.referral.headlinestring | nullobrigatórioO título do anúncio.message.referral.bodystring | nullobrigatórioO texto do anúncio.message.referral.media_typestring | nullobrigatórioO tipo da mídia do anúncio, como image ou video.message.referral.ctwa_clidstring | nullobrigatórioO identificador do clique, para atribuição de conversão.message.unsupportedobject | nullobrigatórioPresente 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 | nullobrigatórioO código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").message.unsupported.titlestring | nullobrigatórioO título do erro, como a Meta o mandou.message.unsupported.detailsstring | nullobrigatórioO detalhe do erro, como a Meta o mandou.message.editobject | nullobrigatórioPresente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).message.edit.wamidstring | nullobrigatórioO wamid da mensagem que foi editada.message.edit.typestring | nullobrigatórioO tipo do conteúdo novo, como text.message.edit.textstring | nullobrigatórioO texto novo, quando o conteúdo novo é texto.message.revokeobject | nullobrigatórioPresente quando o interlocutor apagou uma mensagem para todos (type é revoke).message.revoke.wamidstring | nullobrigatórioO wamid da mensagem que o interlocutor apagou para todos.message.orderobject | nullobrigatórioO pedido que o interlocutor montou num catálogo e enviou (type é order).message.order.catalog_idstring | nullobrigatórioO catálogo de onde veio o pedido.message.order.textstring | nullobrigatórioO texto que o interlocutor escreveu junto com o pedido.message.order.itemsarray<object> | nullobrigatórioOs itens do pedido.message.order.items[].product_retailer_idstring | nullobrigatórioO identificador do produto no seu catálogo.message.order.items[].quantitystring | nullobrigatórioA quantidade pedida, como a Meta mandou.message.order.items[].item_pricestring | nullobrigatórioO preço unitário, como a Meta mandou.message.order.items[].currencystring | nullobrigatórioA moeda do preço.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "01b53d46e858f6ab6c89e183ef9509d703f665f6cfe2eb1d6bb185df56224d88",
"event_type": "message.echo",
"occurred_at": "2026-10-07T13:02:30.250Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"message": {
"id": "9a3e6b14-5c2d-4f81-b7a0-2d8e1c4f6a93",
"wamid": "wamid.EXAMPLE_ECHO",
"wa_id": "5511900000000",
"user_id": "BR.13491208655302741918",
"parent_user_id": null,
"username": null,
"type": "text",
"text": "Oi, Maria! Já separei o seu pedido, sai hoje.",
"profile_name": null,
"media": null,
"interactive": null,
"button": null,
"location": null,
"contacts": null,
"reaction": null,
"context": null,
"referral": null,
"unsupported": null,
"edit": null,
"revoke": null,
"order": null
}
}Estado de um template mudou
EVENTtemplate.status
A Meta aprovou, rejeitou, pausou ou desativou um template, e quando houver motivo ele vem junto. Não tem número nem mensagem.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idnullobrigatórioSempre null neste tipo: o template pertence à conta de negócio, e não a um número.testtrueopcionalPresente, 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.numbernullobrigatórioSempre null neste tipo: o evento não passa por um número.event_type"template.status"obrigatóriotemplateobjectobrigatórioO 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)obrigatórioO identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.template.namestringobrigatórioO nome do template.template.languagestringobrigatórioO idioma do template, no código da Meta.template.waba_idstringobrigatórioA 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 | nullobrigatórioO 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.statusstringobrigatórioO novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer.template.categorystringobrigatórioA categoria do template, no vocabulário da Meta.template.reasonstring | nullobrigatórioO motivo que a Meta informou para a rejeição ou a pausa. Nulo quando ela não informa um, como nas aprovações.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "821d41ec2c33a28abe8a0baf97db034baaef1dbe511a6e546a37eca4ad565c65",
"event_type": "template.status",
"occurred_at": "2026-10-07T13:20:00.000Z",
"phone_number_id": null,
"number": null,
"template": {
"id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
"name": "confirmacao_de_pedido",
"language": "pt_BR",
"waba_id": "102290129340398",
"external_id": "cliente-8841",
"status": "REJECTED",
"category": "UTILITY",
"reason": "INVALID_FORMAT"
}
}Número conectado
EVENTnumber.connected
Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão que você abriu com o link de conexão, e traz o externalId dele.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioUm 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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_idstringobrigatórioA 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.coexistencebooleanobrigatóriotrue 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"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "458470a340db14358f03ac02fde7e3839cb6887f3071c06c57a3d9d456621996",
"event_type": "number.connected",
"occurred_at": "2026-10-07T13:45:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398",
"coexistence": false
}
}Número aguardando método de pagamento na Meta
EVENTnumber.payment_required
A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). Sai uma vez ao entrar no estado, e não a cada mensagem recusada. Quem resolve é o dono da conta, no WhatsApp Manager da Meta: a Luna não intermedeia esse pagamento. O guia Pagamento na Meta explica o que dizer ao seu cliente.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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_sincestringobrigatórioQuando 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"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "50a49cee4b216c529e3f7cdd0be525f8902ff6aff66439e004dfe34a0c979fcf",
"event_type": "number.payment_required",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"awaiting_payment_since": "2026-10-13T12:00:00.000Z"
}
}Número voltou a enviar depois da espera por pagamento
EVENTnumber.payment_resolved
Um envio deste número voltou a ser aceito pela Meta depois de uma espera por método de pagamento. É o único sinal de que o pagamento foi regularizado: a Meta não avisa e não oferece consulta. As mensagens recusadas durante a espera não são reenviadas sozinhas.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioUm 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "6a956161dd17bb975533e63286e811ae62b77b3350107945952b2e53f0a9d1e2",
"event_type": "number.payment_resolved",
"occurred_at": "2026-10-13T15:30:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841"
}
}Conta restrita pela Meta
EVENTaccount.restricted
A Meta restringiu a conta de WhatsApp Business do número. Traz o tipo, o prazo e a orientação da Meta em restrictions. O aviso é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. Quem resolve é o dono da conta, no WhatsApp Manager. O guia Saúde da conta explica cada caso.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriowabaobjectobrigatórioA 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_idstringobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullobrigatórioO 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>obrigatórioAs restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar.waba.restrictions[].restriction_typestring | nullobrigatórioO tipo da restrição, no vocabulário da Meta.waba.restrictions[].expirationstring | nullobrigatórioQuando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo.waba.restrictions[].remediationstring | nullobrigatórioO que a Meta diz que resolve a restrição, quando informa.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "d3b1b97cb8b69ac0bf9db087b5200febbea3dcbcc8d0a4108913592b51fdaf29",
"event_type": "account.restricted",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"waba": {
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"restrictions": [
{
"restriction_type": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
"expiration": "2026-11-13T12:00:00Z",
"remediation": null
}
]
}
}Violação de política na conta
EVENTaccount.violation
A Meta registrou uma violação de política na conta de WhatsApp Business do número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. Sai um evento por número da conta.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriowabaobjectobrigatórioA 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_idstringobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullobrigatórioO 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 | nullobrigatórioO tipo da violação, no vocabulário da Meta.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "a2fa828795bf24fd8e7460738c1a1e11a1bcd278fc09a0d238f92ba8c5994441",
"event_type": "account.violation",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"waba": {
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"violation_type": "ALCOHOL_VIOLATION"
}
}Conta desativada pela Meta
EVENTaccount.disabled
A Meta desativou a conta de WhatsApp Business do número, e os envios deixam de ser aceitos. A Luna não reativa conta: o dono pede revisão à Meta. Sai um evento por número da conta, e account.reinstated avisa se a conta voltar.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriowabaobjectobrigatórioA 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_idstringobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullobrigatórioO 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 | nullobrigatórioA data da desativação, como a Meta informou.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "b0308dcc1ab6324eaea0474f1bcdec28146d3a6eb62668a1425fb3a7d6aad778",
"event_type": "account.disabled",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"waba": {
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"ban_date": "2026-10-13"
}
}Conta reativada pela Meta
EVENTaccount.reinstated
A Meta reativou a conta de WhatsApp Business do número depois de uma desativação. Sai um evento por número da conta.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriowabaobjectobrigatórioA Meta reativou a conta de WhatsApp Business deste número depois de uma desativação.waba.waba_idstringobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullobrigatórioO 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 | nullobrigatórioA data informada pela Meta junto com a reativação, quando houver.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "135a9c7b3f192a7cab5ea55f68e0a8113e8d8e80acaa0ae8dad7f20aaf61f2db",
"event_type": "account.reinstated",
"occurred_at": "2026-10-14T09:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"waba": {
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"ban_date": null
}
}Outro aviso de conta da Meta
EVENTaccount.update
Um aviso de conta da Meta que a Luna não traduz em tipo próprio, com o campo event cru dela (por exemplo ACCOUNT_DELETED, ACCOUNT_RECONNECTED ou VOLUME_BASED_PRICING_TIER_UPDATE). Se você não usa, ignore.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriowabaobjectobrigatórioUm 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_idstringobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullobrigatórioO 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.eventstringobrigatórioO 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.detailsobjectobrigatórioO restante do aviso da Meta, como ela mandou, sem o campo event.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "f663ad9f077e865db5d29245db96fe579e9aaa487bdf2f9d91a6e535af3d7949",
"event_type": "account.update",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"waba": {
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"event": "ACCOUNT_DELETED",
"details": {}
}
}Limite da conta mudou
EVENTaccount.limit_changed
A Meta mudou o limite da conta: o limite de mensagens, que conta pessoas únicas fora da janela de atendimento (TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED), ou o de números. É o teto concedido, e nunca quanto foi usado. Vale para o portfólio inteiro, então sai um evento por número da conta.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriowabaobjectobrigatórioA 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_idstringobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullobrigatórioO 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 | nullobrigatórioO 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 | nullobrigatórioQuantos números a Meta permite nesta conta. Nulo quando o aviso mudou só o limite de conversas.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "a3bddf693de91539edaebb432d0d4f936b40822085cafa5c7864ae149756dbff",
"event_type": "account.limit_changed",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"waba": {
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"daily_conversation_limit": "TIER_2K",
"max_phone_numbers_per_waba": null
}
}Número desconectado
EVENTnumber.disconnected
O número deixou de estar conectado à Luna: o cliente removeu o aplicativo, a Luna foi removida como parceira da conta, o vínculo da conta com a Luna foi encerrado, ou você o desconectou com DELETE /v1/numbers/{id} (reason requested_by_tenant). É o par de number.connected. Para voltar, o seu cliente conecta de novo com um novo link de conexão. Traz o motivo no campo reason.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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_idstringobrigatórioA 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.reasonstringobrigatórioO 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 | nullobrigatórioO motivo que a Meta informou em disconnection_info, quando informa.number.initiated_bystring | nullobrigatórioQuem iniciou a desconexão, como a Meta informou.event_type"number.disconnected"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "0dfe4e31d4e40e4a5da6d3f42f0d44b660f67ce551b2a43966e5fb0390fcd741",
"event_type": "number.disconnected",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398",
"reason": "PARTNER_APP_UNINSTALLED",
"disconnection_reason": null,
"initiated_by": null
}
}Qualidade do número mudou
EVENTnumber.quality_changed
A avaliação de qualidade do número mudou (GREEN, YELLOW, RED). A Meta não tem webhook para isso: a Luna confere a qualidade periodicamente, então o evento chega com atraso de até cerca de uma hora. O histórico está em GET /v1/numbers/{id}/health.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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_idstringobrigatórioA 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_ratingstringobrigatórioA avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED.number.quality_ratingstringobrigatórioA avaliação de qualidade atual, no vocabulário da Meta.event_type"number.quality_changed"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "cc81de4eb28ad6a80e39c6cca13eb4b6db12f223f3c1346552cbc24795bcdbbe",
"event_type": "number.quality_changed",
"occurred_at": "2026-10-13T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398",
"previous_quality_rating": "GREEN",
"quality_rating": "YELLOW"
}
}Nome de exibição revisado
EVENTnumber.display_name_reviewed
O estado da revisão do nome de exibição do número mudou (status: approved, pending_review, declined, expired ou none), por exemplo de pending_review para approved ou declined. name é o nome a que o estado se refere. A Meta não informa o motivo de uma recusa nesta consulta. A Luna confere o nome periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo. O estado corrente está em displayNameStatus, em GET /v1/numbers/{id}.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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_idstringobrigatórioA 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.statusstringobrigatórioO 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 | nullobrigatórioO 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"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "23fd01fabc59f4c9ffda20955726e7e3e19c6a05cf609197c8b3c0aef8405e76",
"event_type": "number.display_name_reviewed",
"occurred_at": "2026-11-04T14:20:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398",
"status": "declined",
"name": "Clínica Sorriso Centro"
}
}Autorização do cliente perto de vencer
EVENTnumber.credential_expiring
A autorização que o cliente deu à Luna para operar o número vence em até 14 dias (credential_expires_at). Para renovar, o cliente refaz a conexão: crie um link com POST /v1/onboarding/links informando numberId e ele abre direto a reconexão deste número, sem contar um número novo. Sai uma vez por vencimento e por número da conta. Autorização emitida sem prazo nunca gera este evento.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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_idstringobrigatórioA 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_atstringobrigatórioQuando 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"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "33b03111fe7f1f225626ece55b50955389e78742a6b99059f05be056ce2b2260",
"event_type": "number.credential_expiring",
"occurred_at": "2026-11-21T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398",
"credential_expires_at": "2026-12-05T12:00:00.000Z"
}
}Alerta da Meta sobre a conta
EVENTaccount.alert
A Meta mandou um alerta sobre a conta de WhatsApp Business do número (o campo account_alerts), por exemplo a negativa de um aumento de limite ou a perda da foto de perfil. Os campos chegam como a Meta mandou, sem tradução. O alerta é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriowabaobjectobrigatórioA 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_idstringobrigatórioA 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.waba.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.waba.external_idstring | nullobrigatórioO 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 | nullobrigatórioA que o alerta se refere, como a Meta informou (por exemplo a conta, o portfólio ou um número).waba.entity_idstring | nullobrigatórioO identificador, na Meta, do que o alerta cita.waba.alert_severitystring | nullobrigatórioA gravidade que a Meta atribuiu ao alerta, no vocabulário dela.waba.alert_statusstring | nullobrigatórioSe o alerta está ativo ou foi resolvido, no vocabulário da Meta.waba.alert_typestring | nullobrigatórioO 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 | nullobrigatórioA descrição do alerta, em texto, como a Meta mandou.waba.detailsobjectobrigatórioO restante do alerta, como a Meta mandou, para o que a Luna ainda não nomeia.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "fb613a0660724669d9251d4185488ec26409b34345c592b908ce9747b8430f99",
"event_type": "account.alert",
"occurred_at": "2026-10-19T12:00:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"external_id": "cliente-8841"
},
"waba": {
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"entity_type": "WABA",
"entity_id": "102290129340398",
"alert_severity": "INFORMATIONAL",
"alert_status": "ACTIVE",
"alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
"alert_description": "Messaging limit increase deferred.",
"details": {}
}
}Número precisa de ação
EVENTnumber.action_required
Este número passou a precisar de uma ação sua ou do seu cliente: autorização do cliente vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Traz status, can_send e reasons, cada motivo com code, message e solution, prontos para você mostrar ao seu cliente. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela; é o mesmo cálculo de connection em GET /v1/numbers/{id}. Quando a lista esvazia, sai number.action_resolved.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioEste 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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.statusstringobrigatórioO estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}.Valores:connectedconnectingaction_requireddisconnectednumber.can_sendbooleanobrigatórioSe o envio por este número vai funcionar agora, o mesmo de connection.canSend.number.reasonsarray<object>obrigatórioOs motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento.no mínimo 1 itensnumber.reasons[].codestringobrigatórioO 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[].messagestringobrigatórioO que está acontecendo, em português, pronto para repassar ao seu cliente.number.reasons[].solutionstringobrigatórioO que fazer a respeito, em português.event_type"number.action_required"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "8832cdd12544436fce3b39d709158baa046091d010b5ed144a289c81b807c710",
"event_type": "number.action_required",
"occurred_at": "2026-10-28T15:02:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"status": "action_required",
"can_send": false,
"reasons": [
{
"code": "payment_required",
"message": "A Meta recusou um envio deste número por falta de método de pagamento na conta de WhatsApp Business do negócio.",
"solution": "O dono da conta cadastra o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. Quando um envio voltar a ser aceito, o aviso sai do ar."
}
]
}
}Número não precisa mais de ação
EVENTnumber.action_resolved
O número deixou de precisar de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou. Um número que você desconectou não gera este evento: number.disconnected já avisou.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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.numberobjectobrigatórioEste 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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.statusstringobrigatórioO estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}.Valores:connectedconnectingaction_requireddisconnectednumber.can_sendbooleanobrigatórioSe o envio por este número vai funcionar agora, o mesmo de connection.canSend.event_type"number.action_resolved"obrigatório
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "3279de99ef1bc2ade5d88bde7a2fd878b8faabddc179b8dceebded74d5b7394b",
"event_type": "number.action_resolved",
"occurred_at": "2026-10-28T15:40:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"status": "connected",
"can_send": true
}
}Link de conexão concluído
EVENTonboarding.link.completed
O seu cliente concluiu a conexão por um link: o link passa a used. Traz o externalId do link e, quando a Luna já registrou o número, number_id; o evento number.connected avisa quando o número fica pronto para enviar. Sai uma vez por link.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstring | nullobrigatórioO número do link de reconexão ou o que resultou da conexão, ou null quando o evento não tem número.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.display_numberstring | nullobrigatórioO número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.number.external_idstring | nullobrigatórioO 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_idstringobrigatórioA 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"obrigatóriolinkobjectobrigatórioO 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)obrigatórioO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullobrigatórioO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.used_atstringobrigatórioQuando a conexão por este link concluiu, o mesmo usedAt de GET /v1/onboarding/links/{id}.link.waba_idstring | nullobrigatórioA 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) | nullobrigatórioO 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.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "fd3596b2273541c7a77c69cb8a2ddb0e060052ddc84f251b5a76961053b578b1",
"event_type": "onboarding.link.completed",
"occurred_at": "2026-10-28T15:30:12.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398"
},
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"used_at": "2026-10-28T15:30:12.000Z",
"waba_id": "102290129340398",
"number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b"
}
}Link de conexão aberto
EVENTonboarding.link.opened
O seu cliente abriu o link pela primeira vez. Sai uma vez por link, e não de novo quando ele volta à página ou tenta outra vez. Traz o externalId do link e opened_at. É o começo do ciclo: depois vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstring | nullobrigatórioO número do link de reconexão, ou null quando o link é de uma conexão nova.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriolinkobjectobrigatórioO 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)obrigatórioO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullobrigatórioO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.opened_atstringobrigatórioQuando o seu cliente abriu o link pela primeira vez.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "b8a277c5c9377c213ee4c3b79c3e83829f3bef5f69521db1a0434da05acfbc1d",
"event_type": "onboarding.link.opened",
"occurred_at": "2026-10-28T15:21:40.000Z",
"phone_number_id": null,
"number": null,
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"opened_at": "2026-10-28T15:21:40.000Z"
}
}Tentativa de conexão pelo link não deu certo
EVENTonboarding.link.failed
Uma tentativa de conexão por um link não deu certo. reason diz por quê: abandoned (o cliente fechou a janela da Meta, e step traz a tela em que parou), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir e não conseguiu), country_not_supported (o número não é +55) ou registration_blocked (a Meta bloqueou o registro por 72 horas). O link continua aberto até vencer. Sai uma vez por tentativa.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstring | nullobrigatórioO número do link de reconexão, ou null quando o link é de uma conexão nova.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriolinkobjectobrigatórioUma 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)obrigatórioO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullobrigatórioO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.session_idstring (uuid)obrigatórioA tentativa de conexão que não deu certo. Um link aberto admite várias.link.reasonstringobrigatórioPor que a tentativa não deu certo: abandoned (o cliente fechou a janela da Meta e a tela em que parou está em step), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir várias vezes e não conseguiu), country_not_supported (o número escolhido não é +55) ou registration_blocked (a Meta bloqueou o registro do número por 72 horas). Novos motivos podem aparecer.Valores:abandonederrorfailedcountry_not_supportedregistration_blockedlink.stepstring | nullobrigatórioO 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 | nullobrigatórioO código de erro que a janela da Meta relatou. Nulo quando não houve erro relatado.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "cabf3f3478bda2efd0e9a3726d503dbcd575bec16cc0ccf5fc65cdcb4c88cea3",
"event_type": "onboarding.link.failed",
"occurred_at": "2026-10-28T15:12:40.000Z",
"phone_number_id": null,
"number": null,
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"session_id": "2e8f4b60-1a3c-4d57-9b0e-6c7d8e9f0a12",
"reason": "abandoned",
"step": "phone_number_setup",
"error_code": null
}
}Link de conexão venceu
EVENTonboarding.link.expired
O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link usado nunca gera este evento. Sai uma vez por link.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idstring | nullobrigatórioO número do link de reconexão, ou null quando o link é de uma conexão nova.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/testtrueopcionalPresente, 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 | nullobrigatórioO 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)obrigatórioO identificador do número na Luna, o mesmo que GET /v1/numbers devolve.number.phone_number_idstringobrigatórioO identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/number.external_idstring | nullobrigatórioO 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"obrigatóriolinkobjectobrigatórioO 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)obrigatórioO identificador do link, o mesmo que POST /v1/onboarding/links devolveu.link.external_idstring | nullobrigatórioO externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele.link.expired_atstringobrigatórioQuando o link venceu, o mesmo expiresAt de GET /v1/onboarding/links/{id}.
Exemplo do corpo entregue
{
"version": "2026-11-10",
"event_id": "1df73af80cf86f74267290bc13fcd1f82551997dd79845170b35c78f40b563ad",
"event_type": "onboarding.link.expired",
"occurred_at": "2026-10-31T15:00:00.000Z",
"phone_number_id": null,
"number": null,
"link": {
"id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21",
"external_id": "cliente-8841",
"expired_at": "2026-10-31T15:00:00.000Z"
}
}Categoria de um template mudou
EVENTtemplate.category
A Meta mudou, ou avisou que vai mudar, a categoria de um template. A categoria define o preço que a Meta cobra do negócio: de UTILITY para MARKETING, o preço sobe. Chega como aviso prévio (correct_category e scheduled_for) e como mudança feita (previous_category e new_category). Não tem número nem mensagem.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idnullobrigatórioSempre null neste tipo: o template pertence à conta de negócio, e não a um número.testtrueopcionalPresente, 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.numbernullobrigatórioSempre null neste tipo: o evento não passa por um número.event_type"template.category"obrigatóriotemplateobjectobrigatórioA 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)obrigatórioO identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.template.namestringobrigatórioO nome do template.template.languagestringobrigatórioO idioma do template, no código da Meta.template.waba_idstringobrigatórioA 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 | nullobrigatórioO 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.categorystringobrigatórioA categoria do template, no vocabulário da Meta.template.previous_categorystring | nullobrigatórioA categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio.template.new_categorystring | nullobrigatórioA categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio.template.correct_categorystring | nullobrigatórioNo 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 | nullobrigatórioNo aviso prévio, quando a Meta aplica a mudança. Nulo quando a mudança já foi feita.
Exemplo do corpo entregue
{
"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
}
}Qualidade de um template mudou
EVENTtemplate.quality
A nota de qualidade de um template mudou (GREEN, YELLOW, RED). Nota baixa antecede a pausa do template pela Meta. Não tem número nem mensagem.
Corpo da requisição
version"2026-11-10"obrigatórioA versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.event_idstringobrigatórioO identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteresoccurred_atstringobrigatórioQuando o evento ocorreu, em UTC.phone_number_idnullobrigatórioSempre null neste tipo: o template pertence à conta de negócio, e não a um número.testtrueopcionalPresente, 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.numbernullobrigatórioSempre null neste tipo: o evento não passa por um número.event_type"template.quality"obrigatóriotemplateobjectobrigatórioA 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)obrigatórioO identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.template.namestringobrigatórioO nome do template.template.languagestringobrigatórioO idioma do template, no código da Meta.template.waba_idstringobrigatórioA 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 | nullobrigatórioO 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 | nullobrigatórioA nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN.template.new_quality_scorestring | nullobrigatórioA nota de qualidade de agora, no vocabulário da Meta.
Exemplo do corpo entregue
{
"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"
}
}