Skip to content
InfiQ glossary · Reference sheetWebhooks & events

Phone Number Quality Webhook

The phone_number_quality_update webhook reports status changes for one business number, such as onboarding and the upgrade to 1,000 messages per second.

Properties

Term
Phone Number Quality Webhook
Abbreviation
None
Category
Webhooks & events
Level
Practitioner
Audience
Developers, Marketers
Reviewed
Also called
phone_number_quality_update · Phone number quality update · Throughput upgrade webhook

01 · Definition

What is the phone number quality webhook?

The phone number quality webhook is the phone_number_quality_update field. Despite its name, Meta's current reference describes it as the event for a change in one business phone number's throughput or limit status. It reports event: ONBOARDING while the number is still being registered, and event: THROUGHPUT_UPGRADE when the number moves from the default of up to 80 messages per second to 1,000. The value also carries display_phone_number and max_daily_conversations_per_business, the owning portfolio's messaging limit after the change.

The name comes from the years when messaging limits and quality flags belonged to each phone number. Integrations built before October 2025 also received events such as FLAGGED, UNFLAGGED, UPGRADE and DOWNGRADE, with current_limit and old_limit. When messaging limits moved to the business portfolio, Meta's notes said the Flagged state no longer occurs and scheduled current_limit and old_limit for removal in February 2026. The current reference lists only the two events above, but a careful handler still logs any other value instead of failing.

So this webhook is not the quality alarm its name suggests. A number's quality rating — GREEN, YELLOW or RED, meaning high, medium or low — is read from the phone number's quality_rating field through the API or in WhatsApp Manager. Template quality has its own template quality webhook, message_template_quality_update. The portfolio's limit is announced by the business capability update webhook, business_capability_update. Subscribe to all of these webhook fields together and treat this one as the throughput signal.

Key takeaways

  • The phone number quality webhook (phone_number_quality_update) reports status changes for one business number, not its quality rating.
  • Meta's current reference lists two events: ONBOARDING, and THROUGHPUT_UPGRADE for the move from 80 to 1,000 messages per second.
  • The upgrade is automatic and free with an unlimited limit, 100K+ unique users in a moving 24 hours and quality YELLOW or better.
  • Read a number's GREEN, YELLOW or RED rating from its quality_rating field; template quality has its own webhook.
  • Legacy events such as FLAGGED and DOWNGRADE belong to per-number limits before October 2025; log them if one ever arrives.

See InfiQ pricing

02 · Specifications

The phone number quality webhook: key facts and limits

Webhook fieldphone_number_quality_update
Documented eventsONBOARDING, THROUGHPUT_UPGRADE
Limit fieldmax_daily_conversations_per_business (the portfolio's)
Default throughputUp to 80 messages per second per number
Upgraded throughput1,000 messages per second, automatic and free
Upgrade criteriaUnlimited limit, 100K+ unique users in 24 hours, quality YELLOW or better
Quality values (API)quality_rating: GREEN, YELLOW, RED
Deprecated fieldscurrent_limit, old_limit (removal scheduled February 2026)

03 · Rationale

Why does the phone number quality webhook matter?

For a high-volume sender, THROUGHPUT_UPGRADE is the moment a broadcast can go out more than twelve times faster, and a sender that misses it keeps throttling itself to the default rate. For marketers the bigger risk is false comfort. Older dashboards treated this field as the quality alarm, but a quiet phone_number_quality_update stream today does not mean quality is fine. Quality has to be watched where it is now reported.

04 · Operation

How does the phone number quality webhook work?

  1. Subscribe to the related fields together

    Subscribe to phone_number_quality_update, business_capability_update, message_template_quality_update and account_alerts. Between them they cover throughput, limits, template quality and refused increases.

  2. Map the number

    The payload identifies the number by display_phone_number (digits, no plus sign), and entry.id is the WABA. Look up your phone_number_id from that pair rather than assuming one number per account.

  3. Hold sends while onboarding

    On ONBOARDING, keep the number out of campaign rotation until registration completes and a test message succeeds. TIER_NOT_SET means it has not sent anything yet.

  4. Raise the rate limiter on upgrade

    On THROUGHPUT_UPGRADE, lift that number's send rate from 80 towards 1,000 messages per second. The upgrade takes up to a minute, during which sends can fail with error 131057, so retry with backoff.

  5. Poll quality separately

    Read quality_rating on a schedule (and after big sends), and pause marketing when it falls. Treat any legacy FLAGGED or DOWNGRADE event, if one ever arrives, as an alarm.

05 · Code samples

The phone number quality webhook in code

export async function onNumberQualityUpdate(entry, change) {
  const v = change.value;
  const number = await numbers.byDisplay(entry.id, v.display_phone_number); // WABA + digits
 
  switch (v.event) {
    case "ONBOARDING":
      await number.setStatus("onboarding");          // keep out of campaign rotation
      break;
    case "THROUGHPUT_UPGRADE":
      await rateLimiter.set(number.phoneNumberId, { perSecond: 1000 });
      await alerts.info("Throughput upgraded to 1,000 mps for " + v.display_phone_number);
      break;
    default:
      // Legacy values (FLAGGED, DOWNGRADE...) or new ones: never ignore silently.
      await alerts.warn("phone_number_quality_update: " + v.event, v);
  }
  if (v.max_daily_conversations_per_business) {
    await portfolios.setLimitTier(entry.id, v.max_daily_conversations_per_business);
  }
}

Map the number, act on the two documented events and raise an alert for anything else.

06Playground

A working model of Phone Number Quality Webhook. Use its controls to replay it step by step.

When does a number earn THROUGHPUT_UPGRADE?

4 / 4
050100150118 K users
  • Default: up to 80 mps0–100 K users
  • Eligible for 1,000 mps100–150 K users
Reading 4 of 4Eligible for 1,000 mps

THROUGHPUT_UPGRADE

118 K users

Unlimited limit, over 100K unique users in 24 hours, quality YELLOW or better: Meta upgrades the number and posts the event.

The needle tracks an illustrative portfolio's unique users messaged outside a service window in a moving 24 hours. Step through the readings to see when the webhook fires.

THROUGHPUT_UPGRADE: 118 K users — Eligible for 1,000 mps zone. Unlimited limit, over 100K unique users in 24 hours, quality YELLOW or better: Meta upgrades the number and posts the event.

07 · Cautions

Common mistakes with the phone number quality webhook

  • Using it as the quality alarm

    A dashboard that waits for FLAGGED will wait for ever: the current reference no longer lists it. Poll quality_rating, subscribe to template quality updates, and alert on falls there.

  • Hard-coding the old event list

    Code written for FLAGGED/UNFLAGGED/UPGRADE/DOWNGRADE may ignore THROUGHPUT_UPGRADE, and a strict parser may throw on it. Branch on known values and log the rest.

  • Raising throughput before the webhook

    Sending above 80 messages per second before the upgrade returns error 130429 and wastes retries. Raise the limiter when THROUGHPUT_UPGRADE arrives, and expect 131057 for up to a minute.

  • Reading the deprecated limit fields

    current_limit and old_limit were scheduled for removal in February 2026. Use max_daily_conversations_per_business, or GET whatsapp_business_manager_messaging_limit, instead.

08 · Questions and answers

Phone Number Quality Webhook FAQs

Does phone_number_quality_update still fire when my quality drops?
Meta's current reference lists only ONBOARDING and THROUGHPUT_UPGRADE for this field. Read quality from the phone number's quality_rating and watch template quality webhooks; sustained low quality blocks upgrades and can lead to restrictions.
Do I have to request the 1,000 messages-per-second upgrade?
No. Meta upgrades eligible numbers automatically and free once the portfolio has an unlimited limit, has messaged 100,000 or more unique users outside a service window in a moving 24 hours, and has quality YELLOW or better.
How is this different from business_capability_update?
business_capability_update announces the portfolio's messaging limit and phone-number allowance. phone_number_quality_update is about one number's status — onboarding or a throughput upgrade — and carries the portfolio limit only as context.
Why do sends fail with error 131057 right after a throughput upgrade?
The upgrade is still being applied. Moving a number to 1,000 messages per second takes up to a minute, and sends during that time can return 131057, so retry them with backoff rather than treating them as failures.

09 · Worked example: Match-night offers in Hyderabad

Example: Match-night offers in Hyderabad

A Hyderabad food-delivery platform messages around 120,000 opted-in users before evening cricket matches during a tournament. Its portfolio already has an unlimited limit and its quality is GREEN, so once it passes 100,000 unique users in a moving 24 hours, its number receives phone_number_quality_update with event: THROUGHPUT_UPGRADE. The sender raises its rate limiter from 80 to 1,000 messages per second. The 7:30 pm broadcast that used to take about 25 minutes now finishes in about two, before the toss rather than after it.

10 · Recommended practice

Best practices for the phone number quality webhook

  • Keep a per-number record of throughput level (80 or 1,000 mps) and the date it changed; campaign timing depends on it.
  • Before a big send, check the number with the Health Status API as well — it says whether the number can send at all.
  • Remember coexistence numbers are fixed at 20 messages per second, counting incoming and outgoing together.
  • Recheck quality_rating after any large marketing send, not just on a timer.
  • Sustained low quality blocks upgrades and can lead to restrictions — fix templates before scaling sends.

Put Phone Number Quality Webhook to work

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms