Skip to main content

WhatsApp channel update - Usernames, BSUID, and new IDs

  • Updated

Index:

  1. Introduction
  2. Timeline
  3. Businesses - How to adopt or reserve a username
  4. Contacts - BSUID Identification
    1. Overview
    2. Where to find the BSUID - Message Metadata
    3. Available properties
    4. Premises
    5. How to extract metadata information
  5. Internal identification of contacts in Blip
    1. Overview
    2. Evolution of the contact.identity field
    3. Necessary actions and possible impacts
    4. Main recommendations

 

Introduction 

As recently announced by Meta, the contact identification model in WhatsApp Business is evolving. Aiming for user privacy, Meta is introducing Usernames in WhatsApp. Meta's official technical documentation.

The adoption of usernames is optional for both the end user and businesses. If the end user adopts a username, however, their phone number will no longer be shared, with only the username and other related technical IDs being displayed. Businesses, however, even if they have adopted a username, will continue to display the phone number registered to their WhatsApp account. 

In addition to the introduction of usernames on WhatsApp, each username is associated with a BSUID (Business-Scoped User ID), a unique identifier between the user and a specific company that allows the sending of messages on WhatsApp even when the user's phone number is not available. Unlike the phone number, which is always the same number regardless of the company that the contact interacts with, the BSUID for the same user will be unique and different for each of the companies the contact interacts with (based on the company's Business Manager/Business Portfolio).

 

Timeline 

  • June/2026: the Usernames functionality will be released by Meta for testing in some countries 

  • July/2026: rollout to a second sample of test countries defined by Meta 

  • August/2026: expected global launch in GA by Meta 

All milestones described above may be changed in advance based on Meta's own definitions and guidelines.

 

Businesses - How to adopt or reserve a username 

Just like the user, the business will also be able to adopt the use of a username or even reserve a username for its WhatsApp accounts. This adoption, however, is not yet available. We will update this documentation as soon as possible to reflect this process.

 

Contacts - BSUID Identification 

Overview 

All contacts, regardless of whether they adopt a username or not, will now come with the new identifier created by Meta for WhatsApp, the BSUID. 

The phone number of the contact/end user will only be provided by Meta in B2C interactions if:

  • The contact has not adopted a username

  • The contact's phone number is registered in the business Contact List (a feature launched by Meta in April/2026 and natively enabled to record data of contacts who interact with the business)

Where to find the BSUID - Message Metadata 

The BSUID is made available by Blip in the metadata of messages (messages, notifications, and echoes, in cases of Coexistence activations) and will be present in the metadata object of each envelope (messages, notifications, or echo) as long as this information is sent to Blip by Meta/Whatsapp in the corresponding webhooks. 

To consult the BSUID information via metadata:

  • Access the desired bot in the Portal

  • Access the top menu of Blip

  • Click on the three dots icon (...)

  • Select the Log option in the menu

  • Locate the metadata object inside the message envelope

Available properties 

Within the metadata, the identifiers will be available through the following properties:

  • #wa.bsuid: Unique user identifier (BSUID)

  • #wa.parentId: User identifier shared between different companies (when applicable)

Premises 

  • The property #wa.parentId will be included only in cases where Meta authorizes this feature for the company. Important: the request for Parent ID activation must be made by the company to Meta through a support ticket.

  • All of these fields depend on availability from Meta/Facebook; therefore, their presence is conditioned on the data received by the channel in Blip. 

  • This information allows for tracking and interacting with users consistently, even without direct access to the phone number.

How to extract metadata information 

To extract this information, you must define two output actions in the Start block of the Studio:

1. Define metadata variable 

Define a variable with the following parameters:

  • Variable name: metadata

  • Value: {{input.message@metadata}}

2. Execute script 

Execute a script to obtain only the value of #wa.bsuid present in this metadata. Script configuration:

function run(metadata){
metadata= JSON.parse(metadata);
return metadata["#wa.bsuid"];
}

The scope of the script will be presented, as shown in the image below:

TIP! Use event logs to enhance data capture and make them more presentable through custom reports.

 

Internal identification of contacts in Blip 

Overview 

Aiming to minimize the impact on our customers, Blip creates an abstraction that analyzes the data received from Meta and performs the relationship with an existing contact or creates a new contact when necessary. 

With the evolution of the WhatsApp identification model, Blip is also evolving the way contacts are identified on the platform.

Evolution of the contact.identity field 

Currently, the contact.identity field (available in the Blip variables library) is filled with the user's phone number in this format:

  • {phone_number}@wa.gw.msging.net

Starting from the evolution planned for June 1st, 2026, considering that the phone number may no longer be available, new contacts will be created with a Blip's own ID in the format:

  • {guid}@wa.gw.msging.net

The contact.identity field, therefore, no longer necessarily represents a phone number and becomes an internal Blip ID. Contacts already existing in Blip prior to June 1st will not be affected.

Necessary actions and possible impacts 

It is important to review your operation in Blip to ensure that it does not depend on a specific format of the existing contact.identity field in Blip. We suggest mapping mainly in:

  • APIs, webhooks, databases, and external systems integrated with Blip (CRM, ERP, etc.)

  • Conversational flows within Blip itself

  • Business rules that use contact.identity (example: logs, audits, or reports that assume a numerical format)

Main recommendations

  • Treat contact.identity as a generic identifier (string), without assuming it is a phone number

  • Remove rigid format validations (e.g., phone regex)

  • Do not use it as a primary key based on a phone number

 

Need more help? Explore our content at Blip Academy or Blip Community, watch tutorials on our YouTube channel, or clear your doubts in our service channel 😃

Related articles