WhatsApp Usernames and Business-Scoped User IDs (BSUID) - CCE

Introduction:

To enhance user privacy, WhatsApp is introducing usernames, which allow individuals to interact with businesses without disclosing their personal phone numbers. To support this transition, Webex Connect has adopted the Business-Scoped User ID (BSUID) as a primary identifier.

Effective Date: Starting June 2026, Webex Connect will provide full support for WhatsApp Usernames and BSUIDs.

Understanding BSUID elements:

The BSUID is a unique, business-specific identifier generated by Meta for every user-business portfolio pairing.
Format: The BSUID follows a standardized structure:

• Prefix: User’s ISO 3166 alpha-2 two-letter country code.
• Separator: A period (.).
• Suffix: A unique string of up to 128 alphanumeric characters.
• Example: US.13491208655302741918
• Lifecycle: BSUIDs are generated automatically. If a user updates their phone number, Meta will issue a new BSUID for that specific business relationship.

Identifier Priority & Data Sharing

When a request contains both a Phone Number (WAID) and a BSUID, the system follows a specific hierarchy to determine which identifier to process:

• Priority Rule: The system will always prioritize the Phone Number (WAID) and omit the BSUID if both are present.
• WAID Continuity: Phone numbers are shared in Outbound Webhooks only if one of the following conditions is met:
  • Recent Interaction: You have messaged/called the user (or vice versa) within the last 30 days.
  • Contact Status: The user is saved in your contact book, or you are saved in theirs.

Summary Checklist for Developers

📘

BSUID Management

As this update is scheduled for June 2026, ensure your existing webhooks and data handling logic are prepared to parse the BSUID format alongside traditional WAIDs.

Webex Connect provides BSUID visibility across key areas, including Outbound Webhooks, Data Streams, Start Node, Receive Node, and Export Logs.

BSUID Support in the platform components:

Future Implementation Roadmap: WhatsApp BSUID & Username Integration

This implementation plan outlines the phased approach Webex Connect will take to support WhatsApp’s transition to usernames and Business-Scoped User IDs (BSUID). Our primary objective is to ensure zero service disruption while providing the necessary tools for clients to adapt to WhatsApp's new identity model.

Strategic Objective

To maintain backward compatibility, Webex Connect will implement an "Auto-Normalization" layer. This layer ensures that existing client workflows—which rely on the traditional Phone Number (WAID)— continue to function even as WhatsApp begins withholding phone numbers in favor of BSUIDs.

Inbound Normalization & Visibility

Goal: Ensure inbound messages are processed correctly regardless of the identifier provided by WhatsApp.

• Identifier Mapping (The "Fallback" Mechanism):
  • In scenarios where WhatsApp does not provide a WAID, Webex Connect will automatically populate the legacy WAID field with the BSUID value.
  • This prevents downstream systems (CRMs, Ticketing tools) from receiving empty identity fields.
• Explicit Data Exposure:
  • A new, dedicated BSUID field will be introduced in the API response.
  • Action for Clients: We recommend updated logic to begin capturing this field for future-proofing customer records.
• Source Transparency:
  • We will introduce Source Indicators. These metadata tags will explicitly signal whether the value in the identity field is a native WAID (Phone Number) or a compatibility-derived BSUID.

Outbound Compatibility

Goal: Allow clients to reach customers using whichever identifier they have on file.

• Parameter Flexibility:
  • The existing WAID parameter in outbound API calls will be updated to accept either a traditional phone number or a BSUID-formatted string.
• Intelligent Routing:
  • Webex Connect will inspect the format of the identifier. If a BSUID format is detected, the platform will automatically route the message to WhatsApp’s BSUID endpoint, requiring no logic changes from the client side.

Sessioning & Data Hierarchy

Goal: Establish a clear "Source of Truth" for active customer sessions.

To maintain data integrity, Webex Connect will apply the following Priority Rules for session management:

Client Impact & Action Plan

What is Contact Book?

The Contact Book is a Meta feature supported by the Webex Connect platform, introduced in early April 2026 to improve messaging thread continuity. It stores WhatsApp user contact information, specifically phone numbers and BSUIDs. This feature is provided and hosted by Meta, requiring no integration effort. The Contact Book is scoped at the business portfolio level, meaning any interaction between any business phone number within the portfolio and a user will add that user’s phone number and BSUID to the Contact Book. This stored data is used to populate Outbound Webhook payloads and API responses that include the user’s phone number or BSUID, regardless of whether the user has enabled the usernames feature. Only interactions occurring after the Contact Book launch trigger storage; prior interactions are not captured retroactively. Contact Book data is retained until the feature is disabled or the account is deactivated.
How to update Contact Book?

The Contact Book updates automatically when you send or receive a message to or from a customer’s phone number within your business portfolio. Additionally, if you use Local Storage and a customer shares their phone number via the share contact information button, Meta extracts and stores only the phone number from the shared contact card (vCard) in the Contact Book on Meta data centers. No other vCard data is retained beyond the standard data-at-rest period for local storage.
Phone Number (WAID) Continuity:

Phone numbers will only be shared if:

• You have messaged/called the customer within the last 30 days.
• The customer has messaged/called you within the last 30 days.
• The customer is in your contact book or you are in theirs.

You can disable the Contact Book feature anytime, through the Meta Business Suite under Business settings > Business info panel. Disabling the feature stops the storage of new customer information and deletes any existing stored data. If re-enabled later, the Contact Book will resume storing customer information, but previously stored data cannot be restored.

Understanding Customer Data Transitions:

As the Contact Book is launched and Usernames feature rollout is due for release in June, your ability to access customer phone numbers will evolve based on the timing of your interactions. Please review the scenarios below to understand how your customer data will be managed.

Scenario 1: Existing Customers (Customers who have interacted with you prior to April)

This scenario applies to customers with whom you have already established a communication history.

• Before April: Your business relies on the customer's phone number as the primary identifier.
• April – May: As we launch the Contact Book, these customers' phone numbers will be automatically saved to your Contact Book, ensuring uninterrupted access to their information (unless the customer has manually opted out of this feature in their settings).
• From June Onwards: Even if these customers adopt a username, their phone number will remain accessible to you because it was already secured in your Contact Book during the transition period.

Scenario 2: New Customers (Customers who have not interacted with you)

This scenario applies to customers who initiate contact with your business for the first time.

• Before April: No contact information is available, as no prior interaction has occurred.
• April – May: Since there is no existing interaction, these customers' phone numbers will not be added to your Contact Book.
• From June Onwards: With the launch of Usernames, privacy is prioritized. If a customer messages you using a username, their phone number will not be automatically shared. You will see their username as the primary identifier. If you require their phone number for your records, you can request it directly within the chat thread using the new "Click-to-Action" (CTA) button.

Limitations

• Contact Books are scoped to business portfolios independently. If you have linked portfolios, a customer’s phone number and BSUID must be recorded separately in each portfolio’s Contact Book; customer contact information is not shared or synchronized across linked portfolios.
• When using Local Storage, only the phone number is extracted and stored from a shared contact card (vCard); no other vCard data is retained beyond the standard data-at-rest period.