Updated on October 25, 2026
The WhatsApp quality rating is a score Meta assigns to your business phone number based on how recipients reacted to your messages over the past seven days. It comes in three colors: green (high), yellow (medium) and red (low). The color alone does not stop you from sending, but it affects messaging limit increases and throughput, and a rating that stays low can lead to restrictions.
This guide explains where the score comes from, how it relates to each template’s own rating, how to check it through the API and what to do to recover a number that dropped to yellow or red.
What the phone number quality rating is
According to Meta’s send messages documentation, quality is calculated from how WhatsApp users received your messages over the past seven days, weighted by recency. The signals are user feedback:
- blocks;
- reports;
- mutes;
- archives;
- reasons users give when they block your business.
The same page warns that high-traffic numbers can see quality changes within short intervals, sometimes within minutes. A poorly targeted campaign can pull the rating down the same day.
In the API, the field is quality_rating, and the possible values are listed in the Phone Number API reference:
| Color | API value | In WhatsApp Manager | What it means |
|---|---|---|---|
| Green | GREEN | High | Little or no negative feedback |
| Yellow | YELLOW | Medium | Negative feedback is starting to add up; time to act |
| Red | RED | Low | A lot of negative feedback; risk of restriction |
| No rating | NA | Pending | Not enough data yet |
Phone number quality vs. template quality
These are two different scores, and it pays not to mix them up.
Template quality is calculated for each message template based on usage, feedback and engagement. The template quality rating page lists GREEN, YELLOW, RED and UNKNOWN (a new template with no data yet). One important detail: besides blocks and reports, low read rates also pull a template’s score down.
When a template reaches RED, Meta pauses it automatically, according to the template pausing page:
| Occurrence | What happens |
|---|---|
| 1st | Template paused for 3 hours |
| 2nd | Template paused for 6 hours |
| 3rd | Template disabled |
Attempts to send a paused template are rejected, are not charged and do not count against your messaging limit. Meta says pausing does not initially affect the phone number, but if a business keeps sending templates that reach low quality, the number may eventually be affected. In practice, the number’s rating is the accumulated result of its templates and conversations.
To understand how template category shapes the user experience, see how Meta categorizes templates.
How quality affects limits and throughput
Quality shows up in three documented places:
- Moving up to 2,000 recipients. One way out of the initial limit of 250 is sending 2,000 delivered messages outside the customer service window within 30 days using high-quality templates. After any scaling path, Meta reviews your message quality before approving the increase (messaging limits).
- Automatic scaling. Above 2,000, the limit only rises to 10,000, 100,000 and unlimited if the business is sending high-quality messages across all numbers and templates and has used at least half of its limit in the last 7 days.
- Higher throughput. To go beyond 80 messages per second, the number needs a yellow rating or better, among other requirements (throughput).
The messaging limit belongs to the business portfolio and is shared by every number in it. A low-quality number holds back growth for all of them.
Number status: connected, flagged, restricted
Besides the color, each number has a status. The business phone numbers documentation says status reflects quality and the current limit, and that only numbers with a “connected” status can send and receive through the API. Reference values include CONNECTED, FLAGGED and RESTRICTED.
Meta’s Help Center article about your phone number’s quality rating describes the flagged flow: when quality reaches low, the status changes from connected to flagged. If quality returns to medium or high by the seventh day, the number goes back to connected with no limit change; if it does not, the number goes back to connected but the limit drops one level. While flagged, the limit cannot increase.
How to check quality through the API
To see a number’s color and status:
curl "https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>?fields=quality_rating,status,whatsapp_business_manager_messaging_limit" \
-H "Authorization: Bearer <ACCESS_TOKEN>"{
"quality_rating": "GREEN",
"status": "CONNECTED",
"whatsapp_business_manager_messaging_limit": "TIER_2K",
"id": "106540352242922"
}The old messaging_limit_tier field is deprecated; use whatsapp_business_manager_messaging_limit instead.
For a template’s score:
curl "https://graph.facebook.com/v26.0/<TEMPLATE_ID>?fields=quality_score" \
-H "Authorization: Bearer <ACCESS_TOKEN>"Webhooks that help you monitor
| Webhook field | When it fires | Practical use |
|---|---|---|
message_template_quality_update | A template’s score changes | Alert when a template leaves GREEN |
message_template_status_update | Template paused, disabled or reactivated | Stop the campaign that uses it |
account_update | Policy violations and account restrictions | Notify the team and investigate |
phone_number_quality_update | The number’s throughput changes | Track capacity upgrades |
Example message_template_quality_update payload:
{
"entry": [{
"id": "102290129340398",
"time": 1674864290,
"changes": [{
"value": {
"previous_quality_score": "GREEN",
"new_quality_score": "YELLOW",
"message_template_id": 806312974732579,
"message_template_name": "welcome_template",
"message_template_language": "en-US"
},
"field": "message_template_quality_update"
}]
}],
"object": "whatsapp_business_account"
}Since the current phone_number_quality_update page only covers throughput, it is worth polling quality_rating periodically (for example, hourly during campaigns) and storing the history. That way you see the trend before it becomes a problem. For delivery tracking, see message status via webhook.
What drags quality down
Meta lists best practices on the same send messages page. Turned around, the most common mistakes are:
- messaging people who did not opt in (bought lists, old contacts collected for something else);
- generic messages with little personalization or no clear purpose;
- open-ended welcome messages like “Hi, how are you?” with no context;
- too many messages in one day;
- texts that are too long or not what the person expects;
- content that breaks the WhatsApp Business Messaging Policy.
Ignoring opt-out requests also hurts: people who cannot stop your messages tend to block and report. A healthy base starts at signup; see how to build an opt-in list.
How to recover a yellow or red number
- Stop running marketing campaigns. Expected transactional messages (order confirmations, login codes) can continue.
- Find which template pulled the score down. Check the
quality_scoreof each active template and compare it with what you sent in the last 7 days. - Review your targeting. Remove contacts with no recorded opt-in, long-inactive contacts and anyone who asked to leave.
- Rewrite the problem template. Make it clear who is writing, why the person is receiving it and how to opt out. Editing a template sends it back to review.
- Add an opt-out button to marketing templates and treat the tap as an immediate opt-out.
- Lower the frequency. Spacing out sends reduces mutes and archives.
- Watch it for 7 days. Because the score uses a seven-day window, improvement shows up gradually.
If, on top of the color, the number received a policy restriction, the path is different: Meta’s policy enforcement includes 1- or 3-day blocks on templates, 5-, 7- or 30-day blocks on all messages and, in severe cases, an account lock. The details are in Business Support Home in Meta Business Suite.
Quality rating with Vectalk
Vectalk is a proxy for the official Cloud API: the fields and webhooks are the same as Meta’s. To check the quality of the number tied to an instance token, call GET /api/phone-numbers with the fields parameter:
curl "https://apis.vectalk.com.br/api/phone-numbers?fields=id,display_phone_number,quality_rating" \
-H "Authorization: Bearer YOUR_TOKEN"GET /api/phone-numbers/list returns every number in the account with quality_rating and status. Meta’s events reach the URLs you register with POST /api/webhooks. See the Vectalk documentation for details, or sign up at apps.vectalk.com.br/register.
Frequently asked questions
Does a red number stop sending?
Not automatically. Red signals risk. What blocks sending is the number’s status (for example, restricted) or a policy restriction. Still, red is the moment to pause campaigns and investigate.
How long does it take to get back to green?
Meta calculates the score over the past seven days, weighting recent days more. Without new negative signals, it tends to improve over that window, but there is no guaranteed timeline.
Is quality tied to the number or the account?
The color belongs to the phone number. The messaging limit, however, belongs to the business portfolio and depends on quality across all numbers and templates. One bad number holds back the whole portfolio.
Is a paused template charged or counted against the limit?
No. According to Meta, attempts to send a paused template are rejected, not charged and not counted against the messaging limit.
Do delivery errors affect quality?
The score comes from user feedback (blocks, reports, mutes, archives). Failures such as error 131049 are not negative feedback, but repeatedly resending to people who do not engage tends to cause blocks later. See also the most common API errors.
Official sources consulted on October 25, 2026: Send messages and message quality, Messaging limits, Business phone numbers, Phone Number API reference, Template quality rating, Template pausing, Throughput, message_template_quality_update webhook, phone_number_quality_update webhook, Policy enforcement, About your phone number’s quality rating (Help Center), WhatsApp Business Messaging Policy.