Chapter 1 · The scenario
Example: One creative, two audiences
A Kochi travel agency writes a monsoon-getaway marketing template and sends it to 4,000 customers who booked in the past year: reads are high, a handful block it, and the rating settles at high. Encouraged, the team sends the same template to 25,000 contacts collected at a travel fair without WhatsApp opt-in. Within hours the rating drops to medium, then low, and the template is paused for 3 hours. The copy was never the problem — the audience was — so the agency goes back to opted-in past customers and adds a clear opt-out line.
Chapter 2 · What is a template quality rating?
A template quality rating is Meta's judgement of how WhatsApp users are responding to one specific message template. It is worked out per template — per name and language — from negative feedback such as blocks and reports and from engagement such as read rates, and it moves as new feedback arrives. WhatsApp Manager shows it with the status as Active – Quality pending, Active – High quality, Medium quality or Low quality; the API returns it as quality_score.score: UNKNOWN, GREEN, YELLOW or RED.
The rating has consequences. A new template starts as quality pending and may be paced while Meta collects feedback. Medium means negative feedback from multiple customers or low read rates; low means the same at a level that endangers the template, and a template that reaches low is paused automatically — 3 hours the first time, 6 hours the second, disabled the third. Every change fires a message_template_quality_update webhook with previous_quality_score and new_quality_score.
It is not the phone number's quality rating. The number's rating, also shown as green, yellow or red, summarises recent feedback on everything the number sends and gates messaging-limit upgrades; a template rating covers one template and drives pacing and pausing. One weak template can sit at low while the number stays green — but a run of low-quality templates can eventually pull the number down.
Key takeaways
- A template quality rating is Meta's per-template judgement of how recipients respond: high, medium, low or pending.
- The API returns it as
quality_score:GREEN,YELLOW,RED, orUNKNOWNwhile feedback is still pending. - Negative feedback from multiple users and low read rates push it down, and a template that reaches low is paused.
- It is separate from the phone number's quality rating, which covers everything the number sends and gates messaging limits.
Chapter 3 · How it unfolds
How does a template quality rating work?
It starts unrated
A newly approved template has no feedback yet: Active – Quality pending,
UNKNOWNin the API. Early large sends on it may be paced.Recipients react
Blocks, reports (with the reason a user picks when blocking), reads and ignored messages all feed the rating. Unexpected, too frequent or irrelevant messages produce the negative signals.
Meta updates the rating
The rating moves between
GREEN,YELLOWandREDas feedback builds up, and amessage_template_quality_updatewebhook reports each move.Low triggers a pause
At
REDthe template is paused automatically and its sends fail until it is Active again; then the rating is recalculated from recent feedback.The trend reaches the number
Repeated low-quality templates can eventually lower the phone number's own rating, which in turn holds back messaging-limit upgrades.
Chapter 4 · Why it matters
Why does a template quality rating matter?
For a marketer, the template rating is the earliest honest signal of whether a message is welcome. It reacts within a campaign, per creative, before any number-level problem shows, and it decides whether the next send goes out at full reach, is held by pacing or is paused halfway. Watching it lets a team retire a weak creative while it is merely medium, instead of learning about it from a pause or a stalled messaging limit.
Chapter 5 · In code
A template quality rating in code
{"object": "whatsapp_business_account","entry": [{"id": "{WABA_ID}","time": 1760860000,"changes": [{"field": "message_template_quality_update","value": {"previous_quality_score": "GREEN","new_quality_score": "YELLOW","message_template_id": 806312974732579,"message_template_name": "monsoon_getaway","message_template_language": "en"}}]}]}
A move from GREEN to YELLOW: the cheapest moment to narrow the audience.
Chapter 6 · The facts
A template quality rating: key facts and limits
| Scope | One template (name + language) |
|---|---|
| API values | GREEN · YELLOW · RED · UNKNOWN |
| Manager labels | High · Medium · Low · Quality pending |
| Inputs | Blocks, reports, read rates |
| At low (RED) | Paused 3 h, then 6 h, then disabled |
| Webhook | message_template_quality_update |
| Not the same as | The phone number's quality rating |
Chapter 7 · Where it goes wrong
Common mistakes with a template quality rating
Watching only the number's rating
The number can stay green while one template slides to low. Track ratings per template, or you will meet the problem as a pause.
Rewriting copy when the audience is the problem
Blocks mostly come from people who did not expect the message. Before rewriting, check who received it: opt-in source, last interaction and how often you message them.
A big first send on a pending template
With no rating yet, a large first send risks pacing and, if it goes badly, an early pause. Warm new templates on engaged segments first.
Cloning a low-rated template
The same content under a new name meets the same reaction. Change the offer, the targeting or the frequency, not just the template name.
Chapter 8 · What good teams do
Best practices for a template quality rating
- Alert on any
GREENtoYELLOWmove; medium is the cheapest moment to act. - Compare ratings across creatives in the same campaign to learn which messages customers welcome.
- Cap how often each customer hears from you so no single template becomes the one that gets blocked.
- Make opting out easy: a customer who can stop messages is less likely to block and report.
Chapter 9 · Template Quality Rating FAQs