Skip to main content

phone_number_quality_update webhook reference | Developer Documentation

phone_number_quality_update webhook reference

Updated: Nov 14, 2025
This reference describes trigger events and payload contents for the WhatsApp Business Account phone_number_quality_update webhook.
The phone_number_quality_update webhook notifies you of changes to a business phone number’number's throughput level.

Triggers

    A business phone number’number's throughput level changes.

    Syntax

    {
    
"entry": [
          {
            "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
            "time": <WEBHOOK_TRIGGER_TIMESTAMP>,
            "changes": [
              {
                "value": {
                  "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                  "event": "<EVENT>",
                  "old_limit": "<OLD_LIMIT>", <!-- only included for messaging limit changes -->
                  "current_limit": "<CURRENT_LIMIT>",
                  "max_daily_conversations_per_business": "<MAX_DAILY_MESSAGES_LIMIT>"
                },
                "field": "phone_number_quality_update"
              }
            ]
          }
        ],
        "object": "whatsapp_business_account"
      }
    Parameters
    

    

    



Placeholder 

Description 

Example value 




    

    <BUSINESS_DISPLAY_PHONE_NUMBER>
    

    String
    


    

    Business display phone number.
    


    

    15550783881
    



    

    <CURRENT_LIMIT>
    

    String
    


    

    This field will be removed in February, 2026. Use max_daily_conversations_per_business instead.
    

    Indicates current messaging limit or throughput level.
    

    Values can be:
    

    TIER_50 —- Indicates a messaging limit of 50.
    

    TIER_250 —- Indicates a messaging limit of 250.
    

    TIER_2K —- Indicates a messaging limit of 2,000.
    

    TIER_10K —- Indicates a messaging limit of 10,000.
    

    TIER_100K —- Indicates a messaging limit of 100,000.
    

    TIER_NOT_SET —- Indicates the business phone number has not been used to send a message yet.
    

    TIER_UNLIMITED —- Indicates the business phone number has higher throughput.
    


    

    TIER_UNLIMITED
    



    

    <EVENT>
    

    String
    


    

    Messaging limit change or throughput change event.
    

    Values can be:
    

    ONBOARDING —- Indicates the business phone number is still being registered.
    

    THROUGHPUT_UPGRADE —- Indicates the business phone number’number's throughput level has increased to higher throughput.
    


    

    THROUGHPUT_UPGRADE
    



    

    <MAX_DAILY_MESSAGES_LIMIT>
    

    String
    


    

    Indicates a change to the owning business portfolio’portfolio's messaging limit or throughput change.
    

    Values can be:
    

    TIER_50 —- Indicates a messaging limit of 50.
    

    TIER_250 —- Indicates a messaging limit of 250.
    

    TIER_2K —- Indicates a messaging limit of 2,000.
    

    TIER_10K —- Indicates a messaging limit of 10,000.
    

    TIER_100K —- Indicates a messaging limit of 100,000.
    

    TIER_NOT_SET —- Indicates the business phone number has not been used to send a message yet.
    

    TIER_UNLIMITED —- Indicates the business phone number has higher throughput.
    


    

    TIER_2K
    



    

    <OLD_LIMIT>
    

    String
    


    

    This parameter will be removed in February, 2026. Use max_daily_conversations_per_business instead.
    

    Indicates old messaging limit.
    

    Values can be:
    

    TIER_50 —- Indicates a messaging limit of 50.
    

    TIER_250 —- Indicates a messaging limit of 250.
    

    TIER_2K —- Indicates a messaging limit of 2,000.
    

    TIER_10K —- Indicates a messaging limit of 10,000.
    

    TIER_100K —- Indicates a messaging limit of 100,000.
    

    TIER_NOT_SET —- Indicates the business phone number has not been used to send a message yet.
    


    

    TIER_UNLIMITED
    



    

    <WEBHOOK_TRIGGER_TIMESTAMP>
    

    Integer
    


    

    Unix timestamp indicating when the webhook was triggered.
    


    

    1739321024
    



    

    <WHATSAPP_BUSINESS_ACCOUNT_ID>
    

    String
    


    

    WhatsApp Business Account ID.
    


    

    102290129340398
    Example
    {
    "entry": [
        {
    "id": "102290129340398",
    "time": 1748454394,
    "changes": [
            {
    "value": {
    "display_phone_number": "15550783881",
    "event": "THROUGHPUT_UPGRADE",
    "current_limit": "TIER_UNLIMITED"
              },
    "field": "phone_number_quality_update"
            }
          ]
        }
      ],
    "object": "whatsapp_business_account"
    }
    
    
            
    
    
    

            
    
        
    
    
    

    
    

    
    
    
        
    
             Back to top