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’s throughput level.

Triggers

    A business phone 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’s throughput level has increased to higher throughput.
    THROUGHPUT_UPGRADE
    <MAX_DAILY_MESSAGES_LIMIT>
    String
    Indicates a change to the owning business 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"
    }
    
    
            
    
        
    
    
    
        
    
            
    
                
                
    
                    
                    
                
    
            
    
            
            
    
                                            
    
        
    
    
    

    

    
    
    

    
            
    
            
    

    
    
        
    
            
            
        
    
            
    

    
    
        
    
                    
    

        
    No comments to display
    

            
    

    

    

                
    
        
    
                
    
        
    
    
    

    
    

    
    
    
        
    
             Back to top