LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Eventos de webhook

Usar com IA

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ório
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringobrigatório
    O identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteres
  • occurred_atstringobrigatório
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringobrigatório
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • testtrueopcional
    Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.
  • numberobject | nullobrigatório
    O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número.
  • number.idstring (uuid)obrigatório
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringobrigatório
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • number.external_idstring | nullobrigatório
    O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes.
  • event_type"message.received"obrigatório
  • messageobjectobrigatório
    Uma mensagem que chegou de um interlocutor. Além de wamid, wa_id (que pode ser nulo), user_id, parent_user_id, username, type e text, ela traz o conteúdo que o tipo carrega (mídia, botão ou item clicado, resposta de Flow, localização, contatos, reação, pedido, edição, apagamento, aviso de tipo sem suporte), a citação, o anúncio de origem e o nome de perfil. Os nomes dentro desses campos são os da Meta. Todo campo está sempre presente, e é nulo quando não se aplica.
  • message.idstring (uuid)obrigatório
    O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem.
  • message.wamidstringobrigatório
    O identificador da mensagem na Meta.
  • message.wa_idstring | nullobrigatório
    O identificador do interlocutor na Meta, em E.164 sem o sinal de mais: o telefone. Nulo quando o usuário escreveu sem que o telefone apareça (nome de usuário adotado): use user_id.
  • message.user_idstring | nullobrigatório
    O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor.
  • message.parent_user_idstring | nullobrigatório
    O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.
  • message.usernamestring | nullobrigatório
    O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.
  • message.typestringobrigatório
    O tipo da mensagem, no vocabulário da Meta.
  • message.textstring | nullobrigatório
    O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title.
  • message.profile_namestring | nullobrigatório
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • message.mediaobject | nullobrigatório
  • message.media.mime_typestring | nullobrigatório
    O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu.
  • message.media.sha256string | nullobrigatório
    O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type.
  • message.media.captionstring | nullobrigatório
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • message.media.filenamestring | nullobrigatório
    O nome do arquivo. Só documento tem.
  • message.media.voiceboolean | nullobrigatório
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • message.media.animatedboolean | nullobrigatório
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • message.media.urlstring | nullobrigatório
    Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo.
  • message.interactiveobject | nullobrigatório
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • message.interactive.typestring | nullobrigatório
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • message.interactive.idstring | nullobrigatório
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • message.interactive.titlestring | nullobrigatório
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • message.interactive.descriptionstring | nullobrigatório
    A descrição do item da lista. Nula nos demais.
  • message.interactive.namestring | nullobrigatório
    O nome do Flow. Só em nfm_reply.
  • message.interactive.response_jsonstring | nullobrigatório
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • message.buttonobject | nullobrigatório
    O clique num botão de resposta rápida de um template.
  • message.button.payloadstring | nullobrigatório
    O payload que você definiu no botão de resposta rápida do template.
  • message.button.textstring | nullobrigatório
    O texto do botão.
  • message.locationobject | nullobrigatório
    A localização que o interlocutor compartilhou.
  • message.location.latitudenumber | nullobrigatório
    A latitude, em graus decimais.
  • message.location.longitudenumber | nullobrigatório
    A longitude, em graus decimais.
  • message.location.namestring | nullobrigatório
    O nome do lugar, quando o interlocutor escolheu um.
  • message.location.addressstring | nullobrigatório
    O endereço, quando há.
  • message.location.urlstring | nullobrigatório
    O endereço web do lugar, quando há.
  • message.contactsarray<object> | nullobrigatório
    Os cartões de contato que o interlocutor compartilhou.
  • message.contacts[].nameobject | nullobrigatório
    O nome do contato, nos campos da Meta.
  • message.contacts[].name.formatted_namestring | nullobrigatório
  • message.contacts[].name.first_namestring | nullobrigatório
  • message.contacts[].name.last_namestring | nullobrigatório
  • message.contacts[].name.middle_namestring | nullobrigatório
  • message.contacts[].name.prefixstring | nullobrigatório
  • message.contacts[].name.suffixstring | nullobrigatório
  • message.contacts[].phonesarray<object> | nullobrigatório
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • message.contacts[].phones[].phonestring | nullobrigatório
  • message.contacts[].phones[].wa_idstring | nullobrigatório
  • message.contacts[].phones[].typestring | nullobrigatório
  • message.contacts[].emailsarray<object> | nullobrigatório
    Os e-mails do contato.
  • message.contacts[].emails[].emailstring | nullobrigatório
  • message.contacts[].emails[].typestring | nullobrigatório
  • message.contacts[].orgobject | nullobrigatório
    A organização do contato.
  • message.contacts[].org.companystring | nullobrigatório
  • message.contacts[].org.departmentstring | nullobrigatório
  • message.contacts[].org.titlestring | nullobrigatório
  • message.reactionobject | nullobrigatório
    A reação a uma mensagem, ou a retirada dela.
  • message.reaction.wamidstring | nullobrigatório
    O wamid da mensagem que recebeu a reação.
  • message.reaction.emojistring | nullobrigatório
    O emoji. Nulo quando o interlocutor retirou a reação.
  • message.contextobject | nullobrigatório
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • message.context.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor citou ao responder.
  • message.context.fromstring | nullobrigatório
    Quem enviou a mensagem citada.
  • message.context.forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada.
  • message.context.frequently_forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • message.referralobject | nullobrigatório
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • message.referral.source_typestring | nullobrigatório
    A origem do clique, como ad ou post.
  • message.referral.source_idstring | nullobrigatório
    O identificador do anúncio ou da publicação na Meta.
  • message.referral.source_urlstring | nullobrigatório
    O endereço do anúncio ou da publicação.
  • message.referral.headlinestring | nullobrigatório
    O título do anúncio.
  • message.referral.bodystring | nullobrigatório
    O texto do anúncio.
  • message.referral.media_typestring | nullobrigatório
    O tipo da mídia do anúncio, como image ou video.
  • message.referral.ctwa_clidstring | nullobrigatório
    O identificador do clique, para atribuição de conversão.
  • message.unsupportedobject | nullobrigatório
    Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso".
  • message.unsupported.codeinteger | nullobrigatório
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • message.unsupported.titlestring | nullobrigatório
    O título do erro, como a Meta o mandou.
  • message.unsupported.detailsstring | nullobrigatório
    O detalhe do erro, como a Meta o mandou.
  • message.editobject | nullobrigatório
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • message.edit.wamidstring | nullobrigatório
    O wamid da mensagem que foi editada.
  • message.edit.typestring | nullobrigatório
    O tipo do conteúdo novo, como text.
  • message.edit.textstring | nullobrigatório
    O texto novo, quando o conteúdo novo é texto.
  • message.revokeobject | nullobrigatório
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • message.revoke.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor apagou para todos.
  • message.orderobject | nullobrigatório
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • message.order.catalog_idstring | nullobrigatório
    O catálogo de onde veio o pedido.
  • message.order.textstring | nullobrigatório
    O texto que o interlocutor escreveu junto com o pedido.
  • message.order.itemsarray<object> | nullobrigatório
    Os itens do pedido.
  • message.order.items[].product_retailer_idstring | nullobrigatório
    O identificador do produto no seu catálogo.
  • message.order.items[].quantitystring | nullobrigatório
    A quantidade pedida, como a Meta mandou.
  • message.order.items[].item_pricestring | nullobrigatório
    O preço unitário, como a Meta mandou.
  • message.order.items[].currencystring | nullobrigatório
    A moeda do preço.

Exemplo do corpo entregue

JSON
{
  "version": "2026-11-10",
  "event_id": "1fd66b6f86489c36c3552f14dbf49f50df6b2d946c259f7b0eaa0ef88f58adb5",
  "event_type": "message.received",
  "occurred_at": "2026-10-06T14:05:40.120Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "7d1c4b8e-2a3f-4e5d-9c6b-1f0a2b3c4d5e",
    "wamid": "wamid.EXAMPLE_BUTTON_CLICK",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "interactive",
    "text": null,
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": {
      "type": "button_reply",
      "id": "rastrear",
      "title": "Rastrear pedido",
      "description": null,
      "name": null,
      "response_json": null
    },
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": {
      "wamid": "wamid.EXAMPLE_MESSAGE_WITH_BUTTONS",
      "from": "5511900000001",
      "forwarded": null,
      "frequently_forwarded": null
    },
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
JSON
{
  "version": "2026-11-10",
  "event_id": "0ab56cecd18b825ebeb4548219cb8fe392fec9e56301e52be1086f3c734ace86",
  "event_type": "message.received",
  "occurred_at": "2026-10-06T14:07:03.900Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "4c9e2d1a-8b7f-4a6c-b5d3-0e1f2a3b4c5d",
    "wamid": "wamid.EXAMPLE_IMAGE",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "image",
    "text": null,
    "profile_name": "Maria Souza",
    "media": {
      "mime_type": "image/jpeg",
      "sha256": "EXAMPLE_SHA256_OF_THE_FILE",
      "caption": "A nota fiscal do pedido",
      "filename": null,
      "voice": null,
      "animated": null,
      "url": "https://api.lunahia.com.br/v1/media/6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b.EXEMPLO_DO_SEGREDO_DE_43_CARACTERES_AAAAAAAA"
    },
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
JSON
{
  "version": "2026-11-10",
  "event_id": "a2f4909b0fd2db8ab8b1bfe4e16487f49b86113e27bf8c3c9d10a2d0fefebc72",
  "event_type": "message.received",
  "occurred_at": "2026-10-06T14:02:11.482Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51",
    "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "text",
    "text": "Oi! Queria saber o status do meu pedido.",
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
JSON
{
  "version": "2026-11-10",
  "event_id": "e2f81dd079e4419dac363779655be694a25cc502b7646be51cdac4b0cfc276fb",
  "event_type": "message.received",
  "occurred_at": "2026-11-03T14:02:11.482Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "c8a1e5d2-6f3b-4a7c-9e0d-1b2c3d4e5f60",
    "wamid": "wamid.EXAMPLE_NO_PHONE",
    "wa_id": null,
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": "mariasouza",
    "type": "text",
    "text": "Oi! Queria saber o status do meu pedido.",
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}
JSON
{
  "version": "2026-11-10",
  "event_id": "1eaa360e693d1a7366e66ba81d7bee362a56c2b4f4ef4854e43ad35861bd7ae1",
  "event_type": "message.received",
  "occurred_at": "2026-11-04T14:10:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "f3a8c1d2-5b6e-4f70-8a9b-0c1d2e3f4a5b",
    "wamid": "wamid.EXAMPLE_ORDER",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "order",
    "text": null,
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": null,
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": {
      "catalog_id": "EXAMPLE_CATALOG_ID",
      "text": "Quero estes dois, por favor.",
      "items": [
        {
          "product_retailer_id": "sku-001",
          "quantity": "2",
          "item_price": "49.90",
          "currency": "BRL"
        },
        {
          "product_retailer_id": "sku-002",
          "quantity": "1",
          "item_price": "15.00",
          "currency": "BRL"
        }
      ]
    }
  }
}
JSON
{
  "version": "2026-11-10",
  "event_id": "b9714a025db0a22bd3a63f9dfd9aa52aed7ddcae4efde825dfb2fa41e1736dd2",
  "event_type": "message.received",
  "occurred_at": "2026-11-04T14:12:30.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "external_id": "cliente-8841"
  },
  "message": {
    "id": "a4b9d2e3-6c7f-4081-9bac-1d2e3f4a5b6c",
    "wamid": "wamid.EXAMPLE_FLOW_REPLY",
    "wa_id": "5511900000000",
    "user_id": "BR.13491208655302741918",
    "parent_user_id": null,
    "username": null,
    "type": "interactive",
    "text": null,
    "profile_name": "Maria Souza",
    "media": null,
    "interactive": {
      "type": "nfm_reply",
      "id": null,
      "title": null,
      "description": null,
      "name": "flow",
      "response_json": "{\"flow_token\":\"EXAMPLE_FLOW_TOKEN\",\"nome\":\"Maria Souza\",\"data\":\"2026-11-10\"}"
    },
    "button": null,
    "location": null,
    "contacts": null,
    "reaction": null,
    "context": null,
    "referral": null,
    "unsupported": null,
    "edit": null,
    "revoke": null,
    "order": null
  }
}

Estado de uma mensagem que você enviou

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

Exemplo do corpo entregue

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

Contato trocou de telefone ou de BSUID

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

Exemplo do corpo entregue

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

Contato mudou uma preferência

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

Exemplo do corpo entregue

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

Eventos descartados por indisponibilidade

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

Exemplo do corpo entregue

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

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

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

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

Evento de teste

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ório
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringobrigatório
    O identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteres
  • occurred_atstringobrigatório
    Quando o evento ocorreu, em UTC.
  • phone_number_idnullobrigatório
    Sempre null neste tipo: o evento de teste não passa por nenhum número.
  • testtrueopcional
    Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.
  • numbernullobrigatório
    Sempre null neste tipo: o evento não passa por um número.
  • event_type"webhook.test"obrigatório
  • webhook_testobjectobrigatório
    Um evento de teste, enviado porque você pediu em POST /v1/webhooks/endpoints/{id}/test. Ele nunca aparece se você não pediu, não tem número nem conversa, e serve para conferir a URL e a verificação da assinatura.
  • webhook_test.endpoint_idstring (uuid)obrigatório
    O endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu.

Exemplo do corpo entregue

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

Resposta dada pelo aplicativo do celular

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ório
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringobrigatório
    O identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteres
  • occurred_atstringobrigatório
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringobrigatório
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • testtrueopcional
    Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.
  • numberobject | nullobrigatório
    O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número.
  • number.idstring (uuid)obrigatório
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringobrigatório
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • number.external_idstring | nullobrigatório
    O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes.
  • event_type"message.echo"obrigatório
  • messageobjectobrigatório
    Uma mensagem que o dono do negócio escreveu pelo aplicativo WhatsApp Business do celular, num número conectado em coexistência. Só ocorre em número conectado em coexistência. É o sinal para um agente automatizado ficar quieto na conversa: um humano respondeu. A forma é a de message.received, e wa_id é o destinatário. Todo campo está sempre presente, e é nulo quando não se aplica.
  • message.idstring (uuid)obrigatório
    O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem.
  • message.wamidstringobrigatório
    O identificador da mensagem na Meta.
  • message.wa_idstring | nullobrigatório
    O identificador do DESTINATÁRIO na Meta, em E.164 sem o sinal de mais: o cliente final para quem o dono do negócio escreveu. É a conversa onde o seu agente deve ficar quieto. Nulo quando a conversa é só de BSUID: use user_id.
  • message.user_idstring | nullobrigatório
    O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor.
  • message.parent_user_idstring | nullobrigatório
    O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais.
  • message.usernamestring | nullobrigatório
    O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais.
  • message.typestringobrigatório
    O tipo da mensagem, no vocabulário da Meta.
  • message.textstring | nullobrigatório
    O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title.
  • message.profile_namestring | nullobrigatório
    O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou.
  • message.mediaobject | nullobrigatório
  • message.media.mime_typestring | nullobrigatório
    O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu.
  • message.media.sha256string | nullobrigatório
    O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type.
  • message.media.captionstring | nullobrigatório
    A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma.
  • message.media.filenamestring | nullobrigatório
    O nome do arquivo. Só documento tem.
  • message.media.voiceboolean | nullobrigatório
    Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem.
  • message.media.animatedboolean | nullobrigatório
    Verdadeiro quando a figurinha é animada. Só figurinha tem.
  • message.media.urlstring | nullobrigatório
    Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo.
  • message.interactiveobject | nullobrigatório
    A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu.
  • message.interactive.typestring | nullobrigatório
    Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow).
  • message.interactive.idstring | nullobrigatório
    O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply.
  • message.interactive.titlestring | nullobrigatório
    O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply.
  • message.interactive.descriptionstring | nullobrigatório
    A descrição do item da lista. Nula nos demais.
  • message.interactive.namestring | nullobrigatório
    O nome do Flow. Só em nfm_reply.
  • message.interactive.response_jsonstring | nullobrigatório
    As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply.
  • message.buttonobject | nullobrigatório
    O clique num botão de resposta rápida de um template.
  • message.button.payloadstring | nullobrigatório
    O payload que você definiu no botão de resposta rápida do template.
  • message.button.textstring | nullobrigatório
    O texto do botão.
  • message.locationobject | nullobrigatório
    A localização que o interlocutor compartilhou.
  • message.location.latitudenumber | nullobrigatório
    A latitude, em graus decimais.
  • message.location.longitudenumber | nullobrigatório
    A longitude, em graus decimais.
  • message.location.namestring | nullobrigatório
    O nome do lugar, quando o interlocutor escolheu um.
  • message.location.addressstring | nullobrigatório
    O endereço, quando há.
  • message.location.urlstring | nullobrigatório
    O endereço web do lugar, quando há.
  • message.contactsarray<object> | nullobrigatório
    Os cartões de contato que o interlocutor compartilhou.
  • message.contacts[].nameobject | nullobrigatório
    O nome do contato, nos campos da Meta.
  • message.contacts[].name.formatted_namestring | nullobrigatório
  • message.contacts[].name.first_namestring | nullobrigatório
  • message.contacts[].name.last_namestring | nullobrigatório
  • message.contacts[].name.middle_namestring | nullobrigatório
  • message.contacts[].name.prefixstring | nullobrigatório
  • message.contacts[].name.suffixstring | nullobrigatório
  • message.contacts[].phonesarray<object> | nullobrigatório
    Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp.
  • message.contacts[].phones[].phonestring | nullobrigatório
  • message.contacts[].phones[].wa_idstring | nullobrigatório
  • message.contacts[].phones[].typestring | nullobrigatório
  • message.contacts[].emailsarray<object> | nullobrigatório
    Os e-mails do contato.
  • message.contacts[].emails[].emailstring | nullobrigatório
  • message.contacts[].emails[].typestring | nullobrigatório
  • message.contacts[].orgobject | nullobrigatório
    A organização do contato.
  • message.contacts[].org.companystring | nullobrigatório
  • message.contacts[].org.departmentstring | nullobrigatório
  • message.contacts[].org.titlestring | nullobrigatório
  • message.reactionobject | nullobrigatório
    A reação a uma mensagem, ou a retirada dela.
  • message.reaction.wamidstring | nullobrigatório
    O wamid da mensagem que recebeu a reação.
  • message.reaction.emojistring | nullobrigatório
    O emoji. Nulo quando o interlocutor retirou a reação.
  • message.contextobject | nullobrigatório
    A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada.
  • message.context.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor citou ao responder.
  • message.context.fromstring | nullobrigatório
    Quem enviou a mensagem citada.
  • message.context.forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada.
  • message.context.frequently_forwardedboolean | nullobrigatório
    Verdadeiro quando a mensagem foi encaminhada muitas vezes.
  • message.referralobject | nullobrigatório
    O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever.
  • message.referral.source_typestring | nullobrigatório
    A origem do clique, como ad ou post.
  • message.referral.source_idstring | nullobrigatório
    O identificador do anúncio ou da publicação na Meta.
  • message.referral.source_urlstring | nullobrigatório
    O endereço do anúncio ou da publicação.
  • message.referral.headlinestring | nullobrigatório
    O título do anúncio.
  • message.referral.bodystring | nullobrigatório
    O texto do anúncio.
  • message.referral.media_typestring | nullobrigatório
    O tipo da mídia do anúncio, como image ou video.
  • message.referral.ctwa_clidstring | nullobrigatório
    O identificador do clique, para atribuição de conversão.
  • message.unsupportedobject | nullobrigatório
    Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso".
  • message.unsupported.codeinteger | nullobrigatório
    O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte").
  • message.unsupported.titlestring | nullobrigatório
    O título do erro, como a Meta o mandou.
  • message.unsupported.detailsstring | nullobrigatório
    O detalhe do erro, como a Meta o mandou.
  • message.editobject | nullobrigatório
    Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit).
  • message.edit.wamidstring | nullobrigatório
    O wamid da mensagem que foi editada.
  • message.edit.typestring | nullobrigatório
    O tipo do conteúdo novo, como text.
  • message.edit.textstring | nullobrigatório
    O texto novo, quando o conteúdo novo é texto.
  • message.revokeobject | nullobrigatório
    Presente quando o interlocutor apagou uma mensagem para todos (type é revoke).
  • message.revoke.wamidstring | nullobrigatório
    O wamid da mensagem que o interlocutor apagou para todos.
  • message.orderobject | nullobrigatório
    O pedido que o interlocutor montou num catálogo e enviou (type é order).
  • message.order.catalog_idstring | nullobrigatório
    O catálogo de onde veio o pedido.
  • message.order.textstring | nullobrigatório
    O texto que o interlocutor escreveu junto com o pedido.
  • message.order.itemsarray<object> | nullobrigatório
    Os itens do pedido.
  • message.order.items[].product_retailer_idstring | nullobrigatório
    O identificador do produto no seu catálogo.
  • message.order.items[].quantitystring | nullobrigatório
    A quantidade pedida, como a Meta mandou.
  • message.order.items[].item_pricestring | nullobrigatório
    O preço unitário, como a Meta mandou.
  • message.order.items[].currencystring | nullobrigatório
    A moeda do preço.

Exemplo do corpo entregue

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

Estado de um template mudou

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ório
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringobrigatório
    O identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteres
  • occurred_atstringobrigatório
    Quando o evento ocorreu, em UTC.
  • phone_number_idnullobrigatório
    Sempre null neste tipo: o template pertence à conta de negócio, e não a um número.
  • testtrueopcional
    Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.
  • numbernullobrigatório
    Sempre null neste tipo: o evento não passa por um número.
  • event_type"template.status"obrigatório
  • templateobjectobrigatório
    O estado de um template mudou na Meta: aprovado, rejeitado, pausado, desativado ou outro. Não tem número nem conversa, porque o template pertence à conta de negócio.
  • template.idstring (uuid)obrigatório
    O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem.
  • template.namestringobrigatório
    O nome do template.
  • template.languagestringobrigatório
    O idioma do template, no código da Meta.
  • template.waba_idstringobrigatório
    A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId.
  • template.external_idstring | nullobrigatório
    O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts).
  • template.statusstringobrigatório
    O novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer.
  • template.categorystringobrigatório
    A categoria do template, no vocabulário da Meta.
  • template.reasonstring | nullobrigatório
    O 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

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

Número conectado

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

Exemplo do corpo entregue

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

Número aguardando método de pagamento na Meta

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

Exemplo do corpo entregue

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

Número voltou a enviar depois da espera por pagamento

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

Exemplo do corpo entregue

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

Conta restrita pela Meta

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

Exemplo do corpo entregue

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

Violação de política na conta

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

Exemplo do corpo entregue

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

Conta desativada pela Meta

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

Exemplo do corpo entregue

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

Conta reativada pela Meta

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

Exemplo do corpo entregue

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

Outro aviso de conta da Meta

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

Exemplo do corpo entregue

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

Limite da conta mudou

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

Exemplo do corpo entregue

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

Número desconectado

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

Exemplo do corpo entregue

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

Qualidade do número mudou

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

Exemplo do corpo entregue

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

Nome de exibição revisado

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

Exemplo do corpo entregue

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

Autorização do cliente perto de vencer

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

Exemplo do corpo entregue

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

Alerta da Meta sobre a conta

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

Exemplo do corpo entregue

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

Número precisa de ação

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

Exemplo do corpo entregue

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

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

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ório
    A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir.
  • event_idstringobrigatório
    O identificador estável deste evento. Use-o para descartar repetições.64 a 64 caracteres
  • occurred_atstringobrigatório
    Quando o evento ocorreu, em UTC.
  • phone_number_idstringobrigatório
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • testtrueopcional
    Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes.
  • numberobjectobrigatório
    Este número não precisa mais de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou (connected, ou connecting se a conexão voltou a estar em curso).
  • number.idstring (uuid)obrigatório
    O identificador do número na Luna, o mesmo que GET /v1/numbers devolve.
  • number.phone_number_idstringobrigatório
    O identificador do número na Meta, o mesmo que a listagem de números devolve.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • number.display_numberstring | nullobrigatório
    O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou.
  • number.external_idstring | nullobrigatório
    O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link.
  • number.statusstringobrigatório
    O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}.Valores: connected connecting action_required disconnected
  • number.can_sendbooleanobrigatório
    Se 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

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

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

Exemplo do corpo entregue

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

Qualidade de um template mudou

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

Exemplo do corpo entregue

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