What is WhatsApp API quality rating?
WhatsApp API quality rating is Meta's 7-day score of how people receive your Cloud API messages. Green keeps your messaging tier growing; Yellow and Red freeze scaling and can pause templates. This is the operational playbook we use on Ominiflow onboarding. WhatsApp API quality rating is Meta's 7-day, recency-weighted score of how recipients receive Cloud API messages from your business number. It is driven mainly by blocks, reports, mutes, archives, and block reasons. Public values are Green, Yellow, Red, and NA.
Last updated: 21 August 2026
WhatsApp API quality rating is the score Meta assigns your Cloud API phone number based on how recipients treated your messages over the last seven days. It is not a vanity badge. Green keeps your messaging limit eligible to grow. Yellow or Red freezes scaling, can pause templates, and is the usual reason a Diwali or sale-week broadcast dies mid-campaign.
This is not another “what is WhatsApp API” explainer. We already cover setup, pricing, and volume sends elsewhere. This guide is the operational layer: how the rating is calculated, how it differs from template quality, how it gates 2026 messaging limits, and the 14-day recovery sequence we run with Ominiflow customers when a number turns Yellow.
Too long? Read this first
- WhatsApp API quality rating = 7-day, recency-weighted mix of blocks, reports, mutes, archives, and the reasons people give when they block you
- Public values: GREEN (high), YELLOW (medium), RED (low), NA (not enough data yet)
- Number quality and template quality are separate scores — a single bad marketing template can go Red while the number stays Green
- In 2026, messaging limits sit on the business portfolio (250 → 2,000 → 10,000 → 100,000 → Unlimited). A poor rating blocks the next upgrade
- Meta does not publish a magic block-rate percentage. If Yellow appears, treat it as an incident — not a dashboard curiosity
- Recovery: stop marketing, keep high-value utility to opted-in engaged users, staff replies, wait a full 7-day window, then resume at 20–30% of previous promo volume
What is WhatsApp API quality rating?
WhatsApp API quality rating is Meta's rolling assessment of how WhatsApp users receive messages from your business phone number on Cloud API. It is visible in WhatsApp Manager under Account tools → Phone numbers, and via the Phone Number API as quality_rating.
Meta's own description: quality is based on how messages have been received over the past seven days and is weighted by recency. The mix is almost entirely negative feedback — blocks, reports, mutes, archives, and the reason a user picks when they block the business — not likes or star ratings.
A new number often shows NA until Meta has enough traffic. High-volume numbers can change colour in minutes during a blast. That is expected, not a bug.
If you are still choosing the platform itself, start with the WhatsApp Business API complete guide and the plain-language definition. Come back here before you scale broadcasts.
Number quality vs template quality
Teams mix these up and then “fix the wrong thing.” There are two scores:
| Score | Applies to | API field | If it goes Red |
|---|---|---|---|
| Number quality | The Cloud API phone number | quality_rating | Tier upgrades freeze; sending can be restricted |
| Template quality | Each approved template | quality_score.score | That template can be paused or disabled; others may still send |
Template ratings from Meta's Template API:
- GREEN — little negative feedback; send normally
- YELLOW — negative feedback or low read rates; still sendable, at risk of pause
- RED — significant negative feedback or low reads; still sendable but likely to be paused soon
- UNKNOWN — new template, not enough data yet
Onboarding pattern we see every week: a Diwali “FLAT 50%” marketing template goes Yellow after a 40,000-contact blast, while utility order-shipped templates stay Green. Pause the promo template. Do not shut the whole WABA unless the number is also Yellow/Red.
Template rules: template message API guide.
What actually moves the score
Meta does not publish a block-rate threshold. Anyone selling you “keep blocks under 2%” is guessing. What is documented:
- Lookback is seven days, newer messages weigh more
- Signals include blocks, reports, mutes, archives, and block reasons
- Read-rate weakness shows up more clearly on templates than as a published number-level formula
- High-traffic numbers can flip colour inside a single campaign window
From Ominiflow onboarding (Indian D2C, education, and BFSI numbers we watch in WhatsApp Manager after go-live), the drops that actually happen are almost never “the API is broken.” They are:
| What the team did | What users did | What the dashboard shows 6–48h later |
|---|---|---|
| Imported a CRM list with no WhatsApp opt-in | Block / Report as spam | Number Yellow, marketing templates at risk |
| Festival blast to all 80k contacts, including 2019 one-time buyers | Mute, archive, block | Template Red; number may still be Green if utility volume is high |
| Broadcast with no agent coverage after 8pm | Reply, get silence, then block | Quality dip plus wasted Meta conversation fees |
| Marketing copy inside a Utility template | Category mismatch + complaints | Template rejection or later quality hit |
| Purchased “WhatsApp database” | Mass reports | Restriction or ban — see ban guide |
How quality rating gates messaging limits in 2026
Quality rating is the gate on how many unique people you can start a template conversation with in a rolling 24 hours. Session replies inside the 24-hour customer window do not consume that cap.
Meta's documented ladder for a business portfolio (limits are shared across numbers in the same portfolio — adding a second number does not double the cap):
| Portfolio limit | How you get there |
|---|---|
| 250 | Default for a new, unverified business portfolio |
| 2,000 | Complete a scaling path: verify the business, have a partner verify it, or deliver 2,000 template messages to unique users outside the service window in a 30-day window at healthy quality — walkthrough: scale your WhatsApp Business Account |
| 10,000 | Automatic, once you use a large share of the current cap over ~7 days with high-quality sending |
| 100,000 | Automatic, same quality + utilisation logic |
| Unlimited | Automatic at the top of the ladder |
Meta evaluates upgrades on a short cycle (on the order of hours, not weeks). A Yellow or Red rating is why a brand “does everything right on volume” and still sits at 2,000. Volume without quality does not unlock 10,000.
Need the send-by-volume workflow rather than the score itself? Use how to send 500–100,000 WhatsApp messages and safe bulk messaging.
How to keep a Green WhatsApp API quality rating
This is the checklist we walk in week one of Ominiflow onboarding — before the first marketing campaign, not after the first Yellow.
- Documented opt-in only. Checkout checkbox, lead form with WhatsApp consent text, QR, or Click-to-WhatsApp ads. Store source + timestamp. Email subscribers are not WhatsApp subscribers.
- Segment, then send. Last-90-day buyers outperform “entire CRM.” Festival lists should exclude people who never opened or replied in 90 days.
- Match template category to copy. Order shipped = Utility. Discount = Marketing. Auth code = Authentication. Mixing promo into Utility is how templates get rejected and later reported.
- Staff the replies. A broadcast without inbox coverage is a quality incident waiting to happen. Route to a shared inbox or a bot with a human handoff. See shared inbox.
- Ramp volume. New number: utility to engaged customers first, then a 500-contact marketing test, then 2,000, then the festival list. Do not debut the number on 50,000 cold contacts.
- Cap frequency. Two marketing conversations a week to the same person is already aggressive. Three “last chance” templates in 48 hours is how mutes happen.
- Scrub dead numbers. Landlines and people who left WhatsApp create “sent, never delivered” noise and wasted spend. Validate E.164 before import.
- Watch both scores. Number Green + template Yellow means pause that template, not the whole API.
Common implementation failures: five WhatsApp API mistakes.
14-day recovery playbook (Yellow or Red)
When WhatsApp Manager shows Yellow or Red, treat it like a production incident. Do not “send a nicer blast tomorrow.”
Day 0 (same day)
- Pause all Marketing templates. Leave Utility and Authentication running if they are still Green.
- Identify the last campaign: list source, template name, send time, reply SLA.
- Export suppressions: anyone who replied STOP, blocked, or never delivered.
- Put agents on the inbox. Unanswered campaign replies are still arriving.
Days 1–7
- Send only high-value Utility to people who already messaged you or have a live order/appointment.
- Do not import new cold lists.
- Rewrite the offending template: shorter, specific, no fake urgency, correct category. Submit a new template rather than hammering a Red one.
- Let a full 7-day window roll off. Recency weighting means yesterday's blast still dominates today's colour.
Days 8–14
- If the number is back to Green, run a 500–1,000 marketing test to the highest-intent segment (clicked last campaign, purchased last 30 days).
- If still Yellow, stay on utility another week. Do not “test” with 20,000 names.
- If Red persists or sending is restricted, open a case in Meta Business Support and review the ban/restriction path in our WhatsApp ban guide.
Honest limit: we cannot force Meta to flip a colour. We can stop the behaviour that caused it and wait for the 7-day window to reweight. Brands that keep blasting through Yellow usually meet a restriction, not a miracle recovery.
How to check WhatsApp API quality rating
In WhatsApp Manager: Account tools → Phone numbers. Colour and status sit next to the number. Template quality is on Manage templates for each approved template.
Via Cloud API (replace the phone-number ID and token):
curl -X GET "https://graph.facebook.com/v21.0/PHONE_NUMBER_ID?fields=quality_rating,display_phone_number,verified_name" \
-H "Authorization: Bearer ACCESS_TOKEN"Typical values: GREEN, YELLOW, RED, or NA.
For a template:
curl -X GET "https://graph.facebook.com/v21.0/TEMPLATE_ID?fields=quality_score,name,status" \
-H "Authorization: Bearer ACCESS_TOKEN"On Ominiflow, campaign delivery/read/reply sit next to the send so you see a quality problem before WhatsApp Manager turns Yellow. Pair that with webhook status events from the webhook integration guide if you run a custom backend.
India sale-week and festival playbook
This is the week Indian D2C numbers go Yellow. The pattern is the same every year: one marketing template, the full list, Sunday 11am, inbox unmanned.
- Two lists: “bought or chatted in 90 days” vs “the rest.” Send the promo to the first. Do not “also include the rest to be safe.”
- Utility first that morning: COD confirmations and dispatch updates keep the number doing useful work while marketing is live.
- Reply SLA: bot greets in 30 seconds; human within 15 minutes during sale hours. Ignored “is this COD?” replies are quality poison.
- One promo conversation per person that day. Follow-ups belong inside the 24-hour window as session messages, not a second marketing template.
- Stop at the first quality warning. Finishing the remaining 30,000 contacts after Yellow appears is how Red happens before lunch.
COD and RTO context: WhatsApp COD confirmation India. D2C setup: WhatsApp API for D2C brands.
FAQ
What is WhatsApp API quality rating? expand_more
It is Meta's 7-day, recency-weighted score of how WhatsApp users receive Cloud API messages from your business number — mainly blocks, reports, mutes, archives, and block reasons. Values are Green, Yellow, Red, or NA.
Does a Yellow rating mean I am banned? expand_more
No. Yellow means medium quality: you can usually still send, but template pauses and frozen tier upgrades are in play. Stop marketing, keep useful utility, and wait for the 7-day window to reweight. A ban or restriction is a different, more severe state.
Can I pay Meta to raise my quality rating? expand_more
No. There is no paid boost. The score follows recipient behaviour. Spending more on a larger cold list makes it worse.
Why is my template Red but my number still Green? expand_more
They are independent scores. Pause or replace the Red template. Keep sending Green utility templates. That split is common after one aggressive promo.
How long does recovery take? expand_more
Plan on one full 7-day lookback after you stop the offending traffic, often 8–14 days before it is safe to resume modest marketing. Recency weighting means a huge blast yesterday still dominates today's colour.
Do session replies hurt quality rating? expand_more
Useful replies inside the 24-hour window are not the usual problem. The usual problem is business-initiated templates to people who did not opt in, plus silence when they answer. Staff the inbox.
Does adding another WhatsApp number fix a Red rating? expand_more
Not as a loophole. In 2026 messaging limits are portfolio-level. A second number still shares the cap, and opening numbers to dodge quality is a policy risk. Fix the list and the copy.
Keep your Cloud API number Green on Ominiflow
Ominiflow is a WhatsApp Cloud API platform: shared inbox so campaign replies get answered, broadcast tooling with segments instead of “all contacts,” template management, and Meta conversation fees at cost. We watch quality with you during onboarding — especially before the first festival send.
Book a quality-rating review →
Related: WhatsApp API India · onboarding checklist · safe bulk messaging · pricing · start free setup
Published 21 August 2026. Quality-rating and messaging-limit rules summarised from Meta WhatsApp Business Platform developer docs (messaging limits, template quality, phone number quality). Meta can change thresholds without a blog post — verify in WhatsApp Manager before a large send. This is operational guidance, not a guarantee of delivery or tier upgrades.
