Disclaimer: Please note that all timelines and geographic rollout details regarding the launch of WhatsApp Usernames and BSUIDs are managed exclusively by Meta. The dates provided below are based on Meta’s current roadmap and are subject to change at their discretion. LivePerson will deploy its changes on 31 Aug 2026.
As Meta continues to prioritize consumer privacy, WhatsApp is moving toward a Username-first model. Later in 2026, WhatsApp users will have the option to set a username and communicate with businesses without sharing their personal phone numbers.
To support this transition, Meta is introducing the Business-scoped User ID (BSUID), a unique identifier tied to the relationship between a specific user and your brand. LivePerson is committed to ensuring this shift is seamless for your agents, your automation, and your customer history.
Meta’s introduction of BSUIDs represents a breaking protocol change. First-time consumers who have adopted a WhatsApp username will not be able to successfully message or interact with your brand unless the LivePerson feature updates and architectural changes described in this document are fully implemented.
LivePerson Continuity Plan
We understand that maintaining a continuous conversation history is critical. To protect your data, LivePerson is implementing a two-phase strategy:
- Phase 1 — Mapping (April – July 2026): Our systems will run a background "Registry" to link BSUIDs to existing phone numbers for active users. This happens silently and requires no action from you.
- Phase 2 — The Switch (August 31, 2026): We will officially adopt the BSUID as the primary identifier. To preserve history, our system will perform a "Mapping Fallback": if a returning user was captured in our Phase 1 Registry, we will keep them on their phone-based ConsumerID to ensure their chat history remains connected.
If a returning user was last active before our mapping window began in April 2026, we will not have a link on file. In these cases, their next message will start a "fresh" thread under their new BSUID without historical continuity. However, no data is lost in this process; all historical transcripts remain fully searchable and accessible in the Conversational Cloud under the user's original phone-based ID.
Mapped vs. Unmapped Users Quick Reference
Feature | Mapped User | Unmapped / New User |
|---|
Condition | Interacted during Apr–Jul 2026 mapping window | Last active before April 2026, or is a brand-new user |
consumerID
| Stays phone-based | Becomes BSUID-based |
History | Continuous in the existing thread | Starts a new thread (prior history is not auto-stitched) |
Phone Number | Known and visible | Hidden unless shared/recovered via interactive tools |
Technical Specifications:
Your stores, CRM routing, and database queries must be configured to accept the full BSUID string.
- Legacy Identifier Format:
whatsapp_<account_id>_<phone> - New Identifier Format:
whatsapp_<account_id>_<BSUID>
A BSUID is composed of an ISO 3166 two-letter country code prefix, a period, and up to 128 alphanumeric characters (e.g., US.13491208655302741918). This prefix should also be used as your primary method for country/region detection.
To provide a clear path for your technical teams, we have consolidated the structural changes to identifiers and Shared Data Entries (SDEs) below. Post launch, the following logic will apply:
Data Point | Field/SDE | Update Details |
|---|
Primary Identifier | consumerID
| Remains as the phone-based ID for all users in the Mapping Registry. Changes from a phone number to the BSUID format for new or unmapped users: whatsapp_<account_id>_<BSUID>. This string can be up to 149 characters. |
WhatsApp Username | accountName
| If a user has set a username, it will be captured here (e.g., @Alex_Smith ). |
Phone Number | personalInfo/phonenumber
| This becomes optional. It will only be populated if the user shares it via their privacy settings or if it was captured during our Mapping Phase. |
Reporting APIs | Messaging Interactions API | All exports and API responses will reflect the new BSUID-based consumerID. |
Identifier Value | IMEI (Personal Info)
| Always set. Contains the bare identifier value only: either the phone number or the BSUID (without the whatsapp_<account_id>_ prefix). Use this SDE to identify the active thread type. |
API & Integration Impacts
Messaging Interactions API
The messaging_history (.../conversations/search) payload structure is unchanged—no fields are renamed or removed. However, the values returned within the consumer identifiers will reflect BSUIDs for unmapped users.
- Filter Modifications: If your integration filters or queries by
consumerID, you must search for both formats to retrieve a single user's complete history (legacy phone-based format for pre-switch/mapped threads and BSUID-based format for post-switch threads). - No Filter Applied: If you retrieve complete conversation objects or account-level interactions without ID filtering, no API code changes are required.
- Lookup Pattern: Transition from a 1-Dimensional (phone-only) mapping database to a 2-Dimensional model where phone and BSUID are independent keys. Treat BSUID as the primary durable key.
- Latency: SDE-based searches in the historical API typically carry a ~2-hour indexing delay.
Participant ID Lookups (Global Functions)
If your systems fetch participantId via phone number lookups in customerInfo:
- Searching by phone number will not throw an error, but it will fail to return post-switch BSUID threads.
- Use the
IMEI SDE to determine the thread type and branch your search logic accordingly. - The recommended search pathway is through the
personalInfo.phoneNumber SDE. Reach out to the LivePerson Connectors Team for query rewrite assistance if required.
Phone-Number Recovery (Interactive Contact Request)
If a brand requires a phone number for verification, CRM syncing, or order fulfillment, you can use Meta’s Interactive Contact Request feature. LivePerson supports this via both agents and conversational bots.
- Trigger: The bot or agent sends a
requestPhoneNumber interactive message to the user. - Consent: When the user taps the native "Share" button, their verified number is sent directly into the chat thread and populates the
phonenumber SDE. - Persistence: Once recovered, the phone number persists for all future conversations. It does not, however, retroactively stitch historical threads.
Sample Payload for requestContactInfo Interactive Message:
{
"type": "vertical",
"tag": "requestContactInfo",
"elements": [
{
"type": "text",
"text": "Hi, Brand is requesting your WhatsApp Contact information",
"tag": "title"
},
{
"type": "button",
"title": "Share",
"click": {
"actions": [
{
"type": "custom",
"data": []
}
]
}
}
]
}
Other Key Integration Points
- Outbound & Marketing (Proactive/C2M): Unaffected. Brands should continue sending outbound templates and marketing messages via phone numbers. The LivePerson platform automatically conducts a "Dual-ID Check" against the registry to route outbound messages into the active BSUID thread when a mapping exists, preventing duplicate threads.
- Click-to-WhatsApp (CTWA) Ads: Referral and ad-source data will continue to arrive on the first inbound message. For unmapped users, you will receive only the BSUID, meaning you must trigger the Interactive Contact Request flow if a phone number is required.
- Custom Spam-Blocking: Custom "blocked" skills or routing rules keyed strictly on phone numbers may be bypassed by unmapped returning users. Update your blocklists to account for BSUIDs.
- Portfolio Changes: BSUIDs are scoped to your specific Meta Business Portfolio. If you migrate your WhatsApp numbers to a different portfolio, all existing BSUIDs will be invalidated, and Meta will generate brand-new IDs.
Action Checklist for Brands
Before activation, please ensure your technical teams complete the following audits:
- Database Capacity: Ensure your CRM and transactional databases are configured to store up to 128-character BSUID strings alongside existing phone fields.
- Audit Bot Logic: Remove any logic that hardcodes, parses, or strips phone numbers directly from the
consumerID string. Re-architect your bots to read from the phonenumber SDE instead. - Update API Queries: If you use the Messaging Interactions API, ensure your filters query both legacy phone-based formats and new BSUID formats to compile complete customer history.
- Implement Recovery Flows: Design and deploy bot/agent workflows utilizing the
requestPhoneNumber interactive template for use cases where phone verification is legally or operationally mandatory. - Re-align Geolocation: Re-point country-detection logic to read the two-letter prefix from the BSUID.
- Review Security & Blocking Rules: Audit custom spam-blocking integrations and third-party context data stores (such as CCS/namespaces) to ensure they are compatible with BSUID-scoped keys.
For further technical details, please refer to the Official Meta Developer Documentation. We are here to support you through this transition, please reach out to your Account Team with any questions!