Usernames and business-scoped user IDs

WhatsApp is introducing usernames as an optional privacy feature for end users. When a user adopts a username, their phone number may no longer appear in your webhook payloads.

If you already have a user's phone number (for example collected through forms, email, prior conversations or any other means), you can continue sending outbound messages to that number as before. This change only affects inbound webhooks when a user who has adopted a username contacts you without a prior phone-based interaction. Authentication templates (one-tap, zero-tap, and copy code) are not affected and continue to require a phone number.

To ensure uninterrupted messaging, Meta is simultaneously rolling out business-scoped user IDs (BSUIDs). These are stable, anonymous identifiers that let you reach and recognize users even without their phone number.

These are two separate changes with two separate timelines:

The rollout starts with ten pilot countries in June 2026, followed by the rest of the world:

What is a BSUID

A business-scoped user ID (BSUID) is a unique, stable identifier for a WhatsApp user within your business portfolio.

• Format: ISO 3166 alpha-2 country code + period + up to 128 alphanumeric characters. Example: US.13491208655302741918. To distinguish a BSUID from a phone number, check whether the value starts with two letters followed by a period.
• Scope: Unique per business portfolio. The same user has a different BSUID with each business they interact with.
• Stability: Stays the same unless the user changes their phone number. In that case, Meta generates a new BSUID and sends a user_id_update webhook with the old and new values so you can update your records.
• Not the same as identity changes: Identity changes occur when a user reinstalls WhatsApp or changes devices while keeping the same phone number. A BSUID update occurs when a user changes their phone number entirely.
• Always present: From end of May 2026, every inbound webhook includes a BSUID in contact.userId, regardless of whether the user has a username.

BSUIDs start appearing in your webhooks automatically. No configuration is required on your side.

Parent BSUIDs

Most businesses do not need parent BSUIDs. They are available only to businesses that manage multiple linked portfolios and have submitted a request to Meta and received explicit approval. A parent BSUID works across all linked portfolios and appears in contact.parentUserId. It is useful when the same user interacts with multiple phone numbers you own and you want a single identifier across all of them.

If your business operates a single portfolio, this field does not apply.

What are usernames

Any WhatsApp user can set an optional username that appears in the app instead of their phone number when messaging businesses. Once a user adopts a username, their phone number may be hidden from businesses they have not interacted with recently.

Usernames are entirely optional. Users who do not adopt one are unaffected. Their phone number continues to appear in your webhooks exactly as before.

Business usernames

Businesses can also adopt a username. A business username maps to a single business phone number across all of WhatsApp. One phone number can have only one username at a time, and no two WhatsApp phone numbers (consumer or business) can share the same username.

Business usernames must follow these format rules:

• May only contain English letters (a-z), digits (0-9), period (.), and underscore (_) characters.
• Non-English characters (such as ñ, é, ü) do not work and cause the request to fail.
• Must be between 3 and 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 two consecutive periods.
• Must not start with www.
• Must not end with a domain (for example, .com, .org, .net, .edu, .gov).
• WhatsApp ignores case when comparing usernames, but not period and underscore characters. For example, myID and myid are the same username, but myid, my.id, and my_id are all distinct.

Before the username feature is fully available, you have the option to claim a username that WhatsApp has reserved for you through WhatsApp Manager, Meta Business Suite, or through the API. You can also adopt a different username that aligns with your branding. Approved usernames become active once the username feature is available in your region.

WhatsApp displays business profile information in chat windows in the following order (highest priority first):

1. Saved contact name
2. Verified business name or Official Business Account name
3. Username
4. Phone number

Your business phone numbers always appear in your business profile.

Phone number visibility

When a user's phone number is available, your webhook payloads include both the phone number and the BSUID. When the phone number is unavailable, you receive the BSUID only.

A user's phone number is included in your webhook payloads if any of the following is true:

• You messaged or called their phone number within the last 30 days.
• You received a message or call from their phone number within the last 30 days.
• The user is in your Contact Book (opens in a new tab).

If none of these apply and the user has adopted a username, you receive their BSUID instead of their phone number.

Two mechanisms determine whether a phone number is included:

• 30-day window (per business phone number): The 30-day lookback is 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 do not include the user's phone number unless that number has also interacted with the user within the last 30 days.
• Contact Book (opens in a new tab) (per business portfolio): Contact Book automatically stores phone number and BSUID pairs whenever any business phone number in your portfolio interacts with a user. It is on by default and requires no setup. Once a pair is stored, the phone number is always included in webhooks from all phone numbers in your portfolio, even if the user later adopts a username. Contact Book only captures interactions that occur after early April 2026. It does not store historical data.

If you lose a user's phone number after they adopt a username, it is not permanent. Any interaction from a specific business phone number (outbound campaign, inbound reply) restores visibility on that number's webhooks and adds the user to the Contact Book for portfolio-wide visibility. You can also request the phone number directly in conversation using the REQUEST_CONTACT_INFO button described in Request a phone number from username users.

To maximize phone number visibility, send outbound messages to your existing contact list regularly. Any outbound message to a phone number resets the 30-day window and populates the Contact Book, keeping phone numbers visible even after users adopt usernames.

API payload changes

All changes are additive until the username launch. No fields are removed from existing payloads before the global rollout.

Inbound message webhook (MO)

Infobip delivers this to your webhook URL when a user sends you a message.

Phone number available

{
  "results": [
    {
      "from": "441234567890",
      "to": "440987654321",
      "integrationType": "WHATSAPP",
      "receivedAt": "2026-03-30T12:00:00.000+0000",
      "messageId": "ABGGFlA5Fpa",
      "message": {
        "type": "TEXT",
        "text": "Hello, I need help with my order"
      },
      "contact": {
        "name": "John Smith",
        "phoneNumber": "441234567890",
        "userId": "US.1349120865530274191",
        "parentUserId": "US.ENT.9876543210987654321",
        "username": "john.smith"
      }
    }
  ]
}

Phone number unavailable

{
  "results": [
    {
      "from": "AR.13491208655302741918",
      "to": "440987654321",
      "integrationType": "WHATSAPP",
      "receivedAt": "2026-06-15T12:00:00.000+0000",
      "messageId": "ABGGFlA5Fpa",
      "message": {
        "type": "TEXT",
        "text": "Hello, I need help with my order"
      },
      "contact": {
        "name": "Jane Doe",
        "userId": "AR.13491208655302741918",
        "username": "jane.doe"
      }
    }
  ]
}

When a phone number is unavailable, from and contact.userId carry the same BSUID value. contact.userId is the more reliable field to read. It always carries the BSUID regardless of whether the phone is present. For a full list of fields across all API surfaces, see the summary table.

Outbound message request (MT)

Send to a phone number

POST /whatsapp/1/message/text
 
{
  "from": "440000000000",
  "to": "441234567890",
  "content": {
    "text": "Your order #1234 has been shipped!"
  }
}

Send to a BSUID

POST /whatsapp/1/message/text
 
{
  "from": "440000000000",
  "to": "US.1349120865530274191",
  "content": {
    "text": "Your order #1234 has been shipped!"
  }
}

The to field accepts either a phone number or a BSUID. The maximum field length is 150 characters. You do not need to make other changes to the request format.

Outbound campaigns sent to phone numbers work the same as before. You continue to send to phone numbers and receive phone numbers in the corresponding delivery report webhooks.

Delivery report webhook (DLR)

Infobip delivers this to your DLR webhook when a message status changes.

Example payload

{
  "results": [
    {
      "bulkId": "BULK-ID-123",
      "messageId": "2250be2d4219-3af1-78856-aabe-1362af1edfd2",
      "to": "441234567890",
      "sentAt": "2026-03-30T12:00:00.000+0000",
      "doneAt": "2026-03-30T12:00:02.000+0000",
      "messageCount": 1,
      "contact": {
        "name": "John Smith",
        "phoneNumber": "441234567890",
        "userId": "US.1349120865530274191",
        "parentUserId": "US.ENT.9876543210987654321",
        "username": "john.smith"
      },
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      }
    }
  ]
}

The contact object follows the same structure as in the inbound webhook. It is included for sent, delivered, and read status events only. It is not included in failed delivery reports. The identifiers included in the DLR depend on how you sent the original message:

• Sent to a phone number: The DLR includes both the phone number and the BSUID.
• Sent to a BSUID, phone number known: The DLR includes both the phone number and the BSUID.
• Sent to a BSUID, phone number unknown: The DLR includes the BSUID only.

Summary of all field changes

Request a phone number from username users

If a user has adopted a username and their phone number is unavailable to you, WhatsApp provides a way to request it directly in the conversation thread.

You can add a new button type, REQUEST_CONTACT_INFO, to utility and marketing templates. When the user taps it, they share their virtual contact card (including phone number) in the message thread, and WhatsApp triggers a contacts webhook containing the number.

The following shows a template creation payload with a REQUEST_CONTACT_INFO button. No parameters are required for the button itself, as WhatsApp sets the label and does not allow customization.

{
  "name": "order_share_contact",
  "language": "en",
  "category": "UTILITY",
  "structure": {
    "body": {
      "text": "Your order has been shipped! Share your contact info so we can reach you with delivery updates."
    },
    "buttons": [
      {
        "type": "REQUEST_CONTACT_INFO"
      }
    ]
  }
}

When the user taps the button, WhatsApp delivers a contacts webhook containing the user's phone number. Read the phone number from this webhook, store it in your CRM, and use it in subsequent outbound messages to maintain phone number visibility going forward.

For the full webhook payload structure, refer to the Inbound messages API reference (opens in a new tab).

Integration requirements

To support usernames and BSUIDs, update your integration as follows:

1. Parse webhooks for BSUIDs.
   • Do not assume from always contains a phone number. Read contact.userId for every inbound message.
2. Store the BSUID.
   • Add a userId field to your customer records and use it as the stable WhatsApp identifier alongside the phone number.
3. Handle user_id_update events.
   • When a user changes their phone number, Meta sends this event with the old and new User IDs. Update your records accordingly.
4. Send to BSUIDs when needed.
   • When replying to a username-only user, use their userId in the to field.
5. Account for authentication limitations.
   • One-tap, zero-tap, and copy code authentication templates require a phone number and cannot use a BSUID. Ensure users likely to need OTP have a phone number on file.

Rollout timeline

For additional details, refer to Meta's Business-scoped user IDs documentation (opens in a new tab).

Support

For API integration questions or to report abuse related to usernames or BSUIDs, contact Infobip support (opens in a new tab).