# Saúde da conta

Fonte: https://lunahia.com.br/docs/saude-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.

Uma conta restrita, em GET /v1/business-accounts

```json
{
  "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"
}
```

> `restricted` só vale enquanto o prazo da restrição não passou, porque a Meta não avisa o fim de uma restrição por prazo. Se o prazo não puder ser lido como data, a restrição conta como ativa até um novo aviso, e `restrictions` devolve o valor como a Meta mandou para você conferir.

## 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.

Desativada

```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"
  }
}
```

Reativada

```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
  }
}
```

- **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](https://lunahia.com.br/docs/conectar-numero)) 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](https://lunahia.com.br/docs/pagamento-na-meta).

Os eventos têm o formato completo em [Receber eventos](https://lunahia.com.br/docs/receber-eventos), e os campos estão na [referência da API](https://lunahia.com.br/docs/referencia). A mudança de categoria e de qualidade de **template** está em [Templates](https://lunahia.com.br/docs/templates).

## Detalhes das rotas deste guia

A [referência da API](https://lunahia.com.br/docs/referencia) 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.
