Skip to main content

Meta WhatsApp Account Health

The Meta health page in the admin shows the current status of every WhatsApp channel you have connected. The platform polls Meta on a schedule, records each snapshot, and alerts you the moment a snapshot worsens — so you find out about a quality-rating drop within minutes.

When to use it​

  • You ran a campaign and want to confirm your account didn't take a quality hit.
  • You see members reporting they're not getting messages and want to triage from one screen.
  • You're about to launch a big broadcast and want to verify you're in the right messaging-limit tier first.

How it works​

A background worker (MetaAccountHealthWorker) sweeps every active WhatsApp channel across all tenants and fetches Meta's per-phone health for each. A new MetaAccountHealth row is written each sweep, with these fields:

  • Quality rating — Green, Yellow, Red.
  • Messaging-limit tier — 250 / 1k / 10k / 100k / unlimited contacts per 24 hours.
  • Phone status — Connected, Disconnected.
  • Name status — Approved, Pending, Rejected, Flagged.
  • Account-review status — Approved, Pending, Restricted.

Snapshots are graded into a numeric severity:

SeverityConditions
0 — HealthyGreen quality, all statuses normal.
1 — WarningYellow quality, Pending review, or similar mild signals.
2 — DegradedRed quality, Flagged name, Disconnected phone, Rejected name.
3 — RestrictedAccount restricted (no further sending allowed).

When a snapshot's severity is worse than the previous one for the same channel, a [META-HEALTH-DEGRADED] notification is sent to the platform's ops channel. That's your "act now" signal.

The admin page​

Go to Communications → Meta health. The page shows a table of channels with the current snapshot for each. Click a channel for the history view — the last N snapshots over time, colour-coded by severity.

Each row has a Refresh now button (Pages.Communications.MetaHealth.Refresh permission) that triggers a single-channel probe immediately, so you don't have to wait for the next scheduled sweep.

The public endpoint​

For external monitoring or demos, a coarse-grained summary is available at:

GET /api/public/meta-health

No authentication. Returns the current per-channel severity (no PII, no Meta tokens). Useful for status pages or uptime monitors.

Step-by-step​

Investigate a degraded channel​

  1. Open Communications → Meta health.
  2. Find the channel showing yellow or red.
  3. Click for history. Look for the snapshot that triggered the change — what did Meta say (quality drop? template flagged? account review?).
  4. Cross-reference with your Broadcasts log — what campaign was running at that time?
  5. Pause the offending campaign or template until you understand the cause.
  6. Click Refresh now after the next 30 minutes to see if Meta has updated their snapshot.

Set up external alerting​

The platform already emits [META-HEALTH-DEGRADED] via the configured ops notifier (typically ntfy). For external alerting (PagerDuty, Slack), point your monitor at /api/public/meta-health and alert on severity ≥ 2.

Limits and gotchas​

  • Meta's status lags. Meta sometimes takes hours to reflect a degraded snapshot through their API. The platform records what Meta reports — you may see the symptom (delivery failures) before the health page shows the issue.
  • Restricted is terminal. Once you're severity 3, only Meta can lift the restriction. The platform stops sending but Meta itself decides when you can resume.
  • The worker writes a sentinel row under tenant 1 / __worker__ when the host tick loop wedges, so you can tell "no fresh data" from "no degradation".
  • Permission: Pages.Communications.MetaHealth (view) and Pages.Communications.MetaHealth.Refresh (manual probe).