LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Account health

Use with AI

When Meta restricts, deactivates or disconnects your customer’s account, sending stops working and their agent goes quiet. Luna passes these notices on as events and keeps the last state, so your system acts at once instead of finding out from the end customer.

One account notice, one event per number#

Meta notifies the business account (the WABA), not a number. Luna’s envelope is per number, so each notice is sent once for every connected number of the account, all with the same waba_id inside the waba object. To handle the notice only once, group by waba_id. An account with no connected number produces no event; its state stays in GET /v1/business-accounts.

EventWhen it is sentWhat your system does
account.restrictedMeta restricted the account.Read the type and the deadline, tell the customer, adjust what the restriction blocks.
account.violationMeta recorded a policy violation.Handle the cause before it becomes a restriction.
account.disabledMeta deactivated the account.Stop trying to send and ask Meta for a review.
account.reinstatedMeta reinstated the account.Resume sending.
number.disconnectedThe number is no longer connected to Luna.Open a new connect link.
account.limit_changedMeta changed the account limit.Adjust the sending pace to the new ceiling.
number.quality_changedThe number’s quality changed.Reduce what causes complaints.
account.alertMeta sent an alert about the account (account_alerts).Read the alert_type and the description, and tell the customer.
number.credential_expiringThe authorization the customer gave Luna expires within 14 days.Open a reconnection link for the number and send it to the customer.
account.updateAnother account notice Luna does not translate.Read the raw event and decide, or ignore it.

Where to read the state, without a webhook#

Meta offers no lookup for this state. Luna keeps the last notice it received and returns it in two places. In GET /v1/business-accounts, each account carries status, with restricted, restrictions, disabled, violationType and reportedAt. In GET /v1/numbers and GET /v1/numbers/{id}, each number carries waba, with id, restricted and disabled, ready for a screen to show without calculating anything. Both places also carry the validity of the customer’s authorization (credentialExpiresAt and credentialNeverExpires) and the payment method at Meta (paymentMethodOnMeta and currency), described in the sections below.

A restricted account, in 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"
}

Restricted account: `account.restricted`#

What it means. Meta imposed a restriction on the account. What it blocks depends on the type, in restrictions[].restriction_type (for example, adding numbers or starting conversations). expiration carries the deadline as Meta reported it and remediation carries its guidance, when there is any.

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
      }
    ]
  }
}
  • Cause. It usually comes from complaints, contacts blocking the number, or use outside Meta’s policy. A restriction for abusing utility templates, for example, follows a ladder of Meta warnings before it gets here.
  • Fix. Read the type and the deadline, and tell your customer. The account owner handles the cause, in Meta’s WhatsApp Manager, by the route Meta itself indicates in the notice. While it lasts, do not insist on what the restriction blocks.
  • How to know it ended. Meta does not announce the end of a timed restriction. Check expiration, or read status.restricted in GET /v1/business-accounts, which stops holding when the deadline passes.

Policy violation: `account.violation`#

What it means. Meta recorded a policy violation on the account, with the type in violation_type. It is a warning: the account can be restricted or deactivated if the violation is not handled.

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"
  }
}
  • Cause. Content or behavior that Meta’s policy does not allow, indicated by the type.
  • Fix. Find which content or flow caused the violation, fix it and tell the account owner. A violation does not expire on its own: status.violationType keeps the last type announced.

Deactivated and reinstated account: `account.disabled` and `account.reinstated`#

What it means. account.disabled says Meta deactivated the account: sends stop being accepted. account.reinstated says it came back. Meta also announces a scheduled deactivation, and that notice arrives as account.update with event equal to DISABLED_UPDATE, because the account is not deactivated yet.

DeactivatedJSON
{
  "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"
  }
}
ReinstatedJSON
{
  "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
  }
}
  • Cause. A serious or repeated violation of Meta’s policy, or a restriction that was not resolved.
  • Fix. The account owner asks Meta for a review. Luna does not reinstate accounts and cannot ask for it on their behalf. While it is deactivated, stop sending: every attempt only fails.
  • How to know it is back. By account.reinstated, or by status.disabled equal to false in GET /v1/business-accounts.

Disconnected number: `number.disconnected`#

What it means. The number is no longer connected to Luna. It is the pair of number.connected. The reason field says which Meta notice caused the disconnection: PARTNER_APP_UNINSTALLED (the customer removed the app), PARTNER_REMOVED (Luna was removed as the account’s partner) or ACCOUNT_OFFBOARDED (the account’s link to Luna was ended). disconnection_reason and initiated_by carry what Meta reported, when it reports.

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
  }
}
  • Cause. Almost always, the customer removed the app in their own Business Manager.
  • What state the number ends up in. It depends on the cause, and the event name is not the state name. When the customer removes the app (PARTNER_APP_UNINSTALLED), their authorization stops being valid: the number gets connection.status: "action_required", canSend: false and the reason credential_invalid in connection.reasons, and reconnection is through the link (POST /v1/onboarding/links with numberId). When you disconnect with DELETE /v1/numbers/{id} (reason: "requested_by_tenant"), the number gets connection.status: "disconnected", canSend: false and empty reasons. For PARTNER_REMOVED and ACCOUNT_OFFBOARDED the event is delivered, but today only the uninstall changes the number’s state by itself: check connection before concluding it stopped. So decide by the event’s reason, or read connection in GET /v1/numbers/{id}, and do not always expect disconnected.
  • Fix. Sends from this number no longer work. To come back, your customer has to connect again: open a new connect link (see Connect a number) and ask them to finish it. The message history stays in GET /v1/messages.

Account limit: `account.limit_changed`#

What it means. Meta changed the account limit. daily_conversation_limit is Meta’s messaging limit, in its tier names: TIER_250, TIER_2K, TIER_10K, TIER_100K or TIER_UNLIMITED (250, 2,000, 10,000 and 100,000 people per 24-hour period, or no ceiling). It counts unique people the business writes to outside the customer service window, not messages, and it belongs to the business portfolio, shared by all its numbers. And max_phone_numbers_per_waba is the account’s number ceiling. One of the two is null when the notice changed only the other. It is the ceiling Meta granted, never how much was used. The limit belongs to the business portfolio, so it holds for all numbers of the account.

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
  }
}
  • Cause. Meta raises the limit when quality is good and volume calls for it, and lowers it when quality drops.
  • Fix. Adjust the sending pace to the new ceiling. Each number’s current value is in limiteDiarioDeConversas, in GET /v1/numbers.

Number quality: `number.quality_changed`#

What it means. The number’s quality rating changed, from previous_quality_rating to quality_rating (GREEN, YELLOW, RED). Meta has no webhook for this: Luna checks each number’s quality periodically, and the event is sent when the check sees the change. It arrives with a delay of up to about an hour.

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"
  }
}
  • Cause. Contacts block or report the number, or complain about the messages.
  • Fix. Reduce what causes complaints: messages the contact did not ask for, high frequency, unexpected content. Low quality leads to a lower limit and, later, to a restriction. The history is in GET /v1/numbers/{id}/health.

Authorization about to expire: `number.credential_expiring`#

What it means. The authorization your customer gave Luna to operate the number expires within 14 days (credential_expires_at). That authorization can have an expiry (the current connection setup issues it with a 60-day validity); when it expires, Meta refuses Luna’s calls on that account and the number stops sending and receiving. This is the one notice in the family that comes before the problem. Luna reads the validity at connection time and checks it every hour, and the notice is sent once per expiry and per number of the account: renewing the authorization changes the expiry and allows a new notice. An authorization issued without an expiry never produces the event.

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"
  }
}
  • Cause. The authorization’s own expiry. Nothing went wrong on your customer’s side.
  • Fix. Create a reconnection link with POST /v1/onboarding/links passing numberId, and send it to your customer. The page opens that number’s renewal directly, does not count a new number and keeps your externalId. The same applies if credentialStatus is already reauth_required. Whether renewal is allowed is the API’s call: the podeReconectar field of GET /v1/numbers/{id} becomes true 14 days before the expiry.
  • Where to read it without a webhook. credentialExpiresAt (the date) and credentialNeverExpires (true when Meta reported it does not expire, null until Luna has read it) in GET /v1/business-accounts and in each number’s waba object.

Meta alert: `account.alert`#

What it means. Meta sent an alert about the account (the account_alerts field), for example a denied limit increase (INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED, INCREASED_CAPABILITIES_ELIGIBILITY_FAILED or INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO) or a lost profile picture (PROFILE_PICTURE_LOST). The fields arrive as Meta sent them, untranslated and with no closed list of values: entity_type, entity_id, alert_severity, alert_status, alert_type and alert_description. What Luna does not name yet goes in details. Like the other account notices, one event goes out per connected number, all with the same 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": {}
  }
}
  • Cause. It depends on the alert_type. The text in alert_description is Meta’s.
  • Fix. Show the alert to the account owner and let them handle it in Meta’s WhatsApp Manager. Treat new alert_type values as information, not as an error: Meta adds types without notice.

Other notices: `account.update`#

Every Meta account notice that has no type of its own arrives as account.update, with Meta’s raw event field and the rest in details: ACCOUNT_DELETED, ACCOUNT_RECONNECTED, VOLUME_BASED_PRICING_TIER_UPDATE, the scheduled deactivation and whatever Meta adds. Luna does not invent a meaning for them. If your system does not use them, ignore them.

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

What Luna does not do#

  • It does not lift a restriction, reinstate an account or ask Meta for a review. That belongs to the account owner.
  • It does not look the state up at Meta: Meta offers no such lookup. The state Luna returns is the one from the last notice it received.
  • It does not block your sending because of a restriction. Meta is what refuses, and the refusal arrives as an error on the message.
  • It charges nothing for these notices. A missing payment method at Meta has its own guide: Payment at Meta.

The events have their full format in Receive events, and the fields are in the API reference. Template category and quality changes are in Templates.

Route details for this guide#

The API reference says how to call each route, in a few lines. What explains the reason for each decision, the edge cases and the warnings is here, in the order of the reference.

GET /v1/numbers/{id}/health#

limiteDiarioDeConversas is Meta's MESSAGING LIMIT, set for the business portfolio and not for each number: it counts unique people the business writes to outside the customer service window, in the tiers TIER_250, TIER_2K, TIER_10K, TIER_100K and TIER_UNLIMITED. throughputLevel is SPEED, how many messages per second Meta processes. Each transition carries the value in force at that point, and that is how you find out when the limit went up or down. Neither one counts what has already been used.

And there is a ceiling that goes up and a ceiling that does not. throughputLevel describes a progression Meta raises on its own as the number builds quality. A number connected through coexistence, which keeps working in the business phone app, has a FIXED ceiling and never enters that progression. What separates the two cases is tetoDeVazaoPorSegundo, right beside it: with a value, it gives the fixed ceiling in messages per second; null, the progression applies to this number. The value comes from what the platform observed in the traffic, and not from the label Meta returned.

sincronizacaoDoHistorico tracks the import of the phone previous conversations on a number connected through coexistence, and there are FOUR situations, not three. Null means there is no import for this number. em_curso means it is running, and sincronizacaoPrazo tells you until when: past that instant without finishing, Meta disconnects the end business. concluida means it finished, and the older conversations already show up in GET /v1/messages. recusada means the business owner declined to share on the phone, so it will not finish and asking again changes nothing.

Do not read the percentage on its own. sincronizacaoProgresso is a label Meta assigns, and one hundred per cent does NOT mean success: a refusal arrives carrying whatever progress had already been recorded. What tells you the outcome is sincronizacaoDoHistorico, and nothing else. And absence is not zero progress: null means there is no import, zero means one started and has not moved yet.

The transitions list carries one entry per CHANGE, not one per check. A number whose rating has never changed since it was connected returns an empty list, and that means it has been stable: do not read an empty list as missing data.

What separates the two cases is checkedAt. With a timestamp, the platform asked Meta and found no change. Null, the check has not happened for this number yet.

Transitions come newest first.