Use business-scoped user IDs

Why BSUIDs exist

WhatsApp is rolling out optional usernames in 2026. When a user adopts a username, WhatsApp can display the username instead of the user’s phone number and may omit the phone number from webhook payloads. Each user controls whether to adopt a username, so businesses cannot rely on phone numbers as the only way to identify customers. Meta therefore requires WhatsApp Business Platform businesses and partners, as well as click-to-WhatsApp advertisers, to support BSUIDs so they can continue processing messages from users who adopt usernames. To support this change, Meta began adding business-scoped user IDs (BSUIDs) to webhook payloads in early April 2026. A BSUID is a backend identifier for one WhatsApp user within one Meta business portfolio. Meta includes it in message webhooks whether or not the user has adopted a username, and it can be used to message the user when their phone number is unavailable. Usernames and BSUIDs have different lifecycles. A user can change their username without changing their phone number or BSUID. If the user changes their phone number, Meta generates a new BSUID. Store these identifiers separately and update their association when you receive a phone-number-change system event. A phone number can still appear when the business phone number has exchanged a message or call with the user in the previous 30 days, or when Meta’s contact book contains the user. Treat phone-number and username fields as conditional, and update parsers and identity storage to accept BSUIDs alongside any other identifiers that are present. This guide covers BSUID identity rules, message and call requests, Meta’s contact book, and the webhook fields your integration needs to store. WhatsApp user username example

Understand the identifiers

Identifier	Scope	Example	When to use it
Phone number	A WhatsApp account	`+16315551111`	Use it when the phone number is available and the operation requires one.
BSUID	One Meta business portfolio and one WhatsApp user	`US.13491208655302741918`	Use it from any business phone number in the same portfolio.
Parent BSUID	A set of linked Meta business portfolios and one WhatsApp user	`US.ENT.11815799212886844830`	Use it only after Meta enables parent BSUIDs for the linked portfolios.

Meta generates regular BSUIDs automatically. Each BSUID starts with the user’s ISO 3166 alpha-2 two-letter country code, followed by a period and up to 128 alphanumeric characters. Preserve the complete value. Do not remove or change the country prefix, period, or identifier characters. BSUIDs have these lifecycle rules:

A BSUID is unique to one business portfolio and user pair.
A user’s BSUID changes when the user changes their phone number.
A parent BSUID works across the linked portfolios for which Meta enabled it.
A business phone number cannot use a regular BSUID scoped to another portfolio.

One-tap, zero-tap, and copy-code authentication templates require a phone number. Do not send these template types with only a BSUID.

To link portfolios and use parent BSUIDs, ask your Meta point of contact to check your eligibility. You can continue using regular BSUIDs within their original portfolios after Meta enables parent BSUIDs. Business-scoped user ID example

Before you begin

Store your YCloud API key in YCLOUD_API_KEY.
Use a WhatsApp business phone number owned by the same portfolio as the regular BSUID.
Subscribe your webhook endpoint to the WhatsApp events your integration uses.
Treat every new BSUID, parent BSUID, phone number, and username field as optional when deserializing webhooks.
Store the regular BSUID and parent BSUID independently when both are present.

Send a message with a BSUID

Both WhatsApp message endpoints accept recipient:

Endpoint	Behavior
`POST /whatsapp/messages/sendDirectly`	Submits the message synchronously to the WhatsApp Business API.
`POST /whatsapp/messages`	Queues the message for asynchronous submission.

Set recipient to either a regular BSUID or a parent BSUID. Omit to when you want YCloud to address the user by BSUID.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hello from YCloud!"
    }
  }'

Use the same request body with POST /whatsapp/messages to enqueue the message.

Input	Result
Only `to`	YCloud sends to the phone number.
Only `recipient`	YCloud sends to the BSUID or parent BSUID.
Both `to` and `recipient`	YCloud uses `to` and ignores `recipient`.
Neither field	YCloud rejects the request.

Request a user’s phone number

Use a request-contact-info message when your workflow needs a phone number that was not included in a webhook. The user decides whether to share it.

Use a template button

Add a REQUEST_CONTACT_INFO button to a utility or marketing template. The button text is fixed as Share Contact Info, and the button does not accept send-time parameters.

{
  "type": "buttons",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

Create and approve the template before sending it. See Request phone number template for a complete template request.

Use an interactive message

Send an interactive request_contact_info message when you do not need a template:

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "interactive",
    "interactive": {
      "type": "request_contact_info",
      "body": {
        "text": "Please share your phone number."
      },
      "action": {
        "name": "request_contact_info"
      }
    }
  }'

Handle the contact response

When the user shares contact information, YCloud sends a whatsapp.inbound_message.received event whose message type is contacts. For a response to your request, contacts[].origin is contact_request.

{
  "type": "whatsapp.inbound_message.received",
  "whatsappInboundMessage": {
    "fromUserId": "US.13491208655302741918",
    "type": "contacts",
    "contacts": [
      {
        "origin": "contact_request",
        "phones": [
          {
            "phone": "+16315551111",
            "wa_id": "16315551111"
          }
        ]
      }
    ]
  }
}

Validate the event signature, acknowledge it with a 2xx response, and process the phone number asynchronously. A contact shared directly from WhatsApp can also include a vCard. Request contact information button

Understand Meta’s contact book

Meta’s contact book stores the association between a user’s phone number and BSUID. With the feature enabled, sending or receiving a message or call using the user’s phone number records both identifiers. Meta can then include that association in webhooks even after the user adopts a username. Contact books belong to individual business portfolios. Linked portfolios do not share or synchronize their entries: record the association independently in each portfolio. Meta retains entries until you disable the feature or deactivate your account. You can disable it in Meta Business Suite > Business settings > Business info. Disabling the feature deletes the stored entries and stops recording new ones. Re-enabling it starts collecting new entries; it does not restore the deleted data. Meta contact book settings

Contact requests and Local Storage

When a user shares their phone number through a request-contact-info button, Meta adds the phone number to the contact book if the feature is enabled. For businesses using Local Storage, Meta extracts the phone number from the shared vCard and stores it in the contact book on Meta data centers. Other vCard data is not retained beyond the standard retention period. Meta removed the earlier requirement to send a separate message to capture this association. See the official BSUID documentation for the current Local Storage behavior.

Delete a Meta contact book entry

Delete a Meta contact book entry for a regular BSUID through one WhatsApp business phone number with: DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}

curl --request DELETE \
  "https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/%2B16315551111/contactBook/US.13491208655302741918" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Accept: application/json"

Use a standard BSUID for this operation. Parent BSUIDs containing .ENT. are not supported. URL-encode the leading + in the phone number as %2B when you construct the path manually. An HTTP 200 response always contains success: true. A deleted value of true means Meta deleted a matching entry. A value of false means Meta processed the request but found no matching entry. Deleting the entry does not delete YCloud contacts, messages, or BSUID business records. After deletion, webhook events for business phone numbers in the same Meta business portfolio no longer include the user’s phone number and BSUID together. Meta’s 30-day cache can still supply both identifiers, and a later interaction can create the contact book entry again.

Start a call with a BSUID

POST /whatsapp/calls/connect also accepts recipient. The same target rules apply: provide to or recipient, and to takes precedence when both are present.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/calls/connect \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "sdpType": "offer",
    "sdp": "SDP_OFFER"
  }'

For the complete calling lifecycle, see Manage WhatsApp calls.

Process BSUID webhook fields

The following fields are additions to existing event payloads. Keep the event’s top-level object when defining your data model.

Event	Optional fields to store
`whatsapp.message.updated`	`whatsappMessage.recipientUserId`, `whatsappMessage.parentRecipientUserId`, `whatsappMessage.customerProfile.name`, `whatsappMessage.customerProfile.username`
`whatsapp.inbound_message.received`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`
`whatsapp.user.preferences`	`whatsappUserPreference.userId`, `whatsappUserPreference.parentUserId`
`whatsapp.call.connect`	`callingConnect.toUserId`, `callingConnect.toParentUserId`, `callingConnect.fromUserId`, `callingConnect.fromParentUserId`
`whatsapp.call.terminate`	`callingTerminate.toUserId`, `callingTerminate.toParentUserId`, `callingTerminate.fromUserId`, `callingTerminate.fromParentUserId`
`whatsapp.call.status.updated`	`callingStatusUpdated.recipientUserId`, `callingStatusUpdated.parentRecipientUserId`
`whatsapp.group.participants_update`	`whatsappGroup.recipientUserId`, `whatsappGroup.parentRecipientUserId`, `whatsappGroup.customerProfile.username`, and the `recipientUserId` and `parentRecipientUserId` fields in `whatsappGroup.addedParticipants[]`, `whatsappGroup.removedParticipants[]`, and `whatsappGroup.failedParticipants[]`
`whatsapp.smb.history`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`, `whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`
`whatsapp.smb.app.state.sync`	`whatsappSmbAppStateSync.stateSync[].contact.userId`, `whatsappSmbAppStateSync.stateSync[].contact.parentUserId`, `whatsappSmbAppStateSync.stateSync[].contact.username`
`whatsapp.smb.message.echoes`	`whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`, `whatsappMessage.customerProfile.username`

Apply these omission rules:

A parent BSUID field is absent when parent BSUIDs are not enabled.
A sent message or call target field can be absent when you addressed the user by phone number.
customerProfile appears on sent, delivered, and read message updates, but not on failed updates.
customerProfile.username is absent when the user has not enabled usernames. It is also absent from sent status updates.
A phone number can be absent even when the corresponding BSUID is present.

Handle a user changing phone numbers

When an inbound message has type: system and system.type: user_changed_number, replace the old identity mapping with the new values. The system object’s BSUID field names remain in Meta’s snake_case format.

{
  "type": "system",
  "system": {
    "type": "user_changed_number",
    "wa_id": "16315552222",
    "user_id": "US.13491208655302741919",
    "parent_user_id": "US.ENT.11815799212886844831"
  }
}

Treat parent_user_id as optional. Keep the old and new values long enough to reconcile existing conversations and idempotently update your identity store.

Business usernames

A business username helps customers find your business in WhatsApp. It does not hide your business phone number. Each phone number can have one username, and a username cannot be shared by two WhatsApp phone numbers. A consumer username can change without changing the user’s BSUID. Keep the username as profile information rather than using it as your identity key. See Claim a business username for the 3–35 character format rules and the claiming and review process. Business username example

Reserved usernames

You can claim an eligible username reserved by Meta or choose another username for your brand. Use WhatsApp Manager, Meta Business Suite, or the username API. Approval does not by itself mean that a username is active for customers. If the reserved username belongs to your Facebook Page or Instagram account, link your business phone number to that Page or account before claiming it. You can link it while claiming the username in Meta Business Suite or WhatsApp Manager, or add the phone number to the Page or account. You need full control or basic partial access with manage_phone permission.

Chat window display priority

WhatsApp displays business identity in this order:

The name saved in the customer’s contacts.
The verified business name or Official Business Account name.
The business username.
The phone number.

Your business phone number remains visible in the business profile.

Migration checklist

Add every BSUID-related webhook field to your deserialization model as an optional field.
Store regular and parent BSUIDs separately from phone numbers and usernames.
Index customer identity by portfolio and BSUID. Do not treat a BSUID as a globally portable identifier.
Route message and call requests through either to or recipient, and test the to precedence rule.
Test username-only users, missing phone numbers, phone-number changes, missing parent BSUIDs, duplicate webhooks, and contact book re-creation.

Message status examples

Inspect sent, delivered, read, and failed message payloads.

Inbound message examples

Inspect contacts, system updates, and other inbound payloads.

Getting Started

Guides

Endpoints

Webhooks

Use business-scoped user IDs

Why BSUIDs exist

Understand the identifiers

Before you begin

Send a message with a BSUID

Request a user’s phone number

Use a template button

Use an interactive message

Handle the contact response

Understand Meta’s contact book

Contact requests and Local Storage

Delete a Meta contact book entry

Start a call with a BSUID

Process BSUID webhook fields

Handle a user changing phone numbers

Business usernames

Reserved usernames

Chat window display priority

Migration checklist

Message status examples

Inbound message examples

​Why BSUIDs exist

​Understand the identifiers

​Before you begin

​Send a message with a BSUID

​Request a user’s phone number

​Use a template button

​Use an interactive message

​Handle the contact response

​Understand Meta’s contact book

​Contact requests and Local Storage

​Delete a Meta contact book entry

​Start a call with a BSUID

​Process BSUID webhook fields

​Handle a user changing phone numbers

​Business usernames

​Reserved usernames

​Chat window display priority

​Migration checklist

Message status examples

Inbound message examples

Why BSUIDs exist

Understand the identifiers

Before you begin

Send a message with a BSUID

Request a user’s phone number

Use a template button

Use an interactive message

Handle the contact response

Understand Meta’s contact book

Contact requests and Local Storage

Delete a Meta contact book entry

Start a call with a BSUID

Process BSUID webhook fields

Handle a user changing phone numbers

Business usernames

Reserved usernames

Chat window display priority

Migration checklist