WhatsApp Business Platform
WhatsApp Business Platform
Business Messaging
WhatsApp Business Platform
Resources

Business-scoped user IDs

Updated: Apr 9, 2026
This document received a major update on March 18, 2026. See the changelog entry for details.
WhatsApp is launching usernames later in 2026.
Usernames are an optional feature for users and businesses. If a username is adopted by a WhatsApp user, their username will be displayed instead of their phone number in the app. Business usernames are not intended for privacy, however. If you adopt a business username, it will not cause your business phone number to be hidden in the app.
To support usernames, Meta will share a new backend user identifier called business-scoped user ID, or BSUID. BSUID uniquely identifies a WhatsApp user and is tied to a specific business.
This document describes how the addition of usernames will impact API requests, API responses, and webhook payloads. Additional changes to support usernames before the feature is made available will be recorded here.
Any changes described in this document are subject to change.

User usernames

A user username is a unique, optional name that WhatsApp users can set in order to display their username instead of their phone number in the app. Usernames can be used in lieu of profile names when personalizing message content for individual users.
WhatsApp users are limited to 1 username, but are able to change them periodically. Changing a username does not affect the user’s phone number or business-scoped user ID, and does not affect the user’s ability to communicate with other WhatsApp users or businesses on the WhatsApp Business Platform. User usernames have the same format restrictions as business usernames.
Usernames are assigned to the username property in API responses and webhooks payloads. Once enabled, a WhatsApp user’s username will appear in all incoming messages webhooks, and all delivered and read status messages webhooks.

Business-scoped user ID

BSUIDs will begin appearing in webhooks in early April 2026.
A BSUID is a unique user identifier that can be used to message a WhatsApp user when you don’t know their phone number. BSUID will be assigned to the user_id parameter and appear in all messages webhooks, regardless of whether or not the user has enabled the username feature.
BSUIDs are scoped to individual business portfolios. This means that any business phone number owned by a given portfolio can be used to message a BSUID scoped to the same portfolio, and attempts to message the BSUID using a phone number owned by a different portfolio will fail.
BSUIDs will be:
  • generated automatically
  • prefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code and a period, followed by up to 128 alphanumeric characters (for example, US.13491208655302741918)
  • unique to each business portfolio-user pair (business portfolios⁠ were formerly known as Business Managers)
  • regenerated if a user changes their phone number (which trigger a system status messages webhook)
BSUIDs can be used to send any type of message except for one-tap, zero-tap, and copy code authentication templates, which require user phone numbers.
When making API requests with BSUIDs, use the entire BSUID value: country code, period, and all alpha numeric characters. Omitting or changing the country code, period, or alpha numeric characters will cause your request to fail.
If you are a managed business with multiple business portfolios, and want to use BSUIDs that will work across all of them, see Parent business-scoped user IDs.

Parent business-scoped user IDs

If you are a managed business and want to link business portfolios, you can ask your Meta point-of-contact to check if you are eligible. If you are eligible, and your business portfolios become linked, parent BSUIDs will be included in all messages webhooks, assigned to a new parent_user_id property.
Parent BSUIDs can be used in place of regular BSUIDS to message users. Functionally, parent BSUIDs have the same properties as regular BSUIDs, but can be used by any business phone number within the set of linked portfolios. Parent BSUIDs follow the same format as regular BSUIDs, but include ENT between the country code and the alphanumeric identifier (for example, US.ENT.11815799212886844830).
Note that you can still message users using their regular BSUID scoped to your business portfolio.

Phone numbers

If a WhatsApp user enables the username feature, their phone number will not be included in webhooks, unless you have interacted with the user before, as explained below. Therefore, regardless of whether or not the user has enabled the feature, the user’s BSUID will be included in any webhooks that would normally include their phone number, assigned to a new user_id property.
To reduce the chance of losing conversation context with existing users who enable the usernames feature, user phone numbers will be included in webhooks if any of the following conditions are met:
  • You have messaged or called the user’s phone number within the last 30 days of the webhook being triggered
  • You have received a message or call from the user’s phone number within the last 30 days of the webhook being triggered
  • The user is in your contact book
Note that the 30-day lookback conditions above are evaluated per business phone number. If you message a user from one of your business phone numbers, webhooks associated with a different business phone number in your portfolio will not include the user’s phone number unless that specific number has also sent or received a message or call to or from the user’s phone number within the last 30 days.
BSUIDs will begin appearing in webhooks in early April 2026. However, our APIs will not support sending messages targeted to the BSUIDs until May 2026 (exact date pending). Once our APIs support BSUIDs in May, you will be able to message users using either their BSUID, phone number, or both.
If you are a solution provider and provide WhatsApp messaging services to your business customers, your customers will be able to use your app to message users, using their portfolio’s business phone numbers and any BSUIDs scoped to their portfolio. If you attempt to use one of your business customer’s BSUIDs with your own business phone number, however, it will fail, since BSUIDs are scoped to portfolios (and essentially, the assets the portfolio owns).
If you are unsure of asset ownership:

Requesting phone numbers from users

This feature will be available in early May 2026.
To make it easier to request phone numbers from WhatsApp users, a REQUEST_CONTACT_INFO button type is available that can be added to utility and marketing templates.
If a user taps this button, their virtual contact card and WhatsApp phone number will be shared in the message thread, and a contacts webhook will be triggered, containing the user’s phone number and vCard⁠.
If you are using the contact book feature, their phone number will also be added to your contact book automatically. For businesses that have enabled Local Storage, Meta extracts the user’s phone number from the shared contact card (vCard) and stores it in your contact book on Meta data centers. Only the phone number is extracted and stored; no other vCard data is retained beyond the standard data-in-use period.
To add a request contact information button to a utility or marketing template, use the following payload structure when creating or editing a utility or marketing template:
{
  "type": "buttons",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO"
    },
    <!-- Additional button objects would go here, if using -->
  ]
}
Request contact information buttons cannot be customized, so you do not need to include any parameter values when sending the template.
Example contacts webhook payload with a vCard:
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<USER_DISPLAY_NAME>",
                  "username": "<USERNAME>",
                },
                "user_id": "<BSUID>"
              }
            ],
            "messages": [
              {
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "contacts",
                "origin": "contact_request/other",       <!-- ADDED -->
                "contacts": [
                  {
                    "vcard": "<VCARD>",                  <!-- ADDED -->
                    "phones": [
                      {
                        "phone": "<USER_PHONE_NUMBER>"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Contact book

In early April 2026, to support messaging thread continuity, a contact book feature that stores WhatsApp user contact information is being released. The contact book is provided and hosted by Meta; no integration work is required.
Once the feature is available, if you send a message/call to a user’s phone number, or receive a message/call from a user’s phone number, the user’s phone number and BSUID will be added to your contact book. Once this data has been recorded, it will be used to populate any webhook payloads and API responses that include the user’s phone number or BSUID, regardless of whether or not the user has enabled the usernames feature.
The contact book is scoped to the business portfolio level, so any interaction between any business phone number within the business portfolio and a user will trigger the user’s phone number and BSUID to be stored in the contact book. Only interactions that occur after the contact book launches will trigger storage; prior interactions will not be retroactively captured, and contact information from those users will not be included in API responses or webhooks.
Contact book data will be retained until you disable the feature, or deactivate your account. If you wish, you can disable this feature anytime after March 16, 2026, in the Meta Business Suite > Business settings > Business info⁠ panel. If you disable your contact book, it will stop storing user information, and any existing user information it has already stored will be deleted. If you re-enable the contact book later, it will start storing user information again, but previously stored information cannot be restored.
Limitations:
  • If you are using Local Storage and a user shares their phone number with you by tapping the share contact information button, Meta extracts the user’s phone number from the shared contact card (vCard) and stores it in your contact book on Meta data centers. Only the phone number is extracted and stored; no other vCard data is retained beyond the standard data-at-rest period for local storage.
  • Contact books are scoped to business portfolios. This means that if you have linked portfolios, a user’s phone number and BSUID would have to be recorded to each portfolio’s contact book independently; user contact information is not shared or synced across linked portfolios.

Country codes

If a WhatsApp user enables the username feature, their phone number (and thus, country dialing code) may not appear in webhooks. In these cases, the user’s BSUID will appear instead, prefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code (e.g., US.13491208655302741918).

Business usernames

Businesses will also be able to adopt a business username. If you adopt a business username, however, it will not cause your business phone number to be hidden in the WhatsApp or WhatsApp Business client.
A business username is mapped to a single business phone number across all of WhatsApp, i.e. a phone number can have only one username at a given time, and no two WhatsApp phone numbers (consumer or business) can have the same username.
Business usernames must adhere to the following format:
  • may only contain English letters (a-z), digits (0-9), period (.) and underscore (_) characters
  • non-English characters (such as ñ, é, ü) are not supported and will cause the request to fail
  • must be between 3-35 characters in length
  • must contain at least one English letter (a-z, A-Z)
  • must not start or end with a period or have 2 consecutive periods
  • must not start with www
  • must not end with a domain (e.g., .com, .org, .net, .int, .edu, .gov, .mil, .us, .in, .html, and so on)
  • case is ignored when comparing usernames, but period and underscore characters are not; for example, myID and myid are the same username but myid, my.id, and my_id are all distinct

Reserved usernames

Before the username feature is made available, you will have the option to claim a username that WhatsApp has reserved for you. Alternatively, you can adopt a different username that aligns with your branding requirements. A reserved username can be claimed through WhatsApp Manager, Meta Business Suite, or via API. Claimed usernames that are approved will become active once the username feature is made available.
If a reserved username is already in use with your Facebook Page or Instagram account, you must link your business phone number to your Facebook Page or Instagram account before you will be able to claim the username.
You can link your phone number when claiming the username in Meta Business Suite or WhatsApp Manager, or by accessing your Facebook Page or Instagram account and adding your phone number directly⁠.
To link your phone number, you must have full control of the page or account, or basic partial access with the manage_phone permission. See About business portfolio and business asset permissions⁠ for information about control/access and permissions.

Chat window display priority

The following priority will be followed (in decreasing order of priority) for displaying business profile information in chat windows in the app. Your business phone numbers will always appear in your business profile.

Support

Adopt or change a business username

This feature will be available later in 2026.
You will be able to adopt or change a business username using Meta Business Suite, WhatsApp Manager, WhatsApp Business app, or the API, later in the year (exact date pending).
Request syntax:
curl -X POST 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/username' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
  "username": "<DESIRED_USERNAME>"
}'
Response syntax, upon success:
{
  "status": "<STATUS>"
}
  • status — The status of the latest requested username. Values can be:
    • approved — The requested username has been approved and will be visible to WhatsApp users once the usernames feature is made available.
    • reserved — The requested username has been reserved and approved but not yet visible to WhatsApp users. It will appear to WhatsApp users once the feature is available for everyone.
Response syntax, upon failure:
{
  "error": {
    "message": "<MESSAGE>",
    "type": "<TYPE>",
    "code": <CODE>,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "<DETAILS>"
    },
    "error_subcode": <ERROR_SUBCODE>,
    "fbtrace_id": "<FBTRACE_ID>"
  }
}
CodeDetailsPossible reason and solutions
10
Application does not have permission for this action
Confirm that the system user whose token is used in the request has appropriate business asset access on the WhatsApp Business Account: either Full control or Partial access for Phone numbers.
33
Invalid ID
(1) The business phone number ID is invalid, (2) the WhatsApp Business Account associated with the business phone number has been deleted, or (3) the user whose token was used in the request has not granted the app the whatsapp_business_management permission (which requires Advanced Access if you are a solution provider)
100
Param Invalid
The username format is invalid.
147001
Username not available
The username has already been claimed, doesn’t pass our internal checks, or is not available for on the platform. Try requesting another username.
147002
Account not eligible to request a username
The business portfolio that owns the WhatsApp Business Account and business phone number must have a higher messaging limit.
147003
FB Account not linked
You must link⁠ the phone number to the Facebook Page that already uses the requested username.
147004
IG Account not linked
You must link⁠ the phone number to the Instagram account that already uses the requested username
133010
Account not registered
The business phone number must first be registered for API use.

Get current username

Use the Username API to get the status of the business username associated with the business phone number, or information about the username.
Request syntax:
curl 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/username' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Response syntax:
{
  "username": "<USERNAME>",
  "status": "<STATUS>"
}
  • username — Current username. Will be omitted if the business phone number has no username.
  • status — Username status. Values can be:
    • approved — The username is approved and visible to WhatsApp users.
    • reserved — The username is reserved for the business phone number but is not visible to WhatsApp users. It will become visible once the usernames feature is made available to everyone.

Get reserved usernames

Use the Username Suggestions API to get a list of usernames that have been reserved for your business portfolio.
Use the Username API to claim the desired username from the list, which will then need to be approved. Once approved and usernames become available in your country, it will move to to an “active” status, meaning the business username will start appearing on your business profile, and users will be able to search for it using exact match search.
Request syntax:
curl 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/username_suggestions' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Response syntax:
{
  "data": [
   {
     "username_suggestions": [
       "<RESERVED_USERNAME>",
       <!-- Additional usernames would follow, if any -->
     ]
   }
 ],
}
  • username_suggestions — An array of reserved usernames, if any. These usernames have a higher chance of approval.

Delete a username

Use the Username API to delete the business username associated with the business phone number.
Request syntax:
curl -X DELETE 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/username' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
Response syntax:
{
  "success": <SUCCESS?>
}
  • success — Boolean. Will be set to true if the username is deleted successfully, otherwise it will be set to false.

business_username_updates webhook

A new business_username_update webhook will be added. This webhook will be triggered when a business username status changes.
Please subscribe each of your apps to this webhook field to be notified of username changes.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <WEBHOOK_TRIGGER_TIMESTAMP>,
      "changes": [
        {
          "field": "business_username_update",
          "value": {
            "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
            "username": "<USERNAME>",
            "status": "<STATUS>"
          }
        }
      ]
    }
  ]
}
  • id — WhatsApp Business Account ID.
  • time — Unix timestamp indicated when the webhook was triggered.
  • display_phone_number — The business phone number’s display number (the number displayed on your profile in the app).
  • username — The username for which the status has changed. Omitted if status is set to deleted.
  • status — Values can be:
    • approved — Indicates the username is approved and visible to WhatsApp users. Triggered when the username’s status changes from reserved to approved, or the username was changed via the WhatsApp Business app.
    • deleted — Indicates the username has been deleted via the WhatsApp Business app.
    • reserved — Indicates the username is reserved for the business phone number but is not visible to WhatsApp users. It will become visible once the usernames feature is made available to everyone.

Messages

Send message requests

These changes will apply to Messages API requests.
This example syntax is sending a text message, but the changes apply to all message types.
'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<USER_PHONE_NUMBER>",    <!-- CHANGED -->
  "recipient": "<BSUID>",         <!-- ADDED -->
  "type": "text",
  "text": {
    "body": "<BODY_TEXT>"
  }
}'
You can include both to (phone number) and recipient (BSUID or parent BSUID) in your request. If you do, to (phone number) will take precedence. If you prefer, you can also use one or the other:
To send a message using only the user’s phone number:
  • set to to the user’s phone number
  • omit the recipient property
To send a message using only the user’s BSUID or parent BSUID:
  • set recipient to the user’s BSUID or parent BSUID
  • omit the to property

Send message response

These changes apply to Messages API responses.
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<USER_PHONE_NUMBER_OR_BSUID>",    <!-- CHANGED -->
      "wa_id": "<USER_PHONE_NUMBER>",             <!-- CHANGED -->
      "user_id": "<BSUID>"                        <!-- ADDED -->
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
    }
  ]
}
  • input — New value (BSUID or parent BSUID).
    • Will return the user’s phone number, if the message was sent to the user’s phone number.
    • Will return the user’s BSUID or parent BSUID, if it was sent to their BSUID or parent BSUID.
    • Will return the group ID, it sent to a group.
  • wa_id — New behavior (can be omitted). Will return the user’s phone number, if the message was sent to the user’s phone number. Otherwise, it will be omitted.
  • user_id — New property.
    • Will return the user’s BSUID or parent BSUID, if the message was sent to the user’s BSUID or parent BSUID.
    • Will be omitted if the message was sent to the user’s phone number, including when both the user’s phone number and BSUID or parent BSUID are included in the request (phone number takes precedence).
Example response to a send message request sent to a user’s phone number (user BSUID or parent BSUID not used in request):
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+16505551234",
      "wa_id": "16505551234"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"
    }
  ]
}
Example response to a send message request sent to a user’s BSUID (user phone number not used in request):
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "US.13491208655302741918",
      "user_id": "US.13491208655302741918"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"
    }
  ]
}
Example response to a send message request sent to a user’s phone number and BSUID (user phone number takes precedence):
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+16505551234",
      "wa_id": "16505551234"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"
    }
  ]
}

Error codes

Adding new error code response to the Messages API.
  • Error code — 131062
  • Details — Business-scoped User ID (BSUID) recipients are not supported for this message.

Marketing Messages API for WhatsApp

Send marketing message requests

Marketing Messages API for WhatsApp will support both phone numbers, BSUIDs, and parent BSUIDs. Sending messages to phone numbers is recommended, primarily so you can continue to receive phone numbers in webhooks.
These changes will apply to Marketing Messages API requests.
'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/marketing_messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<USER_PHONE_NUMBER>",    <!-- CHANGED -->
  "recipient": "<BSUID>",         <!-- ADDED -->
  "type": "template",
  "template": {
    <EXPECTED_TEMPLATE_PARAMETERS>
  }
}'
You can include both to (phone number) and recipient (BSUID or parent BSUID) in your request. If you do, to (phone number) will take precedence. If you prefer, you can also use one or the other:
To send a message using only the user’s phone number:
  • set to to the user’s phone number
  • omit the recipient property
To send a message using only the user’s BSUID or parent BSUID:
  • set recipient to the user’s BSUID or parent BSUID
  • omit the to property

Send marketing message response

These changes apply to Marketing Messages API responses.
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<USER_PHONE_NUMBER_OR_ID>",    <!-- CHANGED -->
      "wa_id": "<USER_PHONE_NUMBER>",          <!-- CHANGED -->
      "user_id": "<BSUID>"                     <!-- ADDED -->
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>",
      "message_status": "<PACING_STATUS>"
    }
  ]
}
  • input — New value (BSUID or parent BSUID).
    • Will return the user’s phone number, if the message was sent to the user’s phone number.
    • Will return the user’s BSUID or parent BSUID, if it was sent to their BSUID or parent BSUID.
    • Will return the group ID, if it was sent to a group.
  • wa_id — Will return the user’s phone number, if the message was sent to the user’s phone number. Otherwise, it will be omitted.
  • user_id — New property.
    • Will return the user’s BSUID or parent BSUID, if the message was sent to the user’s BSUID or parent BSUID.
    • Will be omitted if the message was sent to the user’s phone number, including when both the user’s phone number and BSUID or parent BSUID are included in the request (phone number takes precedence).
Example response to a send a template message to a user’s phone number:
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+16505551234",
      "wa_id": "16505551234"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA",
      "message_status": "accepted"
    }
  ]
}
Example response to a send a template message to a user’s BSUID:
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "US.13491208655302741918",
      "user_id": "US.13491208655302741918"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA",
      "message_status": "accepted"
    }
  ]
}

Webhook testing

You can test webhook payloads that reflect real-world username adoption scenarios using the App Dashboard > Use cases (pencil icon) > Connect with customers through WhatsApp > Customize > Configuration panel (App Dashboard > WhatsApp > Configuration for apps created before December, 2025). Click the Test link alongside the messages webhook to send a test messages webhook to your webhook endpoint.
The test tool supports incoming messages webhooks and status messages webhooks for sent messages, with the following scenarios:
  • User has not adopted a username — Webhook payloads will include BSUID fields and phone number fields, but no username. This represents the default state for most users at launch.
  • User has adopted a username and phone number is unavailable — Webhook payloads will include the username and BSUID fields, but phone number fields will be omitted. Your integration should handle this scenario gracefully. See Phone numbers for conditions under which phone numbers are included.
  • User has adopted a username and phone number is available — Webhook payloads will include all fields: username, BSUID, and phone number.
  • Parent BSUID present — For businesses with linked business portfolios, webhook payloads will include a parent BSUID in addition to the portfolio-level BSUID.

Webhook identifier quick reference

The following tables summarize which user identifiers will be included in messages webhooks, based on the type of webhook and whether the user has adopted a username.

Outbound message status webhooks

These identifiers apply to sent, delivered, and read status messages webhooks.
IdentifierSent to phone numberSent to BSUID
wa_id
Always included
Included if phone number is available per Phone numbers conditions
user_id
Always included
Always included
parent_user_id
Included if parent BSUIDs enabled
Included if parent BSUIDs enabled
parent_recipient_user_id
Included if parent BSUIDs enabled
Included if parent BSUIDs enabled
username
Included in delivered/read if user has a username
Included in delivered/read if user has a username

Incoming messages webhooks

These identifiers apply to incoming messages webhooks, including user-initiated messages and user replies.
IdentifierUser has a usernameUser does not have a username
wa_id
Included if phone number is available per Phone numbers conditions
Always included
user_id
Always included
Always included
parent_user_id
Included if parent BSUIDs enabled
Included if parent BSUIDs enabled
username
Always included
Not included

Messages webhooks

Status messages webhooks

These changes will apply to sent, delivered, read, and failed status messages webhooks.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },

            <!-- Contacts will be included for sent, delivered, and read status -->
            "contacts": [                                      <!-- ADDED -->
              {
                "profile": {
                  "name": "<USER_DISPLAY_NAME>",               <!-- ADDED -->

                  <!-- Only included if user has enabled the username feature -->
                  "username": "<USERNAME>"                     <!-- ADDED -->

                },
                "wa_id": "<USER_PHONE_NUMBER>",                <!-- ADDED -->
                "user_id": "<BSUID>",                          <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"             <!-- ADDED -->
              }
            ],

            "statuses": [
              {
                "id": "<WHATSAPP_MESSAGE_ID>",
                "status": "<STATUS>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "recipient_id": "<USER_PHONE_NUMBER>",         <!-- CHANGED -->
                "recipient_user_id": "<BSUID>",                <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_recipient_user_id": "<PARENT_BSUID>"   <!-- ADDED -->
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
  • contacts — New array. Only included for sent, delivered, and read status messages. Will be omitted entirely for failed status messages webhooks.
    • name — New property. Value will be set to the WhatsApp user’s display name.
    • username — New property.
      • Will be set to the WhatsApp user’s username if the user has enabled the usernames feature.
      • Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature.
    • wa_id — New property.
      • Will be set to the user’s phone number if the phone number can be included based on the conditions described in the Phone numbers section.
      • Will be omitted if the phone number cannot be included based on those conditions.
    • user_id — New property. Will be set to the WhatsApp user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, the property will be omitted entirely.
  • statuses
    • recipient_id — New behavior (can be omitted).
      • Will be set to the user’s phone number, if you sent the message to the user’s phone number.
      • Will be set to the group ID, if you sent the message to a group.
      • Will be omitted if you sent the message to the user’s BSUID or parent BSUID and we are unable to include their phone number based on the conditions described in the Phone numbers section.
    • recipient_user_id — New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
    • parent_recipient_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
Example delivered status messages webhook describing a message sent from a business that has enabled parent BSUIDS to the phone number of a WhatsApp user who has enabled the usernames feature:
{
 "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M.",
                  "username": "@pablomorales"
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.11815799212886844830"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "delivered",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "parent_recipient_user_id": "US.ENT.11815799212886844830",
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
Example delivered status messages webhook describing a message sent from a business that has enabled parent BSUIDS, to the BSUID of a WhatsApp user who has enabled the username feature. In this example, we are unable to include their phone number based on the conditions described in the Phone numbers section (so wa_id and recipient_id are omitted).
{
 "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M.",
                  "username": "@pablomorales"
                },
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.11815799212886844830"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "delivered",
                "timestamp": "1750030073",
                "recipient_user_id": "US.13491208655302741918",
                "parent_recipient_user_id": "US.ENT.11815799212886844830",
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Incoming messages webhooks

These changes apply to incoming messages webhooks (text, image, interactive, and so on), including incoming messages sent by users in a Group chat.
The example syntax below is for an incoming text message, but the changes are the same for all incoming message types.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_PROFILE_NAME>",

                  <!-- Only included if user has enabled the username feature -->
                  "username": "<USERNAME>"                 <!-- ADDED -->
                },
                "wa_id": "<WHATSAPP_USER_ID>",             <!-- CHANGED -->
                "user_id": "<BSUID>",                      <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"         <!-- ADDED -->
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",    <!-- CHANGED -->
                "from_user_id": "<BSUID>",                 <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "from_parent_user_id": "<PARENT_BSUID>",   <!-- ADDED -->

                <!-- Only included if incoming message sent in a group -->
                "group_id": "<GROUP_ID>",

                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "text",
                "text": {
                  "body": "<MESSAGE_TEXT_BODY>"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
  • contacts
    • profile
      • username — New property.
        • Will be set to the user’s username, if the user has enabled the username feature.
        • Will be omitted if the user has not adopted a username.
    • wa_id — New behavior (can be omitted).
      • Will be set to the user’s phone number if the phone number can be included based on the conditions described in the Phone numbers section.
      • Will be omitted if the phone number cannot be included based on those conditions.
    • user_id — New property, set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • messages
    • from — New behavior (can be omitted).
      • Will be set to the user’s phone number if the phone number can be included based on the conditions described in the Phone numbers section.
      • Will be omitted if the phone number cannot be included based on those conditions.
    • from_user_id — New property, set to the user’s BSUID.
    • from_parent_user_id — New property, set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.
Example incoming text message from a user who has enabled the username feature, to a business that has enabled parent BSUIDs. In this scenario, we are unable to include their phone number based on the conditions described in the Phone numbers section.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Sheena Nelson",
                  "username": "@realsheenanelson"
                },
                "user_id": "uUS.13491208655302741918",
                "parent_user_id": "US.ENT.11815799212886844830"
              }
            ],
            "messages": [
              {
                "from_user_id": "US.13491208655302741918",
                "from_parent_user_id": "US.ENT.11815799212886844830",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
                "timestamp": "1749416383",
                "type": "text",
                "text": {
                  "body": "Does it come in another color?"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

System status messages webhooks

These changes apply to system status messages webhooks.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "system",
                "system": {
                  "body": "User...",                       <!-- CHANGED -->
                  "wa_id": "<NEW_WHATSAPP_USER_ID>",       <!-- CHANGED -->
                  "user_id": "<NEW_BSUID>",                <!-- ADDED -->

                  <!-- Only included if parent BSUIDs enabled -->
                  "parent_user_id": "<NEW_PARENT_BSUID>",  <!-- ADDED -->
                  "type": "<SYSTEM_CHANGE_TYPE>"           <!-- CHANGED -->
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
  • system
    • body — New string. Will be set to User <WHATSAPP_USER_PROFILE_NAME> changed from <OLD_BSUID> to <NEW_BSUID> if the user changed their business phone number.
    • wa_id — New behavior (can be omitted).
      • Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
      • Will be set to the user’s phone number if the user has not enabled the usernames feature.
    • user_id — New property. Will be set to the user’s new BSUID.
    • parent_user_id — New property. Will be set to the user’s new parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted. type — New value (user_changed_user_id). Will be set to user_changed_user_id if the WhatsApp user changed their phone number.

user_preferences webhooks

These changes will apply to user_preferences webhooks.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>",

                  <!-- Only included if user has enabled the usernames feature -->
                  "username": "<USERNAME>"                 <!-- ADDED -->
                },
                "wa_id": "<WHATSAPP_USER_ID>",             <!-- CHANGED -->
                "user_id": "<BSUID>",                      <!-- ADDED -->

                <!-- Only included if you have enabled parent BSUIDs -->
                "parent_user_id": "<PARENT_BSUID>"         <!-- ADDED -->
              }
            ],
            "user_preferences": [
              {
                "wa_id": "<WHATSAPP_USER_ID>",             <!-- CHANGED -->
                "user_id": "<BSUID>",                      <!-- ADDED -->

                <!-- Only included if you have enabled parent BSUIDs -->
                "parent_user_id": "<PARENT_BSUID>",        <!-- ADDED -->

                "detail": "<PREFERENCE_DESCRIPTION>",
                "category": "marketing_messages",
                "value": "<PREFERENCE>",
                "timestamp": <WEBHOOK_SENT_TIMESTAMP>
              }
            ]
          },
          "field": "user_preferences"
        }
      ]
    }
  ]
}
  • contacts
    • profile
      • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature.
    • wa_id — New behavior (can be omitted).
      • Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
      • Will be set to the user’s phone number if the user has not enabled the usernames feature.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • user_preferences
    • wa_id — New behavior (can be omitted). Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.

user_id_update webhooks

A new user_id_update webhook will be triggered when a WhatsApp user’s BSUID changes. Subscribe your apps to this webhook field to be notified of BSUID changes.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "user_id_update": [
              {
                "wa_id": "<WHATSAPP_USER_ID>",
                "detail": "User id for <WHATSAPP_USER_PROFILE_NAME> has been updated.",
                "user_id": {
                  "previous": "<OLD_BSUID>",
                  "current": "<NEW_BSUID>"
                },

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": {
                  "previous": "<OLD_PARENT_BSUID>",
                  "current": "<NEW_PARENT_BSUID>"
                },

                "timestamp": "<WEBHOOK_SENT_TIMESTAMP>"
              }
            ]
          },
          "field": "user_id_update"
        }
      ]
    }
  ]
}
  • contacts
    • wa_id — Will be set to the user’s phone number if available. Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
  • user_id_update
    • wa_id — Will be set to the user’s phone number if available. Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
    • detail — A human-readable description of the update.
    • user_id — Object containing the user’s previous and current BSUID.
      • previous — The user’s old BSUID.
      • current — The user’s new BSUID.
    • parent_user_id — Object containing the user’s previous and current parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.
      • previous — The user’s old parent BSUID.
      • current — The user’s new parent BSUID.
    • timestamp — Unix timestamp indicating when the webhook was sent.

Groups API

Get group info

These changes apply to Group API responses.
{
  "participants": [
    {
      "wa_id": "<USER_PHONE_NUMBER>"        <!-- CHANGED -->
      "user_id": "<BSUID>",                 <!-- ADDED -->

      <!-- Only returned if the you have enabled parent BSUIDs -->
      "parent_user_id": "<PARENT_BSUID>",   <!-- ADDED -->

      <!-- Only returned if the user has enabled the usernames feature -->
      "username": "<USERNAME>"              <!-- ADDED -->

    }
  ],
  "subject": "<GROUP_SUBJECT>",
  "id": "<GROUP_ID>",
  "messaging_product": "whatsapp"
}
  • wa_id — New behavior (can be omitted).
    • Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
    • Will be set to the user’s phone number if the user has not enabled the usernames feature.
  • user_id — New property. Will be set to the user’s BSUID.
  • parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • username — New property.
    • Will be set to the user’s username, if the user has enabled the username feature.
    • Will be omitted if the user is not using, or has disabled, the username feature.

Get group join requests

These changes apply to Join Requests API responses.
{
  "data": [
    {
      "join_request_id": "<JOIN_REQUEST_ID>",
      "creation_timestamp": "<JOIN_REQUEST_TIMESTAMP>",
      "wa_id": "<USER_PHONE_NUMBER>",                    <!-- CHANGED -->
      "user_id": "<BSUID>",                              <!-- ADDED -->

      <!-- Only included if parent BSUIDs enabled -->
      "parent_user_id": "<PARENT_BSUID>",                <!-- ADDED -->

      <!-- Only included if user has enabled usernames feature -->
      "username": "<USERNAME>"                           <!-- ADDED -->
    }
  ],
  "paging": {
    "cursors": {
      "before": "<BEFORE_CURSOR>",
      "after": "<AFTER_CURSOR>"
    }
  }
}
  • wa_id — New behavior (can be omitted).
    • Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
    • Will be set to the user’s phone number if the user has not enabled the usernames feature.
  • user_id — New property. Will be set to the user’s BSUID.
  • parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Will be omitted if the user has not enabled the username feature.

Remove group participants

These changes apply to Participants API requests.
curl -g -X DELETE 'https://graph.facebook.com/<API_VERSION>/<GROUP_ID>/participants' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
  "messaging_product": "whatsapp",
  "participants": [
    {
      "user": "<USER_PHONE_NUMBER>"    <!-- CHANGED -->
    }
  ]
}'
  • user — Will accept a user’s phone number or BSUID.

Groups API webhooks

Status messages webhooks for groups

These changes will apply to delivered and readstatus messages webhooks for messages sent to a group.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },

           <!-- Contacts will be included for delivered and read status -->
           "contacts": [                             <!-- ADDED -->
                {
                  "profile": {
                    "name": "<USER_DISPLAY_NAME>",   <!-- ADDED -->

                    <!-- Only included if user has enabled usernames feature -->
                    "username": "<USERNAME>"         <!-- ADDED -->
                  },
                  "wa_id": "<USER_PHONE_NUMBER>",    <!-- ADDED -->
                  "user_id": "<BSUID>",              <!-- ADDED -->

                  <!-- Only included if parent BSUIDs enabled -->
                  "parent_user_id": "<PARENT_BSUID>"
                },
                # Additional contact objects would follow, if aggregated
                {
                  ...
                }
              ],

            "statuses": [
              {
                "id": "<WHATSAPP_MESSAGE_ID>",
                "status": "<STATUS>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "recipient_id": "<GROUP_ID>",
                "recipient_type": "group",
                "recipient_participant_id": "<GROUP_PARTICIPANT_USER_PHONE_NUMBER>", <!-- CHANGED -->
                "recipient_participant_user_id": "<BSUID>",                <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "recipient_participant_parent_user_id": "<PARENT_BSUID>",  <!-- ADDED -->

                <!-- Omitted for v24.0+ unless webhook is for a free entry point conversation -->
                "conversation": {
                  "id": "<CONVERSATION_ID>",
                  "expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP>",
                  "origin": {
                    "type": "<CONVERSATION_CATEGORY>"
                  }
                },

                "pricing": {
                  "billable": <IS_BILLABLE?>,
                  "pricing_model": "<PRICING_MODEL>",
                  "type": "<PRICING_TYPE>",
                  "category": "<PRICING_CATEGORY>"
                }
              },
              # Additional status objects would follow, if aggregated
              {
                ...
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
  • contacts — New array. Only included for delivered and read status messages. Will be omitted entirely for failed status messages webhooks.
    • name — New property. Value will be set to the WhatsApp user’s display name.
    • username — New property. Will be set to the WhatsApp user’s username if the user has adopted a username. Will be omitted for sent status messages webhooks, or if the user has not enabled the usernames feature.
    • wa_id — New property.
      • Will be omitted if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section.
      • Will be set to the user’s phone number, if you sent the message to the user’s phone number.
    • user_id — New property. Will be set to the WhatsApp user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • recipient_participant_id — Changed. Will be set to the user’s phone number, if the message was sent to their phone number. Otherwise, it will be omitted.
  • recipient_participant_user_id — Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
  • recipient_participant_parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.

group_participants_update webhooks

These changes apply to the group_participants_update webhook.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "groups": [
              {
                "timestamp": <WEBHOOK_TRIGGER_TIMESTAMP>,
                "group_id": "<GROUP_ID>",

                <!-- Only if business removes participant from group -->
                "type": "group_participants_remove",
                "request_id": "REQUEST_ID",
                "removed_participants": [
                  {
                    "input": "<USER_PHONE_NUMBER>",      <!-- CHANGED -->
                  }
                ],

                "initiated_by": "business"

                <!-- Only if user removes themself from group -->
                "type": "group_participants_remove",
                "request_id": "REQUEST_ID",
                "removed_participants": [
                  {
                    "wa_id": "<USER_PHONE_NUMBER>"       <!-- CHANGED -->
                    "user_id": "<BSUID>",                <!-- ADDED -->
                    "parent_user_id": "<PARENT_BSUID>",  <!-- ADDED -->
                    "username": "<USERNAME>"             <!-- ADDED -->
                  }
                ],

                "initiated_by": "participant"

                <!-- Only if user joins group via invite link -->
                "type": "group_participants_add",
                "reason": "invite_link",
                "added_participants": [
                  {
                    "wa_id": "<USER_PHONE_NUMBER>"       <!-- CHANGED -->
                    "user_id": "<BSUID>",                <!-- ADDED -->
                    "parent_user_id": "<PARENT_BSUID>",  <!-- ADDED -->
                    "username": "<USERNAME>"             <!-- ADDED -->
                  }
                ]

                <!-- Only if join request created -->
                "type": "group_join_request_created",
                "join_request_id": "<JOIN_REQUEST_ID>",
                "wa_id": "<USER_PHONE_NUMBER>",          <!-- CHANGED -->
                "user_id": "<BSUID>",                    <!-- ADDED -->
                "parent_user_id": "<PARENT_BSUID>",      <!-- ADDED -->
                "username": "<USERNAME>"                 <!-- ADDED -->

                <!-- Only if join request revoked -->
                "type": "group_join_request_revoked",
                "join_request_id": "<JOIN_REQUEST_ID>",
                "wa_id": "<USER_PHONE_NUMBER>"           <!-- CHANGED -->
                "user_id": "<BSUID>",                    <!-- ADDED -->
                "parent_user_id": "<PARENT_BSUID>",      <!-- ADDED -->
                "username": "<USERNAME>"                 <!-- ADDED -->
              }
            ]
          },
          "field": "group_participants_update"
        }
      ]
    }
  ]
}
  • input — New value (BSUID or parent BSUID).
    • Will be set to the user’s phone number if you removed the user from the group using their phone number.
    • Will be set to the user’s BSUID or parent BSUID if you removed the user from the group using their BSUID or parent BSUID.
  • wa_id — New behavior (can be omitted).
    • Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
  • user_id — New property. Will be set to the user’s BSUID.
  • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted.

Block Users API

Block or unblock user requests

These changes apply to the POST and DELETE Block Users requests. This example is for a block user request syntax, but the changes also apply to unblock requests.
curl 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/block_users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKENS>' \
-d '
{
  "messaging_product": "whatsapp",
  "block_users": [
    {
      "user": "<USER_PHONE_NUMBER>"
    },
    {
      "user_id": "<BSUID>"   <!-- ADDED -->
    }
  ]
}'
You can include both user (phone number) and user_id (BSUID or parent BSUID) in your request. If you do, user (phone number) will take precedence. If you prefer, you can also use one or the other:
To block or unblock a user using only their phone number:
  • Set user to the user’s phone number
  • Omit the user_id object
To block or unblock a user using only their BSUID or parent BSUID:
  • Set user_id to the user’s BSUID or parent BSUID
  • Omit the user object

Block or unblock request responses

These changes will apply to the POST and DELETE Block Users request responses.
{
  "messaging_product": "whatsapp",
  "block_users": {
    "added_users": [
      {
        "input": "<USER_PHONE_NUMBER>",  <!-- CHANGED -->
        "wa_id": "<USER_PHONE_NUMBER>",  <!-- CHANGED -->
        "user_id": "<BSUID>"             <!-- ADDED -->
      }
    ]
  }
}
  • input — New value (BSUID or parent BSUID).
    • Will be set to the user’s BSUID or parent BSUID if you used the user’s BSUID or parent BSUID to block or unblock the user.
    • Will be set to the user’s phone number if you used the user’s phone number to block or unblock the user.
  • wa_id — New behavior (can be omitted).
    • Will be omitted if you used the user’s BSUID or parent BSUID to block or unblock the user.
    • Will be set to the user’s phone number if you used their phone number to block or unblock the user.
  • user_id — New property.
    • Will be set to the user’s BSUID or parent BSUID if you used the user’s BSUID or parent BSUID to block or unlock the user.
    • Will be omitted if you used the user’s phone number to block or unblock the user.

Get blocked users

These changes apply to GET Block Users responses.
Response syntax:
{
  "data": [
    {
      "messaging_product": "whatsapp",
      "wa_id": "<USER_PHONE_NUMBER>",    <!-- CHANGED -->
      "user_id": "<BSUID>",             <!-- ADDED -->

      <!-- Only included if parent BSUIDs enabled -->
      "parent_user_id": "<PARENT_BSUID>" <!-- ADDED -->
    }
  ],
  "paging": {
    "cursors": {
      "after": "<AFTER_CURSOR>",
      "before": "<BEFORE_CURSOR>"
    }
  }
}
  • wa_id — Will be set to the user’s phone number if available. Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
  • user_id — New property. Will be set to the user’s BSUID.
  • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.

Calling API

Businesses-initiated call requests

The changes apply to business-initiated Calling API requests.
'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/calls' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
  "messaging_product": "whatsapp",
  "to": "<USER_PHONE_NUMBER>",    <!-- CHANGED -->
  "recipient": "<BSUID>",         <!-- ADDED -->
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<RFC_4566_SDP>"
  }
}'
You can include both to (phone number) and recipient (BSUID or parent BSUID) in your request. If you do, to (phone number) will take precedence. If you prefer, you can also use one or the other:
To call a user using only their phone number:
  • set to to the user’s phone number
  • omit the recipient property
To call a user using only their BSUID or parent BSUID:
  • set recipient to the user’s BSUID or parent BSUID
  • omit the to property

Get call permissions

The changes apply to get call permissions requests. There are no changes to responses.
Get call permissions using a user’s phone number:
curl 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/call_permissions?user_wa_id=<USER_PHONE_NUMBER>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
  • user_wa_id — Set to the user’s phone number.
Get call permissions using a user’s BSUID or parent BSUID:
curl 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/call_permissions?recipient=<BSUID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
  • recipient — Set to the user’s BSUID or parent BSUID.

Send call permission request

See send message requests.

Call permission request webhooks

These changes will apply to incoming call permission reply interactive messages webhooks.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_PROFILE_NAME>",

                  <!-- Only included if user has enabled the usernames feature -->
                  "username": "<USERNAME>"                <!-- ADDED -->

                },
                "wa_id": "<WHATSAPP_USER_ID>",            <!-- CHANGED -->
                "user_id": "<BSUID>",                     <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"        <!-- ADDED -->

              }
            ],
            "messages": [
              {
                "context": {
                  "from": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                  "id": "<CONTEXTUAL_WHATSAPP_MESSAGE_ID>"
                },
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",   <!-- CHANGED -->
                "from_user_id": "<BSUID>",                <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "from_parent_user_id": "<PARENT_BSUID>"   <!-- ADDED -->

                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "interactive",
                "interactive": {
                  "type":  "call_permission_reply",
                  "call_permission_reply": {
                    "response": accept,
                    "expiration_timestamp": "<EXPIRATION_TIMTESTAMP>",
                    "response_source": "<RESPONSE_SOURCE>"
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
  • contacts
    • profile
      • username — New property. Will be set to the user’s username if the user has adopted a username. Will be omitted if the user is not using a username.
    • wa_id — New property.
      • Will be omitted if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section.
      • Will be set to the user’s phone number if the user has not adopted a username.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • messages
    • from — New behavior (can be omitted).
      • Will be set to the user’s phone number if the user has not enabled the user name feature.
      • Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.
    • from_user_id — New property. Will be set to the user’s BSUID.

Business-initiated connected calls webhooks

These changes apply to business-initiated connected calls webhooks.
{
  "entry": [
    {
      "changes": [
        {
          "field": "calls",
          "value": {
            "contacts": [                                  <!-- ADDED -->
              {
                "profile": {
                  <!-- Only included if user has enabled the usernames feature -->
                  "username": "<USERNAME>"                 <!-- ADDED -->
                },
                "wa_id": "<USER_PHONE_NUMBER>",            <!-- ADDED -->
                "user_id": "<BSUID>",                      <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"         <!-- ADDED -->
              }
            ],
            "calls": [
              {
                "biz_opaque_callback_data": "<DATA>",
                "session": {
                  "sdp_type": "answer",
                  "sdp": "<SDP>"
                },
                "from": "<BUSINESS_PHONE_NUMBER>",
                "id": "<WHATSAPP_CALL_ID>",
                "to": "<USER_PHONE_NUMBER>",               <!-- CHANGED -->
                "to_user_id": "<BSUID>",                   <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "to_parent_user_id": "<PARENT_BSUID>",     <!-- ADDED -->

                "event": "connect",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "direction": "BUSINESS_INITIATED"
              }
            ],
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>"
            },
            "messaging_product": "whatsapp"
          }
        }
      ],
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>"
    }
  ],
  "object": "whatsapp_business_account"
}
  • contacts — New array.
    • profile
      • username — New property.
        • Will be set to the WhatsApp user’s username if the user has adopted a username.
        • Will be omitted for sent status messages webhooks, or if the user is not using a username.
    • wa_id — New property.
      • Will be omitted if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section.
      • Will be set to the user’s phone number, if you sent the message to the user’s phone number.
    • user_id — New property. Will be set to the WhatsApp user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • calls
    • to — New behavior (can be omitted). Will be set to the user’s phone number if the user has adopted a username and we are able to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be omitted.
    • to_user_id — New property. Will be set to the user’s BSUID.
    • to_parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, the property will be omitted entirely.

User-initiated connected calls webhooks

These changes will apply to user-initiated connected calls webhooks.
{
  "entry": [
    {
      "changes": [
        {
          "field": "calls",
          "value": {
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>"
            },
            "calls": [
              {
                "session": {
                  "sdp_type": "offer",
                  "sdp": "<SDP>"
                },
                "from": "<USER_PHONE_NUMBER>",             <!-- CHANGED -->
                "from_user_id": "<BSUID>",                 <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "from_parent_user_id": "<PARENT_BSUID>",   <!-- ADDED -->

                "id": "<WHATSAPP_CALL_ID>",
                "to": "<BUSINESS_PHONE_NUMBER>",
                "event": "connect",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "direction": "USER_INITIATED"
              }
            ],
            "contacts": [
              {
                "wa_id": "<USER_PHONE_NUMBER>",            <!-- CHANGED -->
                "profile": {
                  "name": "<USER_DISPLAY_NAME>",           <!-- ADDED -->

                  <!-- Only included if user has enabled usernames feature -->
                  "username": "<USERNAME>"                 <!-- ADDED -->

                },
                "user_id": "<BSUID>"                       <!-- ADDED -->,

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"         <!-- ADDED -->
              }
            ],
            "messaging_product": "whatsapp"
          }
        }
      ],
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>"
    }
  ],
  "object": "whatsapp_business_account"
}
  • calls
    • from — New behavior (can be omitted). Will be omitted if the username has enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • from_user_id — New property. Will be set to the user’s BSUID.
    • from_parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • contacts
    • wa_id — New behavior (can be omitted).
      • Will be omitted if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • name — New property. Will be set to the user’s profile name.
    • username — New property. If the user has adopted a username, it will be set to the user’s username. Otherwise, it will be omitted.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.

Business-initiated terminated calls webhooks

These changes apply to business-initiated terminated calls webhooks.
{
  "entry": [
    {
      "changes": [
        {
          "field": "calls",
          "value": {
            "calls": [
              {
                "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA>",
                "from": "<BUSINESS_PHONE_NUMBER>",
                "id": "<WHATSAPP_CALL_ID>",
                "to": "<USER_PHONE_NUMBER>",              <!-- CHANGED -->
                "to_user_id": "<BSUID>",                  <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "to_parent_user_id": "<PARENT_BSUID>",    <!-- ADDED -->

                "event": "terminate",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "direction": "BUSINESS_INITIATED",
                "status": "COMPLETED"
              }
            ],
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>"
            },
            "contacts": [                                 <!-- ADDED -->
              {
                "profile": {
                <!-- Only included if user has enabled the usernames feature -->
                "username": "<USERNAME>"                 <!-- ADDED -->
                },
                "wa_id": "<USER_PHONE_NUMBER>",           <!-- ADDED -->
                "user_id": "<BSUID>",                     <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"        <!-- ADDED -->
              }
            ],
            "messaging_product": "whatsapp"
          }
        }
      ],
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>"
    }
  ],
  "object": "whatsapp_business_account"
}
  • calls
    • to — New behavior (can be omitted). Will be set to the user’s phone number if the user has adopted a username and we are able to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be omitted.
    • to_user_id — New property. This will be set to the user’s BSUID.
    • to_parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • contacts — New array.
    • profile
      • username — New property. If the user has adopted a username, it will be set to the user’s username. Otherwise, it will be omitted.
    • wa_id — New property. Will be set to the user’s phone number, if the terminated call was made to the user’s phone number. Otherwise, it will be omitted.
    • user_id — New property. This will be set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.

User-initiated terminated calls webhooks

These changes will apply to user-initiated terminated calls webhooks.
{
  "entry": [
    {
      "changes": [
        {
          "field": "calls",
          "value": {
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>"
            },
            "calls": [
              {
                "duration": <CALL_DURATION>,
                "start_time": "<CALL_START_TIMESTAMP>",
                "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA>",
                "end_time": "<CALL_END_TIMESTAMP>",
                "from": "<USER_PHONE_NUMBER>",             <!-- CHANGED -->
                "from_user_id": "<BSUID>",                 <!-- ADDED -->

                <!-- Only included if you have enabled parent BSUIDs -->
                "from_parent_user_id": "<PARENT_BSUID>",   <!-- ADDED -->

                "id": "<WHATSAPP_CALL_ID>",
                "to": "<BUSINESS_PHONE_NUMBER>",
                "event": "terminate",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "direction": "USER_INITIATED",
                "status": "COMPLETED"
              }
            ],
            "contacts": [
              {
                "profile": {
                  "name": "<USER_PROFILE_NAME>"            <!-- ADDED -->

                  <!-- Only included if user has enabled the usernames feature -->
                  "username": "<USERNAME>"                 <!-- ADDED -->
                },
                "wa_id": "<USER_PHONE_NUMBER>",            <!-- CHANGED -->
                "user_id": "<BSUID>",                      <!-- ADDED -->

                <!-- Only included if you have enabled parent BSUIDs -->
                "parent_user_id": "<PARENT_BSUID>"         <!-- ADDED -->
              }
            ],
            "messaging_product": "whatsapp"
          }
        }
      ],
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>"
    }
  ],
  "object": "whatsapp_business_account"
}
  • calls
    • from — New behavior (can be omitted). Will be omitted if the user has enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • from_user_id — New property. Will be set to the user’s BSUID.
    • from_parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • contacts
    • profile
      • name — New property. This will be set to the user’s profile name
      • username — New property. If the user has adopted a username, it will be set to the user’s username. Otherwise, it will be omitted.
    • wa_id — Will be omitted if the user has enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • user_id — New property. This will be set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.

Business-initiated calls status webhooks

These changes will apply to business-initiated calls status webhooks.
{
  "entry": [
    {
      "changes": [
        {
          "field": "calls",
          "value": {
            "statuses": [
              {
                "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA>",
                "id": "<WHATSAPP_CALL_ID>",
                "type": "call",
                "status": "<STATUS>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "recipient_id": "<USER_PHONE_NUMBER>",         <!-- CHANGED -->
                "recipient_user_id": "<BSUID>",                <!-- ADDED -->

                <!-- Only included if you have enabled parent BSUIDs -->
                "recipient_parent_user_id": "<PARENT_BSUID>"   <!-- ADDED -->
              }
            ],
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>"
            },
            "contacts": [                                      <!-- ADDED -->
              {
                "profile": {
                  <!-- Only included if user has enabled the usernames feature -->
                  "username": "<USERNAME>"                     <!-- ADDED -->
                },
                "wa_id": "<USER_PHONE_NUMBER>",                <!-- ADDED -->
                "user_id": "<BSUID>",                          <!-- ADDED -->

                <!-- Only included if you have enabled parent BSUIDs -->
                "parent_user_id": "<PARENT_BSUID>"             <!-- ADDED -->
              }
            ],
            "messaging_product": "whatsapp"
          }
        }
      ],
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>"
    }
  ],
  "object": "whatsapp_business_account"
}
  • statuses
    • recipient_id — New behavior (can be omitted).
      • Will be omitted if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • recipient_user_id — New property. This will be set to the user’s BSUID.
    • recipient_parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.
  • contacts — New array.
    • profile
      • username — New property. Will be set to the user’s username, if the user has enabled the usernames feature. Otherwise, it will be omitted.
    • wa_id — New property. Will be set to the user’s phone number if the call was made to the user’s phone number. Otherwise, it will be omitted.
    • user_id — New property. This will be set to the user’s BSUID.
    • parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted.

SIP invites for business-initiated calls

These changes apply to business-initiated calls made using SIP.
<!-- BEGIN CHANGE -->
INVITE sip:<BSUID_OR_PHONE_NUMBER>@wa.meta.vc;transport=tls SIP/2.0
<!-- END CHANGE -->

Record-Route: <sip:+159.65.244.171:5061;transport=tls;lr;ftag=Kc9QZg4496maQ;nat=yes>
Via: SIP/2.0/TLS 159.65.244.171:5061;received=2803:6081:798c:93f8:5f9b:bfe8:300:0;branch=z9hG4bK0da2.36614b8977461b486ceabc004c723476.0;i=617261
Via: SIP/2.0/TLS 137.184.87.1:35181;rport=56533;received=137.184.87.1;branch=z9hG4bKQNa6meey5Dj2g
Max-Forwards: 69
From: <sip:+17125550259@meta-voip.example.com>;tag=Kc9QZg4496maQ

<!-- BEGIN CHANGE -->
To: <sip:<BSUID_OR_PHONE_NUMBER>@wa.meta.vc>
<!-- END CHANGE -->

Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba
CSeq: 96743476 INVITE
Contact: <sip:mod_sofia@137.184.87.1:35181;transport=tls;swrad=137.184.87.1~56533~3>
User-Agent: SignalWire
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY
Supported: timer, path, replaces
Allow-Events: talk, hold, conference, refer
Session-Expires: 600;refresher=uac
Min-SE: 90
Content-Type: application/sdp
Content-Disposition: session
Content-Length: 2427
X-Relay-Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba
Remote-Party-ID: <sip:+17125550259@meta-voip.example.com>;party=calling;screen=yes;privacy=off
Content-Type: application/sdp
Content-Length:  2427

<!-- SDP omitted for brevity -->
  • <BSUID_OR_PHONE_NUMBER> — Will be the user’s BSUID or parent BSUID if the call was made to the user’s BSUID or parent BSUID, or the user’s phone number if sent to their phone number.

SIP invites for user-initiated calls

These changes apply to user-initiated calls made using SIP.
INVITE sip:+17015558857@meta-voip.example.com;transport=tls SIP/2.0
Via: SIP/2.0/TLS [2803:6080:e888:51aa:d4a4:c5e0:300:0]:33819;rport=33819;received=2803:6080:e888:51aa:d4a4:c5e0:300:0;branch=z9hG4bKPjNvs.IZBnUa1W4l8oHPpk3SUMmcx3MMcE;alias
Max-Forwards: 70

<!-- BEGIN CHANGE -->
From: "<BSUID_OR_PHONE_NUMBER>" <sip:<BSUID_OR_PHONE_NUMBER>@wa.meta.vc>;tag=bbf1ad6e-79bb-4d9c-8a2c-094168a10bea
<!-- END CHANGE -->

To: <sip:+17015558857@meta-voip.example.com>

<!-- BEGIN CHANGE -->
Contact: <sip:<BSUID_OR_PHONE_NUMBER>@wa.meta.vc;transport=tls;ob>;isfocus
<!-- END CHANGE -->

Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCAzODg1NTE5NEU1NTBEMTc1RTFFQUY5NjNCQ0FCRkEzRhwYCzE3MDE1NTU4ODU3FQIAAA==
CSeq: 2824 INVITE
Route: <sip:onevc-sip-proxy-dev.fbinfra.net:8191;transport=tls;lr>
X-FB-External-Domain: wa.meta.vc

<!-- BEGIN ADDITION -->
x-wa-meta-user-id: <BSUID>
x-wa_meta-parent-user-id: <PARENT_BSUID>
x-wa-meta-user-name: <USERNAME>
<!-- END ADDITION -->

Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS
User-Agent: Facebook SipGateway
Content-Type: application/sdp
Content-Length: 1028

<!-- SDP omitted for brevity -->
  • <BSUID> — Will be set to the user’s BSUID.
  • <BSUID_OR_PHONE_NUMBER> — Will be the user’s BSUID or parent BSUID if the call was made to the user’s BSUID or parent BSUID, or if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be the user’s phone number.
  • <PARENT_BSUID> — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
  • <USERNAME> — Will be the user’s username, if the user has enabled the usernames feature. Otherwise, it will be omitted.

SIP OK responses for business-initiated calls

SIP/2.0 200 OK
Via: SIP/2.0/TLS 54.172.60.1:5061;received=2803:6080:f934:8894:7eb5:24f9:300:0;branch=z9hG4bK1e5a.0da2ace9cc912d9e5f2595ca4acb9847.0
Via: SIP/2.0/UDP 172.25.10.217:5060;rport=5060;branch=z9hG4bK5cdada8c-cbf0-4369-b02d-cc97d3c36f2b_c3356d0b_54-457463274351249162
Record-Route: <sip:onevc-sip-proxy.fbinfra.net:8191;transport=tls;lr>
Record-Route: <sip:wa.meta.vc;transport=tls;lr>
Record-Route: <sip:54.172.60.1:5061;transport=tls;lr;r2=on>
Record-Route: <sip:54.172.60.1;lr;r2=on>
Call-ID: f304a1d2cafb8139c1f9ff93a7733586@0.0.0.0

<!-- BEGIN CHANGE -->
From: "<BSUID_OR_PHONE_NUMBER>" <sip:<BSUID_OR_PHONE_NUMBER>@meta-voip.example.com>;tag=28460006_c3356d0b_5cdada8c-cbf0-4369-b02d-cc97d3c36f2b
<!-- END CHANGE -->

To: <sip:12195550714@wa.meta.vc>;tag=0d185053-2615-46c7-8ff2-250bda494cf1
CSeq: 2 INVITE
Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS
Supported: timer
X-FB-External-Domain: wa.meta.vc

<!-- BEGIN CHANGE -->
<sip:<BSUID_OR_PHONE_NUMBER>@wa.meta.vc;transport=tls;ob;X-FB-Sip-Smc-Tier=collaboration.sip_gateway.sip.prod>;isfocus
<!-- END CHANGE -->

<!-- BEGIN ADDITION -->
x-wa-meta-user-id: <BSUID>
x-wa_meta-parent-user-id: <PARENT_BSUID>
x-wa-meta-user-name: <USERNAME>
<!-- END ADDITION -->

Content-Type: application/sdp
Content-Length:   645

<!-- SDP omitted for brevity -->
  • <BSUID> — Will be set to the user’s BSUID.
  • <BSUID_OR_PHONE_NUMBER> — Will be the user’s BSUID or parent BSUID if the call was made to the user’s BSUID or parent BSUID, or if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be the user’s phone number.
  • <PARENT_BSUID> — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
  • <USERNAME> — Will be set to the user’s username, if the user has enabled the usernames feature. Otherwise, it will be omitted.

SIP BYE responses for business- and user-initiated calls

BYE sip:+12195550714@103.30.244.182:5061;transport=tls SIP/2.0
Via: SIP/2.0/TLS [2803:6080:e800:6746::]:56843;rport;branch=z9hG4bKPj65946b3e6f68128d52b6a498a8fd00a5;alias
Record-Route: <sip:wa.meta.vc;transport=tls;lr>
Record-Route: <sip:onevc-sip-proxy.fbinfra.net:8191;transport=tls;lr>
Via: SIP/2.0/TLS [2803:6080:e800:6746:3347:2251:14a4:a00]:5061;branch=z9hG4bKPj65946b3e6f68128d52b6a498a8fd00a5
Via: SIP/2.0/TLS [2803:6080:e934:3f82:b543:8a4d:1414:a00]:52767;rport=52767;received=2803:6080:e934:3f82:b543:8a4d:1414:a00;branch=z9hG4bKPj-D8BXdIVMqAUT9MIJIp78LxKUZNnjYKF;alias
Max-Forwards: 69

<!-- BEGIN CHANGE -->
From: <sip:<BSUID_OR_PHONE_NUMBER>@wa.meta.vc>;tag=0fb8b5f1-2703-49f4-a454-46b1bcb9bfac
<!-- END CHANGE -->

To: <sip:+12195550714@dev.moxcal.com>;tag=2c21fad0-c581-4e54-a707-3bd52abfcc3f
Call-ID: 21e38222-6fcb-4631-8e7d-5b94cf849c90
CSeq: 31641 BYE

<!-- BEGIN ADDITION -->
x-wa-meta-user-id: <BSUID>
x-wa_meta-parent-user-id: <PARENT_BSUID>
x-wa-meta-user-name: <USERNAME>
<!-- END ADDITION -->

X-FB-External-Domain: wa.meta.vc
Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS
User-Agent: Facebook SipGateway
Content-Length:  0
  • <BSUID> — Will be set to the user’s BSUID.
  • <BSUID_OR_PHONE_NUMBER> — Will be the user’s BSUID or parent BSUID if the call was made to the user’s BSUID or parent BSUID, or if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be the user’s phone number.
  • <PARENT_BSUID> — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
  • <USERNAME> — Will be set to the user’s username, if the user has enabled the usernames feature. Otherwise, it will be omitted.

Coexistence

History webhooks

These changes will apply to history webhooks that describe an onboarded business customer’s WhatsApp Business app chat history.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<CUSTOMER_WABA_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<CUSTOMER_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<CUSTOMER_PHONE_NUMBER_ID>"
            },
            "history": [
              {
                "metadata": {
                  "phase": <PHASE>,
                  "chunk_order": <CHUNK_ORDER>,
                  "progress": <PROGRESS>
                },
                "threads": [
                  /* First chat history thread object */
                  {
                    "id": "<WHATSAPP_USER_PHONE_NUMBER>",           <!-- CHANGED -->
                    "context": {                                    <!-- ADDED -->
                      "wa_id": "<WHATSAPP_USER_PHONE_NUMBER>",      <!-- ADDED -->
                      "user_id": "<BSUID>",                         <!-- ADDED -->

                      <!-- Only included if parent BSUIDs enabled before sync request -->
                      "parent_user_id": "<PARENT_BSUID>",           <!-- ADDED -->

                      <!-- Only included if user has enabled usernames feature before sync request -->
                      "username": "<USERNAME>"                      <!-- ADDED -->

                    },
                    "messages": [
                      /* First message object in thread */
                      {
                        "from": "<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER>",  <!-- CHANGED -->
                        "from_user_id" : "<BSUID>",                 <!-- ADDED -->

                        <!-- Only included if parent BSUIDs enabled before sync request -->
                        "from_parent_user_id": "<PARENT_BSUID>",    <!-- ADDED -->

                        "to": "<WHATSAPP_USER_PHONE_NUMBER>",
                        "id": "<WHATSAPP_MESSAGE_ID>",
                        "timestamp": "<DEVICE_TIMESTAMP>,
                        "type": "<MESSAGE_TYPE>",
                        "<MESSAGE_TYPE>": {
                          <MESSAGE_CONTENTS>
                        },
                        "history_context": {
                          "status": "<MESSAGE_STATUS>"
                        }
                      },
                      /* Additional message objects in thread would follow, if any */
                    ]
                  },
                  /* Additional chat history thread objects would follow, if any */
                ]
              }
            ]
          },
          "field": "history"
        }
      ]
    }
  ]
}
  • id — New behavior (can be omitted). Will be omitted if, at the time of the history sync request, the user has already enabled usernames and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
  • context — New context object.
    • wa_id — New property.
      • Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
    • username — New property.
      • Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted.
  • messages
    • from — New behavior (can be omitted).
      • Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • from_user_id — New property. Will be set to the user’s BSUID.
    • from_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
These changes will apply to history webhooks that describe a media asset sent from a WhatsApp user to a business customer, or vice-versa.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<CUSTOMER_WABA_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<CUSTOMER_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<CUSTOMER_PHONE_NUMBER_ID>"
            },
            "contacts": [                                          <!-- ADDED -->
              {

                <!-- Profile only included if user has enabled the usernames feature -->
                "profile": {
                  "username": "<USERNAME>",                        <!-- ADDED -->
                },
                "wa_id": "<WHATSAPP_USER_PHONE_NUMBER>",           <!-- ADDED -->
                "user_id": "<BSUID>",                              <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"                        <!-- ADDED -->
              },
            ],

            <!-- Only for messages sent from a user to a business -->
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",            <!-- CHANGED -->
                "from_user_id": "<BSUID>",                         <!-- ADDED -->

                 <!-- Only included if parent BSUIDs enabled -->
                "from_parent_user_id": "<PARENT_BSUID>",           <!-- ADDED -->

                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<ORIGINAL_WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "<MEDIA_TYPE>",
                "<MEDIA_TYPE>": {
                  <MEDIA_METADATA>
                }
              }
            ],

            <!-- Only for messages sent from a business to a user -->
            "message_echoes": [
              {
                "from": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                "to": "<WHATSAPP_USER_PHONE_NUMBER>",              <!-- CHANGED -->
                "to_user_id": "<BSUID>",                           <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "to_parent_user_id": "<PARENT_BSUID>",             <!-- ADDED -->

                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "<MESSAGE_TYPE>",
                "<MESSAGE_TYPE>": {
                  <MESSAGE_CONTENTS>
                }
              }
            ]

          },
          "field": "history"
        }
      ]
    }
  ]
}
  • contacts — New object.
    • profile
      • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted.
    • wa_id — New property.
      • Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
  • messages
    • from — New behavior (can be omitted).
      • Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • from_user_id — New property. Will be set to the user’s BSUID.
    • from_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
  • message_echoes
    • to — New behavior (can be omitted).
      • Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • to_user_id — New property. Will be set to the user’s BSUID.
    • to_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.

smb_message_echoes webhooks

These changes will apply to smb_message_echoes webhooks.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [                                     <!-- ADDED -->
              {

                <!-- Only included if user has enabled the usernames feature -->
                "profile": {
                  "username": "<USERNAME>"                    <!-- ADDED -->
                },

                "wa_id": "<WHATSAPP_USER_PHONE_NUMBER>",      <!-- ADDED -->
                "user_id": "<BSUID>",                         <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "parent_user_id": "<PARENT_BSUID>"            <!-- ADDED -->
              }
            ],
            "message_echoes": [
              {
                "from": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                "to": "<WHATSAPP_USER_PHONE_NUMBER>",         <!-- CHANGED -->
                "to_user_id": "<BSUID>",                      <!-- ADDED -->

                <!-- Only included if parent BSUIDs enabled -->
                "to_parent_user_id": "<PARENT_BSUID>",        <!-- ADDED -->

                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "<MESSAGE_TYPE>",
                "<MESSAGE_TYPE>": {
                  <MESSAGE_CONTENTS>
                }
              }
            ]
          },
          "field": "smb_message_echoes"
        }
      ]
    }
  ]
}
  • contacts — New array.
    • profile
      • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted.
    • wa_id — New property. Will be omitted if, at the time when the business customer used the WhatsApp Business app to send the message to the user, the user had already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
  • message_echoes
    • to — New behavior (can be omitted). Will be omitted if, at the time when the business customer used the WhatsApp Business app to send the message to the user, the user had already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
    • to_user_id — New property. Will be set to the user’s BSUID.
    • to_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.

smb_app_state_sync webhooks

These changes will apply to smb_app_state_sync webhooks.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "state_sync": [
              {
                "type": "contact",
                "contact": {
                  "full_name": "<CONTACT_FULL_NAME>",
                  "first_name": "<CONTACT_FIRST_NAME>",
                  "phone_number": "<CONTACT_PHONE_NUMBER>",    <!-- CHANGED -->
                  "user_id": "<BSUID>",                        <!-- ADDED -->

                  <!-- Only included if parent BSUIDs enabled -->
                  "parent_user_id": "<PARENT_BSUID>",          <!-- ADDED -->

                  <!-- Only included if user has enabled the usernames feature -->
                  "username": "<USERNAME>"                     <!-- ADDED -->
                },
                "action": "<ACTION>",
                "metadata": {
                  "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>"
                }
              },
              <!-- Additional contacts would follow, if any -->
            ]
          },
          "field": "smb_app_state_sync"
        }
      ]
    }
  ]
}
  • phone_number — New behavior (can be omitted). Will be omitted if, at the time of the sync request, the user has already enabled usernames and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number.
  • user_id — New property. Will be set to the user’s BSUID.
  • parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted.
  • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted.

Revoke messages webhooks

These changes will apply to revoke messages webhooks.
{
 "object": "whatsapp_business_account",
 "entry": [
   {
     "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
     "changes": [
       {
         "value": {
           "messaging_product": "whatsapp",
           "metadata": {
             "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
             "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
           },
           "contacts": [
             {
               "profile": {
                 "name": "<WHATSAPP_USER_PROFILE_NAME>",

                 <!-- Only included if user has enabled the usernames feature -->
                 "username": "<USERNAME>"            <!-- ADDED -->
               },
               "wa_id": "<WHATSAPP_USER_ID>",
               "user_id": "<BSUID>",                 <!-- ADDED -->

               <!-- Only included if parent BSUIDs enabled -->
               "parent_user_id": "<PARENT_BSUID>"    <!-- ADDED -->
             }
           ],
           "messages": [
             {
               "from": "<WHATSAPP_USER_PHONE_NUMBER>",
               "id": "<WHATSAPP_MESSAGE_ID>",
               "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
               "type": "revoke",
               "revoke": {
                 "original_message_id": "<ORIGINAL_WHATSAPP_MESSAGE_ID>"
               }
             }
           ]
         },
         "field": "messages"
       }
     ]
   }
 ]
}
  • contacts
    • profile
      • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — Will be set to the user’s parent BSUID if you enabled parent BSUIDs. Otherwise, it will be omitted.

Edit messages webhooks

These changes will apply to edit messages webhooks.
{
 "object": "whatsapp_business_account",
 "entry": [
   {
     "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
     "changes": [
       {
         "value": {
           "messaging_product": "whatsapp",
           "metadata": {
             "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
             "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
           },
           "contacts": [
             {
               "profile": {
                 "name": "<WHATSAPP_USER_PROFILE_NAME>",

                 <!-- Only included if the user has enabled usernames -->
                 "username": "<USERNAME>"              <!-- ADDED -->
               },
               "wa_id": "<WHATSAPP_USER_ID>",          <!-- CHANGED -->
               "user_id": "<BSUID>",                   <!-- ADDED -->

               <!-- Only included if parent BSUIDs enabled -->
               "parent_user_id": "<PARENT_BSUID>"      <!-- ADDED -->
             }
           ],
           "messages": [
             {
               "from": "<WHATSAPP_USER_PHONE_NUMBER>",
               "id": "<WHATSAPP_MESSAGE_ID>",
               "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
               "type": "edit",
               "edit": {
                 "original_message_id": "<ORIGINAL_WHATSAPP_MESSAGE_ID>",
                 "message": {
                   "context": {
                     "id": "<CONTEXT_ID>"
                   },
                   "type": "image",
                   "image": {
                     "caption": "<MEDIA_ASSET_CAPTION>",
                     "mime_type": "<MEDIA_ASSET_MIME_TYPE>",
                     "sha256": "<MEDIA_ASSET_SHA256_HASH>",
                     "id": "<MEDIA_ASSET_ID>",
                     "url": "<MEDIA_ASSET_URL>"
                   }
                 }
               }
             }
           ]
         },
         "field": "messages"
       }
     ]
   }
 ]
}
  • contacts
    • profile
      • username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted.
    • wa_id — New property. Will be omitted if, at the time when WhatsApp user edits the message, the user has already enabled the usernames feature and the phone number cannot be included based on the conditions described in the Phone numbers section. Otherwise, it will be omitted.
    • user_id — New property. Will be set to the user’s BSUID.
    • parent_user_id — Will be set to the user’s parent BSUID if you enabled parent BSUIDs. Otherwise, it will be omitted.

Analytics

No changes.

Billing and invoicing

No changes.

FAQs

What do I need to do to support usernames?
BSUIDs and parent BSUIDs will begin appearing in webhooks payloads in March 2026, before usernames are made available to WhatsApp users. In order to process messages from users who enable the feature once it is available, you will need to support BSUIDs (and parent BSUIDs if you enable them). To do this, you must:
  • Update your webhook integrations to support BSUIDs (and parent BSUID, if using).
  • Build logic to support handling multiple identifiers (phone numbers from non-username adopters; BSUIDs from username adopters if phone number is not present in webhooks), and map relevant fields back to your CRM/database.
  • Update internal and external systems related to these integrations to be able to handle BSUIDs and join with previous identifiers; primarily CRM (either 3P or internal database) and any tools or workflows triggered off of CRM (e.g., triggered campaign messages, campaign management, measurement, billing, and so on).
  • If you still require customer phone numbers, update your messaging bots/journeys (if used) to request phone numbers, handle scenarios where users do not share phone numbers, and iterate on these new conversation journeys. See WhatsApp Business Solution Terms⁠ for general restrictions in AI use cases.
  • If you have multiple business portfolios with Meta, you may want to implement a solution to enable central CRM access across multiple portfolios, to minimize the operational overhead that comes with using and storing BSUIDs (and parent BSUIDs).
When will I receive a BSUID or parent BSUID vs. a phone number?
When a user adopts a username, they will have phone number privacy meaning their phone number will not be displayed in the app, and their phone number will not be included in webhooks. If the user’s phone number is not present (the wa_id property is missing), you can use their BSUID (or parent BSUID, if using), which will be included and assigned to a new user_id property (parent_user_id for parent BSUIDs).
If a user has not adopted usernames, you will receive both their phone number and their BSUID (and parent BSUID, if enabled).
Note that will continue to share the phone number if certain conditions are met. Per our Cloud API Terms of Service, however, phone numbers and related data are retained for a maximum of 30 days to support features like message redelivery. There may be situations where you receive messages from existing users outside of this 30 day window, which may look like a new user thread to you. Therefore, it is essential that you begin supporting BSUIDs as soon as possible, to minimize losing any conversation context.
Why do partners and directly-integrated businesses using the Cloud API, including directly integrated ads that click to WhatsApp advertisers, have to adopt BSUID?
Partners and businesses must adopt BSUID to continue processing incoming messages from WhatsApp username adopters. Once BSUID is adopted and user messages from username adopters are processed, message webhooks will no longer include phone numbers in some cases as part of the webhook such as wa_id, so anyone using the Cloud API must ensure all connected systems can handle BSUID. They will also be able to ask for a user’s phone number in-thread.
If I have not yet adopted BSUIDs and start to receive messages from username adopters which I cannot process, recourse is there?
If you have not yet adopted BSUID and are not able to process messages from username adopters, there will not be any recourse or corrective action that you can take.
For messages from new customers: the webhook will continue to be sent of an incoming message. Depending on the specifics of the implementation, this may impact your systems that are not equipped to handle incoming messages without user phone numbers, and BSUID assigned to the new user_id field. For messages from your existing customers: the phone number will continue to be included if the conditions described in the Phone numbers section are met.
Once you support BSUIDs, request phone numbers from users by implementing a phone number request button.
How do business usernames differ from display names? When will a user see a business username vs a display name?
Business usernames will provide an ability for the users to reach the business by the business’ username, meaning an end user can search for a business username using their exact username and reach out to the businesses. Since end users cannot search by display names, business usernames offer a clear advantage as a searchable and unique identifier for users to reliably find the correct business.
Business usernames must follow specific formatting rules on length and allowed characters, while display names have some more leeway in terms of formatting.
Business usernames are unique and are tied 1-1 to phone numbers, meaning @JaspersMarket would be tied to one phone number while @JaspersMarketCustomerSupport would be tied to another phone number. Display names are not tied 1-1 to phone numbers, meaning the display name Jasper’s Market can have 10 phone numbers under this display name.
When a business has both a username and display name, display name will be shown first (e.g., in Profile, Chat list, Messages, and so on.), for the businesses to build trust with the users and for users to recognize the business when business reaches out to the user.

Document changelog

April 9, 2026

  • Fixed status messages webhooks field description and second example: corrected parent_user_id to parent_recipient_user_id in the statuses block to match the recipient_id/recipient_user_id naming convention. The parent_user_id field in the contacts block is unchanged.
  • Added parent_recipient_user_id to the outbound message status webhooks quick reference table.

March 31, 2026

  • Updated BSUID webhook rollout date from March 31 to early April 2026.
  • Updated contact book limitations: Local Storage businesses now automatically have phone numbers extracted from shared vCards and stored in the contact book on Meta data centers.
  • Updated requesting phone numbers from users: removed the Local Storage exception that required manually sending a message; replaced with automatic vCard phone number extraction behavior.
  • Updated webhook testing instructions with corrected App Dashboard navigation path.
  • Added availability warning to the adopt or change a business username section.

March 23, 2026

  • Corrected send message response and send marketing message responseuser_id descriptions: when both a phone number and BSUID or parent BSUID are included in the request, the response will not include user_id, since the phone number takes precedence and the response is identical to a phone-number-only request. Updated the example response for the phone number and BSUID case accordingly.

March 18, 2026

February 18, 2026

February 6, 2026

  • Changed number of alphanumeric characters that compose BSUIDs from 256 to 128 alphanumeric characters.
  • Changed how to use a BSUID to send a message; BSUIDs must now be assigned to dedicated properties/fields in message send requests (instead of existing properties/fields supporting both BSUIDs and phone numbers).
  • Changed how country codes will appear in webhooks: they will be prefixed to user BSUIDs instead of assigned to a dedicated webhook property.
  • Added parent BSUID information, which can be used across linked business portfolios.
  • Added contact book information, which can automatically store user phone numbers and BSUIDs.
  • Added phone number request button information.
  • Changed syntax examples, payload examples, and descriptions for all webhooks that returned empty strings in cases where a user has enabled the usernames feature. Now, these properties will not be set to an empty string. Instead, they will be omitted (e.g, the wa_id property in incoming messages webhooks).
  • Changed how errors are returned when attempting to adopt or change a business username.
  • Changed response syntax for getting a business’s current username.
  • Removed ability to cancel pending business username requests.
  • Changed phone_number_username_update webhook to business_username_updates webhook.
Did you find this page helpful?
Thumbs up icon
Thumbs down icon