Migration Guide: How to address the deprecation of user phone number variable

What is changing and why

Meta is launching optional usernames on WhatsApp. If a user activates this feature, their phone number is no longer automatically handed over to the business (unless there has been direct interaction in the last 30 days or the user is already in the business’s contact book).

Because of this, Flowbuilder is removing the User phone number global variable (user_phone_number): it can no longer be guaranteed to always have a value. Data that is only sometimes available leads to logic that fails intermittently.

Deadline — August 14, 2026: From this date, Flowbuilder will block saving any flow that still references User phone number (user_phone_number). Published flows are not unpublished and keep running, but user_phone_number may be empty.
Replace every reference with an explicit phone capture step (see options below), or stop depending on the phone number. For identification when the phone is absent, use WhatsApp User ID in Flowbuilder or process.business_scoped_user_id in Webhooks/Automations — both map to Meta’s BSUID.

How does this affect your flows?

Phone number masking: If a user adopts a WhatsApp username, Meta will send only their BSUID (unique technical identifier per Meta Business Account) in inbound webhooks instead of their phone number.
Availability exceptions: Meta will only send the user’s phone number in the webhook if you have interacted (sent/received messages or calls) with that specific number within the last 30 days.
WhatsApp User ID variable: Flowbuilder now exposes a WhatsApp User ID global variable that references that BSUID. In Webhooks/Automations, the same value is available as process.business_scoped_user_id. Use either as the stable identifier when the phone number is unavailable.
Removal of User phone number: Because the phone number is now optional, the user_phone_number global variable is being removed so flows cannot rely on its implicit presence. After the deadline, you cannot save flows that still use it. Published flows keep running and are not unpublished, but user_phone_number may be empty at runtime.

Options for obtaining the number in the flow

If your process needs a phone number, capture it with one of the blocks below and read it from that block’s output variables.

Option	What it does	Verifies number	When to use it
A. Phone Validation (OTP)	Asks for the number and sends an OTP that the user must confirm.	Yes (Validated and active number).	When the data is critical or will be used for webhooks or automated actions.
B. WhatsApp Flow Question	Phone field within an interactive form.	No (only validates format).	When other data is already being collected within a form.
C. Open Phone-type Question	Simple Open question block with answer type set to Phone.	No (only validates format).	Simple or non-critical cases.

Recommendation: If the number feeds rules or automated actions in Webhooks/Automations, use Option A. For reference or complementary data, B or C are sufficient.

Migration checklist

Identify flows that reference User phone number (user_phone_number) — open each flow and check global variables and any block that reads that value.
Add an explicit capture step (Option A, B, or C).
Update webhook rules and automations to use WhatsApp User ID / process.business_scoped_user_id (BSUID) instead of phone number.
Test flows with a username-enabled (private phone number) account.

Integration with Webhooks/Automations

Flowbuilder removes the User phone number global variable (user_phone_number). Webhooks/Automations may still expose process.user_phone_number with the fallback below — that value is not guaranteed.

Events generated during flow execution (e.g., process.started, process.succeeded, process.failed) are evaluated in the rules engine using JSONLogic. In Webhooks/Automations, the BSUID is available as process.business_scoped_user_id. The process variable process.user_phone_number still follows automatic substitution (fallback) logic:

Source phone (WhatsApp): If Meta provides the phone number in the user’s initial webhook, process.user_phone_number takes that value.
Validated number in the flow: If Meta does not provide the source number (due to BSUID / username), process.user_phone_number takes the value captured and verified in the flow (for example, through the Phone Validation node).
Absent: If Meta does not provide the number and the flow does not capture one, process.user_phone_number is empty.

Note: process.user_phone_number may still appear in Webhooks/Automations with the fallback logic above, but it can be empty.
When you need a stable identifier, prefer process.business_scoped_user_id (Meta’s BSUID).

For a full list of available events and variables, see Webhooks: Events and variables.