business_capability_update Webhook

Field reference for WhatsApp business_capability_update webhooks: messaging limits, phone-number caps, capability changes, and Dualhook handling.

The business_capability_update field reports capability limits on a WABA or business portfolio. It is mainly about messaging capacity and phone-number capacity.

What business_capability_update Reports

This field can report:

messaging limits for the business portfolio,
maximum phone numbers allowed per business portfolio,
maximum phone numbers allowed per WABA,
capability increases or decreases after Meta review or usage changes.

When It Fires

Meta sends it when a WABA is created or when business capabilities change. Capability changes can be increases or decreases, so treat this as a state update rather than only as a success signal.

Payload Shape

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "time": 1739321024,
      "changes": [
        {
          "field": "business_capability_update",
          "value": {
            "max_daily_conversations_per_business": 2000,
            "max_phone_numbers_per_waba": 25
          }
        }
      ]
    }
  ]
}

Common fields:

Field	Notes
`max_daily_conversations_per_business`	Current business messaging limit. Meta documentation may present tier-style values; normalize before display.
`max_daily_conversation_per_phone`	Legacy per-phone field scheduled for removal from Meta docs. Prefer business-level limits.
`max_phone_numbers_per_business`	Business portfolio phone-number cap.
`max_phone_numbers_per_waba`	WABA phone-number cap.

Dualhook Handling

Dualhook subscribes to business_capability_update as a management field. It uses the event to keep capacity and limit signals current in the dashboard and forwards the management event to your endpoint.

The field contains account metadata, not user messages. Dualhook stores the relevant operational metadata and forwarding status only.

Implementation Notes

Treat missing fields as "unchanged or not included", not as zero.
Normalize numeric and tier-style messaging-limit values into your internal format.
Alert operators when a capability decreases, because sends, number onboarding, or customer growth may be affected.
Pair this field with phone_number_quality_update and account_alerts for capacity monitoring.

Webhook Subscription FieldsReference list of all 22+ WhatsApp Business Platform webhook subscription fields, what each notifies you of, required permissions, payload size limits, retry policy, mTLS support, and IP allowlisting.
Capacity, Quality & LimitsAPI rate limits, messaging limit tiers, quality rating, and scaling guidance.
Phone NumbersManaging phone numbers in WhatsApp Business Platform: adding, removing, and limits.
Messaging Health StatusMonitor phone number health: AVAILABLE, LIMITED, BLOCKED states and quality rating.

Browse more docs Start Free Trial