Support for WhatsApp username feature

Overview

Starting in 2026, WhatsApp users can adopt usernames to message businesses without sharing their phone numbers. The Business-scoped user ID (BSUID) serves as a "backend identifier" that enables businesses to maintain customer continuity even without the customer’s phone number. Key points:

• A BSUID is uniquely generated for each user-business pair. It serves as a stable identifier for most API requests and events. A new BSUID is generated if a user changes their phone number or a business changes WABA.
• If a customer decides to adopt a username, their phone number will not be included in API calls to businesses unless it was used within the last 30 days or since Meta enabled contact books. To help reduce disruption, we strongly recommend keeping Meta’s Contact Book feature enabled in your Meta Business Portfolio.
• With username enabled, a new attribute username is provided. However, a username is not suited for contact identification, as it can be changed or reassigned over time, just as phone numbers may be recycled by mobile service providers.
• For two or more linked portfolios, an additional Parent BSUID is provided (it is not available by default and requires explicit enablement and approval from Meta).
• Technical details are described in https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids.

Migration choices

BSUID is introduced as the primary system-level identifier for user–business interactions, particularly when phone numbers are hidden, though it does not fully replace them. This shift introduces challenges in identity resolution, especially for existing customers whose WhatsApp contacts are based solely on phone numbers. To support migration, Genesys provides several approaches, each with its own trade-offs, for handling both identifiers and maintaining contact continuity.

Currently, the Genesys solution uses a customer’s phone number to identify the contact. Using a phone number for contact identification does not fully align with known privacy regulations, as phone numbers can be recycled (i.e., reassigned to a new owner). But, until now, WhatsApp has not provided other means for this purpose.

Meta BSUID enablement affects how the Genesys solution handles chat sessions and identifies contacts. Genesys offers the following migration choices:

• Chat Sessions identification. To allow BSUID to be used instead of a phone number for session identification, HubPP was upgraded on June 2, 2026. The upgrade allows existing versions of the Hub Driver (through 9.1.021.00) to continue operating with chat sessions (see Release Notes at https://docs.genesys.com/Documentation/RN/9.1.x/es-drvr-hub91rn/es-drvr-hub91rn).
• Contacts identification. Old versions (through 9.1.021.00) of Hub Driver use only a phone number as a primary contact attribute. When only a BSUID is provided, and a phone number is absent, a chat session is not assigned to a contact. The newer versions of Hub Driver introduce a configuration option “x-contact-identity-mode“ in section “channel-ghub“ (https://docs.genesys.com/Documentation/Options/latest/ES/Hub-channel-ghub) with the following values:
  • none (default): a full backward compatibility mode to allow customers to upgrade the Hub Driver before configuring any other mode.
  • fixed: in this mode, the Hub Driver adds a set of new attached data KVPs, including WhatsApp_BSUID (and if present in webhook event, WhatsApp_Username and WhatsApp_ParentBSUID). Contact identification can be configured in a couple of different ways:
    • BSUID is the only identifier used for contact search. In this case, all previous contact history associated with the phone number will be ignored for this contact.
    • Phone number is used as the primary attribute for contact search. Only if the phone number is not provided will the BSUID be used for contact search. This mode maintains the continuity of an existing contact history (based on phone numbers), but can now assign a contact if a phone number is not provided.
  • lax (the mode will be available in the next version of Hub Driver and will require the upgrade of DMS). It implements the custom contact identification approach:
    • The solution first searches for BSUID in contacts. If a contact is found, it will be assigned for a chat session. And if a phone number is provided, the hub driver updates the contact record with it.
    • If no contact is found for the provided BSUID, the solution searches for a contact using the provided phone number. If only a single contact is found and it is not yet associated with BSUID, it will be updated with BSUID and assigned to a chat session. Otherwise, a new contact is created.
    • While this mode uses BSUID as a primary contact identification attribute, it stitches a new BSUID-based identity with an existing phone-based identity.

Methods Comparison

Method	PROS	CONS
none	n/a	n/a
fixed with BSUID	Contact identification strongly complies with privacy regulations.	Existing phone-based contact history is completely ignored.
fixed with phone number	Continue using the existing phone-based contact history, but permit BSUID-only contacts if the phone number is not provided.	Does not detect phone number ownership transfers, as the phone number serves as the primary key for contact identification.
lax	For contacts that are already BSUID-associated, it strongly complies with privacy regulations.	Implementing custom contact identification in the DMS, rather than the standard UCS-based approach, may add insignificant latency when creating chat sessions.

How to enable new-hub-driver contact identification modes

For all modes:

• Create a new custom contact attribute named WhatsApp_BSUID (with the same Display Name). See the instructions below for creating a custom contact attribute.
• Optionally, to make these attributes searchable in WDE, create custom contact attributes named WhatsApp_Username and WhatsApp_ParentBSUID.

For fixed mode:

• Upgrade Hub Driver to version “9.1.024.01“.
• In the Hub Driver application, in section “channel-ghub“, set
  • whatsapp-identity-mode = fixed
• For media type “whatsappsession”, create a customized contact identification configuration (instructions provided in https://docs.genesys.com/Documentation/ES/8.5.1/Admin/IDCntMedia)
  • For fixed with BSUID: WhatsApp_BSUID with value “level=0;mandatory=false”.
  • For fixed with a phone number: PhoneNumber (“level=0;mandatory=false”) and WhatsApp_BSUID (“level=1;mandatory=false”).

For lax mode:

• Upgrade the Hub Driver to version “will be provided later”. Upgrade DMS to version “will be provided later“.
• No configuration for contact identification is needed.
• In the Hub Driver application, in section “channel-ghub“, set
  • whatsapp-identity-mode = lax

How to create a Custom Contact Attribute

To create a customer contact attribute using CME:

• In “Business Attributes“, locate “Contact Attributes“.
• Under “Attribute Values“, create a new “Business Attribute Value” and use the same value both for Name and for Display Name.
• In Annex, create the section “settings“, add an option with the name “is-sortable“ and the value “true" (described in https://docs.genesys.com/Documentation/ES/8.5.1/Admin/UCSSearchMake)

Example for WhatsApp_BSUID: