Saúde da conta
Quando a Meta restringe, desativa ou desconecta a conta do seu cliente, o envio para de funcionar e o agente dele fica mudo. A Luna repassa esses avisos como eventos e guarda o último estado, para o seu sistema agir na hora em vez de descobrir pelo cliente final.
Um aviso da conta, um evento por número#
A Meta avisa a conta de negócio (a WABA), e não um número. O envelope da Luna é por número, então cada aviso sai uma vez para cada número conectado da conta, todos com o mesmo waba_id dentro do objeto waba. Para tratar o aviso uma só vez, junte pelo waba_id. Conta sem nenhum número conectado não gera evento; o estado dela continua em GET /v1/business-accounts.
| Evento | Quando sai | O que o seu sistema faz |
|---|---|---|
account.restricted | A Meta restringiu a conta. | Ler o tipo e o prazo, avisar o cliente, ajustar o que a restrição impede. |
account.violation | A Meta registrou uma violação de política. | Tratar a causa antes que vire restrição. |
account.disabled | A Meta desativou a conta. | Parar de tentar enviar e pedir revisão à Meta. |
account.reinstated | A Meta reativou a conta. | Voltar a enviar. |
number.disconnected | O número deixou de estar conectado à Luna. | Abrir um novo link de conexão. |
account.limit_changed | A Meta mudou o limite da conta. | Ajustar o ritmo de envio ao novo teto. |
number.quality_changed | A qualidade do número mudou. | Reduzir o que gera reclamação. |
account.alert | A Meta mandou um alerta sobre a conta (account_alerts). | Ler o alert_type e a descrição, e avisar o cliente. |
number.credential_expiring | A autorização que o cliente deu à Luna vence em até 14 dias. | Abrir um link de reconexão do número e mandar ao cliente. |
account.update | Outro aviso de conta que a Luna não traduz. | Ler o event cru e decidir, ou ignorar. |
Onde ler o estado, sem webhook#
A Meta não oferece consulta desse estado. A Luna guarda o último aviso que recebeu e o devolve em dois lugares. Em GET /v1/business-accounts, cada conta traz status, com restricted, restrictions, disabled, violationType e reportedAt. Em GET /v1/numbers e GET /v1/numbers/{id}, cada número traz waba, com id, restricted e disabled, pronto para uma tela mostrar sem calcular nada. Os dois lugares também trazem a validade da autorização do cliente (credentialExpiresAt e credentialNeverExpires) e a forma de pagamento na Meta (paymentMethodOnMeta e currency), descritas nas seções abaixo.
{
"id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
"wabaId": "102290129340398",
"numbers": ["+55 11 90000-0000"],
"status": {
"restricted": true,
"restrictions": [
{
"restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
"expiration": "2026-11-13T12:00:00Z",
"remediation": null
}
],
"disabled": false,
"violationType": null,
"reportedAt": "2026-10-13T12:00:00.000Z"
},
"createdAt": "2026-08-07T11:27:41.208Z"
}Conta restrita: `account.restricted`#
O que significa. A Meta impôs uma restrição à conta. O que ela impede depende do tipo, em restrictions[].restriction_type (por exemplo, adicionar números ou iniciar conversas). expiration traz o prazo como a Meta informou e remediation traz a orientação dela, quando há.
{
"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
}
]
}
}- Causa. Costuma vir de reclamações, de bloqueios pelos contatos ou de uso fora da política da Meta. A restrição por abuso de template de utilidade, por exemplo, segue uma escada de avisos da Meta antes de chegar aqui.
- Solução. Leia o tipo e o prazo, e avise o seu cliente. Quem trata a causa é o dono da conta, no WhatsApp Manager da Meta, pelo caminho que a própria Meta indica no aviso. Enquanto durar, não insista no que a restrição impede.
- Como saber que acabou. A Meta não avisa o fim de uma restrição por prazo. Confira
expiration, ou leiastatus.restrictedemGET /v1/business-accounts, que deixa de valer quando o prazo passa.
Violação de política: `account.violation`#
O que significa. A Meta registrou uma violação de política na conta, com o tipo em violation_type. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada.
{
"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"
}
}- Causa. Conteúdo ou comportamento que a política da Meta não permite, indicado pelo tipo.
- Solução. Descubra qual conteúdo ou fluxo gerou a violação, corrija e avise o dono da conta. Violação não expira sozinha:
status.violationTypeguarda o último tipo avisado.
Conta desativada e reativada: `account.disabled` e `account.reinstated`#
O que significa. account.disabled diz que a Meta desativou a conta: os envios deixam de ser aceitos. account.reinstated diz que ela voltou. A Meta também avisa uma desativação agendada, e esse aviso chega como account.update com event igual a DISABLED_UPDATE, porque a conta ainda não está desativada.
{
"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"
}
}{
"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
}
}- Causa. Violação grave ou repetida da política da Meta, ou uma restrição que não foi resolvida.
- Solução. O dono da conta pede a revisão à Meta. A Luna não reativa conta e não tem como pedir isso por ele. Enquanto estiver desativada, pare de enviar: cada tentativa só falha.
- Como saber que voltou. Pelo
account.reinstated, ou porstatus.disabledigual afalseemGET /v1/business-accounts.
Número desconectado: `number.disconnected`#
O que significa. O número deixou de estar conectado à Luna. É o par de number.connected. O campo reason diz o aviso da Meta que causou a desconexão: 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). disconnection_reason e initiated_by trazem o que a Meta informou, quando informa.
{
"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
}
}- Causa. Quase sempre, o próprio cliente removeu o aplicativo no Business Manager dele.
- Em que estado o número fica. Depende da causa, e o nome do evento não é o nome do estado. Quando o cliente remove o aplicativo (
PARTNER_APP_UNINSTALLED), a autorização dele deixa de valer: o número fica comconnection.status: "action_required",canSend: falsee o motivocredential_invalidemconnection.reasons, e a reconexão é pelo link (POST /v1/onboarding/linkscomnumberId). Quando você desconecta comDELETE /v1/numbers/{id}(reason: "requested_by_tenant"), o número ficaconnection.status: "disconnected",canSend: falseereasonsvazio. ParaPARTNER_REMOVEDeACCOUNT_OFFBOARDEDo evento é entregue, mas hoje só a desinstalação muda o estado do número sozinha: confiraconnectionantes de concluir que ele parou. Então decida peloreasondo evento, ou leiaconnectionemGET /v1/numbers/{id}, e não espere sempredisconnected. - Solução. Os envios deste número não funcionam mais. Para voltar, o seu cliente precisa conectar de novo: abra um novo link de conexão (veja Conectar um número) e peça a ele para concluir. O histórico de mensagens continua em
GET /v1/messages.
Limite da conta: `account.limit_changed`#
O que significa. A Meta mudou o limite da conta. daily_conversation_limit é 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). Ele conta pessoas únicas a quem o negócio escreve fora da janela de atendimento, e não mensagens, e é do portfólio empresarial (business portfolio), compartilhado por todos os números dele. E max_phone_numbers_per_waba é o de números da conta. Um dos dois vem null quando o aviso mudou só o outro. É o teto concedido pela Meta, e nunca quanto foi usado. O limite é do portfólio de negócio, então vale para todos os números da conta.
{
"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
}
}- Causa. A Meta sobe o limite quando a qualidade é boa e o volume pede, e baixa quando a qualidade cai.
- Solução. Ajuste o ritmo de envio ao novo teto. O valor corrente de cada número está em
limiteDiarioDeConversas, emGET /v1/numbers.
Qualidade do número: `number.quality_changed`#
O que significa. A avaliação de qualidade do número mudou, de previous_quality_rating para quality_rating (GREEN, YELLOW, RED). A Meta não tem webhook para isso: a Luna confere a qualidade de cada número periodicamente, e o evento sai quando a conferência vê a mudança. Ele chega com atraso de até cerca de uma hora.
{
"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"
}
}- Causa. Os contatos bloqueiam ou denunciam o número, ou reclamam das mensagens.
- Solução. Reduza o que gera reclamação: mensagens que o contato não pediu, frequência alta, conteúdo fora do esperado. Qualidade baixa leva à queda de limite e, depois, à restrição. O histórico está em
GET /v1/numbers/{id}/health.
Autorização perto de vencer: `number.credential_expiring`#
O que significa. A autorização que o seu cliente deu à Luna para operar o número vence em até 14 dias (credential_expires_at). Essa autorização pode ter prazo (a configuração de conexão atual a emite com validade de 60 dias); quando ela vence, a Meta recusa as chamadas da Luna nessa conta e o número para de enviar e de receber. Este é o único aviso da família que vem antes do problema. A Luna lê a validade na conexão e confere de hora em hora, e o aviso sai uma vez por vencimento e por número da conta: renovar a autorização muda o vencimento e permite um aviso novo. Autorização emitida sem prazo nunca gera o evento.
{
"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"
}
}- Causa. O prazo da própria autorização. Nada deu errado do lado do seu cliente.
- Solução. Crie um link de reconexão com
POST /v1/onboarding/linksinformandonumberId, e mande ao seu cliente. A página abre direto a renovação daquele número, não conta um número novo e mantém o seuexternalId. O mesmo vale secredentialStatusjá forreauth_required. A decisão de que a renovação cabe é da API: o campopodeReconectardeGET /v1/numbers/{id}passa atruea 14 dias do vencimento. - Onde ler sem webhook.
credentialExpiresAt(a data) ecredentialNeverExpires(truequando a Meta informou que não vence, nulo enquanto a Luna não leu) emGET /v1/business-accountse no objetowabade cada número.
Alerta da Meta: `account.alert`#
O que significa. A Meta mandou um alerta sobre a conta (o campo account_alerts), por exemplo a negativa de um aumento de limite (INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED, INCREASED_CAPABILITIES_ELIGIBILITY_FAILED ou INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO) ou a perda da foto de perfil (PROFILE_PICTURE_LOST). Os campos chegam como a Meta mandou, sem tradução e sem lista fechada de valores: entity_type, entity_id, alert_severity, alert_status, alert_type e alert_description. O que a Luna ainda não nomeia vai em details. Como os outros avisos de conta, sai um evento por número conectado, todos com o mesmo waba_id.
{
"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": {}
}
}- Causa. Depende do
alert_type. O texto emalert_descriptioné o da Meta. - Solução. Mostre o alerta ao dono da conta e deixe que ele trate no WhatsApp Manager da Meta. Trate valores novos de
alert_typecomo informação, e não como erro: a Meta acrescenta tipos sem aviso.
Outros avisos: `account.update`#
Todo aviso de conta da Meta que não tem tipo próprio chega como account.update, com o campo event cru dela e o restante em details: ACCOUNT_DELETED, ACCOUNT_RECONNECTED, VOLUME_BASED_PRICING_TIER_UPDATE, a desativação agendada e o que a Meta acrescentar. A Luna não inventa um significado para eles. Se o seu sistema não usa, ignore.
{
"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": {}
}
}O que a Luna não faz#
- Não levanta restrição, não reativa conta e não pede revisão à Meta. Isso é do dono da conta.
- Não consulta o estado na Meta: ela não oferece essa consulta. O estado que a Luna devolve é o do último aviso que recebeu.
- Não bloqueia o seu envio por causa de uma restrição. Quem recusa é a Meta, e a recusa chega como erro na mensagem.
- Não cobra nada por esses avisos. A falta de método de pagamento na Meta tem guia próprio: Pagamento na Meta.
Os eventos têm o formato completo em Receber eventos, e os campos estão na referência da API. A mudança de categoria e de qualidade de template está em Templates.
Detalhes das rotas deste guia#
A referência da API diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência.
GET /v1/numbers/{id}/health#
limiteDiarioDeConversas é o LIMITE DE MENSAGENS da Meta, do portfólio empresarial (business portfolio) e não de cada número: conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, nas faixas TIER_250, TIER_2K, TIER_10K, TIER_100K e TIER_UNLIMITED. throughputLevel é VELOCIDADE, quantas mensagens por segundo a Meta processa. Cada transição carrega o valor vigente naquele ponto, e é assim que se descobre quando o limite subiu ou desceu. Nenhum dos dois conta o que já foi usado.
E há teto que sobe e teto que não sobe. throughputLevel descreve uma progressão que a Meta sobe sozinha conforme a qualidade do número. Um número conectado em coexistência, que continua funcionando no aplicativo de celular do negócio, tem teto FIXO e não entra nessa progressão. Quem separa os dois casos é tetoDeVazaoPorSegundo, logo ao lado: com valor, ele diz o teto fixo em mensagens por segundo; nulo, a progressão vale para este número. O valor vem do que a plataforma observou no tráfego, e não do rótulo que a Meta devolveu.
sincronizacaoDoHistorico conta a importação das conversas anteriores do aparelho, num número conectado em coexistência, e são QUATRO situações e não três. Nulo significa que não há importação para este número. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando: passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele, e aí não vai concluir e pedir de novo não muda isso.
Não leia o percentual sozinho. sincronizacaoProgresso é um rótulo que a plataforma da Meta atribui, e cem por cento NÃO significa sucesso: a recusa chega com o progresso que já havia sido registrado. Quem diz o desfecho é sincronizacaoDoHistorico, e só ele. E ausência não é progresso zero: nulo é não haver importação, e zero é uma importação que começou e ainda não andou.
A lista de transições traz uma entrada por MUDANÇA, e não uma por verificação. Um número cuja avaliação nunca mudou desde a conexão devolve a lista vazia, e isso significa estabilidade: não trate lista vazia como ausência de dado.
Quem separa os dois casos é checkedAt. Com instante, a plataforma perguntou à Meta e não encontrou mudança. Nulo, a verificação ainda não aconteceu para este número.
As transições vêm da mais recente para a mais antiga.