Skip to main content

​
Troubleshooting: WhatsApp campaign auto-paused on a RED quality rating

A WhatsApp campaign goes to paused the moment you launch it, and the campaign record says why: failure_code: WHATSAPP_QUALITY_RED. That is Orbit’s pre-send quality gate, not a bug in the launch — the launch refused to queue sends because Meta’s quality rating on your WhatsApp Business phone number is RED, and raising the rating is a Meta-side fix, not an Orbit-side one. This page reads the pause, checks the rating, and walks the recovery.
The quality rating is Meta’s signal, computed from how your recipients react to your numbers — blocks, reports, and negative feedback weigh against you. Orbit reads the rating Meta reports and enforces a hold while it is RED; nothing in this page changes the rating itself. Recovery happens in Meta Business Manager.

​
Symptoms

The pause has a specific signature — check the campaign before treating it like a routine operator pause:
  • The campaign goes to paused immediately on launch instead of sending. The launch request returns a 503 with code: "CHANNEL_UNAVAILABLE" and message "WhatsApp quality rating is RED — messaging paused by Meta".
  • The campaign’s metadata carries the full auto-pause stamp: auto_paused_reason: "whatsapp_quality_red", failure_code: "WHATSAPP_QUALITY_RED", a human-readable failure_reason, and a failure_at timestamp.
  • A campaign.paused webhook fires with reason: "whatsapp_quality_red" in the payload. The envelope is deliberately identical to an operator pause — automation that listens for campaign pauses sees every pause class — so the deciding field is the webhook payload reason (or metadata.failure_code on the campaign record), not the event type.
  • The dashboard banner on the campaign-detail page tells you Meta paused messaging rather than a teammate clicking Pause.
If metadata.failure_code is a different value — a credit cap, a circuit-break, or anything else — you are on the wrong page. If the field is absent entirely, someone paused the campaign by hand; check with your team before you chase a Meta quality issue.

​
What the quality rating is

Meta assigns every phone number on your WhatsApp Business account one of three ratings, reported on the phone-number record in Meta Business Manager and synced to Orbit through Meta’s quality webhooks and the scheduled WABA health reconcile:
  • GREEN — normal. Campaign and one-off sends proceed.
  • YELLOW — degraded recipient feedback. Orbit still sends, but the launch log notes the reduced rate, and Meta may throttle the number’s throughput. Treat it as an early warning.
  • RED — recipients are blocking or reporting this number heavily. Meta itself pauses messaging, and Orbit refuses to queue new campaign sends until the rating recovers.
The thresholds and the feedback signals Meta weighs are Meta’s own — see Meta’s quality rating documentation. The rating moves as Meta re-scores your recent recipient feedback; a recovered rating flows back to Orbit on the next webhook or scheduled reconcile, and the gate lifts.

​
Inspect the rating

Read the per-channel quality posture from the unified Brand Identity endpoint — the same read-only rollup that backs the dashboard’s trust score:
The channels array carries a per-channel entry; on WhatsApp that is the whatsapp_business entry with Meta’s live posture for your sender (reads are fail-soft — one unreachable source degrades its own channel entry, never the whole response). The dashboard renders the same read under Settings → Brand Identity. Cross-check in Meta Business Manager (WhatsApp Manager → your phone number) if the API read and the banner disagree — Meta is the source of truth, and the rating in Orbit’s store refreshes on webhook or reconcile cycles.
The quality rating attaches to the phone number on your WABA, not to a single template. Every WhatsApp campaign routed through that number hits the same gate, so auto-paused campaigns queue up in parallel — they are all symptoms of the same number-level rating. (The per-template paused status in Meta’s template list is a separate signal; both tell you recipients are rejecting the content.)

​
Recovery

The only way out is through Meta — work this in order:
  1. Fix what recipients are reacting to. In Meta Business Manager, open the phone number’s Insights and find which templates earn blocks and reports. Rework them so the first line states why the recipient is getting the message, and remove anything promotional from utility and authentication templates. The template troubleshooting page walks the content rules; the content policy lists what Meta rejects.
  2. Wait for the rating to recover. Meta re-scores on a rolling window of recent feedback, so the rating climbs back to YELLOW or GREEN as recipients of later traffic stop blocking and reporting. The recovery lands in Orbit on Meta’s quality webhook or the scheduled health reconcile — no Orbit action is required to notice it.
  3. Resume the campaign once the rating is YELLOW or GREEN. Re-launch the paused campaign (it is still full of the same recipients), and sends already stamped with counters continue from where the counter record left off.
If the rating stays RED across a full feedback window even after the content fix, treat it as a Meta-side dispute: appeal through Meta Business Support with the recipient-feedback evidence. The escalation payload on the template page is a good one-message packet for that appeal too.

​
What not to do

  • Do not resume the campaign while the rating is still RED. The quality gate re-runs at launch and auto-pauses it again — the same WHATSAPP_QUALITY_RED stamp, and every launch attempt is counted against nothing. Fix the content, wait for YELLOW or GREEN, then resume.
  • Do not disconnect and re-connect the WABA. The quality rating follows the phone number at Meta, not the connection state in Orbit. Re-onboarding reads the same RED rating, and the next launch auto-pauses again.
  • Do not route the campaign through a different phone number on the same WABA expecting a cache. The rating is per phone number, but recipient feedback for a shared number family weighs on one another — and splitting recipients across numbers to dodge the gate is exactly the pattern Meta’s enforcement catches. Fix the content.
  • Do not treat the pause as a campaign bug. The gate fires at launch because Meta already reported RED; re-creating the campaign changes nothing about that.

​
See also