Does business_capability_update fire when my limit goes down?

Yes, Meta documents it for decreases as well as increases of a capability, so handle both. In practice limits mostly grow; sustained low quality blocks upgrades and can lead to restrictions, which arrive through account_update, while refused increases arrive in account_alerts.

Is the limit per phone number?

No. Since October 2025 messaging limits are set per business portfolio and shared by all its numbers, so the webhook describes the whole business.

How do I check the limit without waiting for a webhook?

Request the whatsapp_business_manager_messaging_limit field on any business phone number in the portfolio; because limits are shared, it returns the portfolio's tier, such as TIER_10K. The older messaging_limit_tier field is deprecated.

Will the tier ladder change?

New portfolios start at 250; verification or Meta's quality path unlocks higher limits that grow automatically to unlimited. Write handlers that accept any documented tier value rather than hard-coding a fixed number of steps.

business_capability_update: WhatsApp Limit Webhook

Description

What is the business capability update webhook?

The business capability update webhook is the business_capability_update field. Meta sends it when a WhatsApp Business Account is created and whenever one of the business's capabilities goes up or down — above all its messaging limit, and also its phone number limit, the number of business phone numbers it may register. It is the push version of reading the limit from the API: instead of polling, your system hears about a new limit when it happens.

The limit sits in value.max_daily_conversations_per_business as a tier: TIER_250, TIER_2K, TIER_10K, TIER_100K or TIER_UNLIMITED. Meta's own example shows a plain integer there, so a robust handler accepts both forms. The older max_daily_conversation_per_phone (integers, with -1 meaning unlimited) was deprecated, with removal scheduled for February 2026, so new code should not rely on it. Alongside the limit comes max_phone_numbers_per_business while the business is at 250, or max_phone_numbers_per_waba once it is above.

Two cautions about the names. The limit is not a count of conversations: it counts unique users messaged outside a customer service window in a moving 24 hours, and since October 2025 it is set for the whole business portfolio and shared by all its numbers. And this webhook reports the limit itself, while the phone number quality webhook reports events about one number such as a throughput upgrade, and a number's quality rating is read from the API. If a requested increase is refused, the explanation arrives in account_alerts, not here.

Key takeaways

The business capability update webhook (business_capability_update) pushes a business's new messaging limit and phone-number allowance as soon as they change.
The limit arrives in max_daily_conversations_per_business as a tier from TIER_250 to TIER_UNLIMITED; accept a plain integer too.
Despite the field name, the limit counts unique users messaged outside a service window in a moving 24 hours, not conversations.
Since October 2025 the limit belongs to the business portfolio and is shared by every phone number in it.
A refused limit increase is explained in the account_alerts webhook, not in this one.

Why it matters

Why does the business capability update webhook matter?

The messaging limit decides how many people a broadcast can reach in a day. A campaign sized for 10,000 users that runs on a 2,000 limit fails for most of its audience; one sized for 2,000 after the business reached 100,000 leaves reach on the table. Wiring this webhook into the campaign scheduler keeps every send matched to the limit that applies right now, without anyone checking WhatsApp Manager by hand.

Mechanics

How does the business capability update webhook work?

step 1 — Subscribe and store the starting tier
Tick business_capability_update in the app's webhook fields. The first event arrives when the WABA is created; store its tier and phone-number allowance against the business portfolio, not against one number.
step 2 — Normalise the value
Map TIER_250…TIER_UNLIMITED (or an integer, if that is what arrives) to one internal number, with unlimited as infinity. Treat every field as optional; the payload only includes what changed.
step 3 — Recalculate send capacity
Unique users already messaged outside a service window in the last 24 hours count against the new limit. Subtract them and pass the remaining headroom to the broadcast scheduler.
step 4 — Resize running campaigns
On an increase, release held batches. On a decrease, shrink the next batches and push the rest to tomorrow, so templates are not sent to users the limit will not allow.
step 5 — Watch the companion signals
A denied increase arrives in account_alerts with an alert_type such as INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED. Show it beside the current tier so the business knows why it is not growing.

Usage

The business capability update webhook in code

1const TIERS = {
2  TIER_250: 250, TIER_2K: 2000, TIER_10K: 10000,
3  TIER_100K: 100000, TIER_UNLIMITED: Infinity,
4};
5 
6// Accept the tier string from the docs or the integer seen in Meta's example.
7function toLimit(raw) {
8  if (raw === undefined || raw === null) return undefined;
9  if (typeof raw === "number") return raw === -1 ? Infinity : raw;
10  return TIERS[raw];
11}
12 
13export async function onCapabilityUpdate(entry, change) {
14  const v = change.value;
15  const limit = toLimit(v.max_daily_conversations_per_business ?? v.max_daily_conversation_per_phone);
16  if (limit !== undefined) {
17    await portfolios.setLimit(entry.id, limit);       // shared by every number
18    const used = await sends.uniqueUsersOutsideWindow(entry.id, { hours: 24 });
19    await scheduler.resize(entry.id, Math.max(0, limit - used));
20  }
21  const numbers = v.max_phone_numbers_per_waba ?? v.max_phone_numbers_per_business;
22  if (numbers !== undefined) await portfolios.setNumberAllowance(entry.id, numbers);
23}

Map tiers to numbers, recompute headroom over the moving 24 hours, and hand it to the scheduler.

Properties

The business capability update webhook: key facts and limits

Webhook field: business_capability_update
Fires on: WABA creation and any capability increase or decrease
Limit field: max_daily_conversations_per_business
Tier values: TIER_250, TIER_2K, TIER_10K, TIER_100K, TIER_UNLIMITED
What the limit counts: Unique users outside a service window, moving 24 hours
Level: Business portfolio, shared by all its numbers (since October 2025)
Automatic step up: High quality and half the limit used in 7 days; within 6 hours
Deprecated field: max_daily_conversation_per_phone (Meta set removal for February 2026)

Example

Example: A Diwali sale that grew mid-week

An Indore home-goods brand plans its Diwali campaign while its portfolio sits on TIER_10K, so the scheduler splits 32,000 opted-in customers into daily waves of about 9,500, leaving headroom for order updates. On Tuesday afternoon a business_capability_update webhook reports TIER_100K. The scheduler recalculates, merges Wednesday's and Thursday's waves into the current send and finishes the campaign two days early. Nobody had to notice the upgrade in WhatsApp Manager.

Caveats

Common mistakes with the business capability update webhook

Reading the field name literally
max_daily_conversations_per_business is a legacy name. The limit counts unique users messaged outside a service window in a moving 24 hours, not conversations or calendar days. Size sends on that definition.
Storing the limit per phone number
Since October 2025 the limit belongs to the business portfolio and every number shares it. Two numbers each running a 2,000-user campaign on a TIER_2K portfolio will exhaust it twice over.
Parsing only one format
The reference lists tier strings while Meta's example shows an integer, and integrations built before 2026 used the deprecated integer field. Accept both and alert when neither parses.
Waiting for a downgrade event that may not come
Sustained low quality blocks upgrades and can lead to restrictions, which arrive through other webhooks. Watch account_alerts, the account update webhook and template quality alongside this one.

Questions

Business Capability Update Webhook FAQs

Does business_capability_update fire when my limit goes down?: Yes, Meta documents it for decreases as well as increases of a capability, so handle both. In practice limits mostly grow; sustained low quality blocks upgrades and can lead to restrictions, which arrive through account_update, while refused increases arrive in account_alerts.
Is the limit per phone number?: No. Since October 2025 messaging limits are set per business portfolio and shared by all its numbers, so the webhook describes the whole business.
How do I check the limit without waiting for a webhook?: Request the whatsapp_business_manager_messaging_limit field on any business phone number in the portfolio; because limits are shared, it returns the portfolio's tier, such as TIER_10K. The older messaging_limit_tier field is deprecated.
Will the tier ladder change?: New portfolios start at 250; verification or Meta's quality path unlocks higher limits that grow automatically to unlimited. Write handlers that accept any documented tier value rather than hard-coding a fixed number of steps.

Notes

Best practices for the business capability update webhook

Keep a little headroom below the limit for utility and authentication sends outside a window, which count too.
Log every capability event with its timestamp; the history explains past campaign throughput.
Show the current tier and the date it last changed on the campaign launch screen.
Double-check the tier with a GET on whatsapp_business_manager_messaging_limit after a missed webhook or a restore.

See InfiQ pricing

Business Capability Update Webhook

Climb the limit ladder one webhook at a time

What is the business capability update webhook?

Why does the business capability update webhook matter?

How does the business capability update webhook work?

The business capability update webhook in code

The business capability update webhook: key facts and limits

Example: A Diwali sale that grew mid-week

Common mistakes with the business capability update webhook

Reading the field name literally

Storing the limit per phone number

Parsing only one format

Waiting for a downgrade event that may not come

Business Capability Update Webhook FAQs

Best practices for the business capability update webhook

See how this works on InfiQ

Put Business Capability Update Webhook to work

See how this works on InfiQ