LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Saúde da conta

Usar com IA

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.

EventoQuando saiO que o seu sistema faz
account.restrictedA Meta restringiu a conta.Ler o tipo e o prazo, avisar o cliente, ajustar o que a restrição impede.
account.violationA Meta registrou uma violação de política.Tratar a causa antes que vire restrição.
account.disabledA Meta desativou a conta.Parar de tentar enviar e pedir revisão à Meta.
account.reinstatedA Meta reativou a conta.Voltar a enviar.
number.disconnectedO número deixou de estar conectado à Luna.Abrir um novo link de conexão.
account.limit_changedA Meta mudou o limite da conta.Ajustar o ritmo de envio ao novo teto.
number.quality_changedA qualidade do número mudou.Reduzir o que gera reclamação.
account.alertA Meta mandou um alerta sobre a conta (account_alerts).Ler o alert_type e a descrição, e avisar o cliente.
number.credential_expiringA 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.updateOutro 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.

Uma conta restrita, em GET /v1/business-accountsJSON
{
  "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á.

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
      }
    ]
  }
}
  • 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 leia status.restricted em GET /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.

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"
  }
}
  • 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.violationType guarda 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.

DesativadaJSON
{
  "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"
  }
}
ReativadaJSON
{
  "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 por status.disabled igual a false em GET /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.

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
  }
}
  • 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 com connection.status: "action_required", canSend: false e o motivo credential_invalid em connection.reasons, e a reconexão é pelo link (POST /v1/onboarding/links com numberId). Quando você desconecta com DELETE /v1/numbers/{id} (reason: "requested_by_tenant"), o número fica connection.status: "disconnected", canSend: false e reasons vazio. Para PARTNER_REMOVED e ACCOUNT_OFFBOARDED o evento é entregue, mas hoje só a desinstalação muda o estado do número sozinha: confira connection antes de concluir que ele parou. Então decida pelo reason do evento, ou leia connection em GET /v1/numbers/{id}, e não espere sempre disconnected.
  • 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.

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
  }
}
  • 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, em GET /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.

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

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"
  }
}
  • 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/links informando numberId, 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 seu externalId. O mesmo vale se credentialStatus já for reauth_required. A decisão de que a renovação cabe é da API: o campo podeReconectar de GET /v1/numbers/{id} passa a true a 14 dias do vencimento.
  • Onde ler sem webhook. credentialExpiresAt (a data) e credentialNeverExpires (true quando a Meta informou que não vence, nulo enquanto a Luna não leu) em GET /v1/business-accounts e no objeto waba de 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.

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": {}
  }
}
  • Causa. Depende do alert_type. O texto em alert_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_type como 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.

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

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.