The phone_number_quality_update webhook
phone_number_quality_update reports throughput and messaging limit changes for a number. As of 2026 it does not carry the green, yellow or red quality rating despite its name, which has to be polled from the phone number instead.
- Carries throughput and tier
- Not the colour rating, despite the name
- The rating needs polling
Nothing charged for 7 days. Cancel anytime.
The year this field's contents changed away from the colour rating.
Quality ratings a number can hold: green, yellow and red, none of which arrive here.
The error a number returns once quality limiting takes effect.
What does this webhook actually contain?
Throughput and messaging limit information, delivered as an event value plus fields carrying the current limit.
The practical content is that a number's capacity changed: it moved to a different messaging tier, or its throughput level was adjusted. Those are useful to record because they change what an integration can do, and because a tier moving downward is an early signal.
What is not in it, despite the field name, is the quality rating. A handler written against older documentation will look for GREEN, YELLOW or RED here and find nothing, then conclude that quality never changes.
Where does the colour rating come from then?
From reading the phone number directly, on a schedule.
The quality_rating field lives on the phone number object in the Graph API, and it has to be polled rather than waited for. This is why monitoring a connection properly needs a poller as well as a webhook receiver: the two carry different things and neither is sufficient alone.
It is also why a quality drop is invisible to most integrations. Nothing pushes it, the WhatsApp Business app shows no sign of it, and by the time it produces error 131048 the affected sends have already failed.
Common mistakes
- Looking for GREEN, YELLOW or RED in this payload. As of 2026 it is not there.
- Building monitoring from webhooks alone. The quality rating has to be polled.
- Ignoring a downward tier change. It is usually the first visible sign of a problem.
EasyCoexistence polls quality rating, messaging tier and throughput level on every connected number and records each check, so a decline is visible before it costs a send.
Frequently asked questions
Why is the field named after quality then?
It predates the change. The name stayed while the contents moved, which is why this catches people out.
How often should the rating be polled?
Often enough to catch a slide before it becomes a limit. We poll on a schedule rather than on demand.
Does the app show the rating?
No. Nothing about it is visible in the WhatsApp Business app on the phone.
Is 131048 related?
Yes. That is the error a number starts returning once a low rating results in limiting.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialNothing charged for 7 days. Cancel anytime.Verified on