# Migration Guide: Deprecation of user phone number Global Variable and Phone Capture in Flowbuilder

{{<tags>}}

Meta is launching optional [usernames](https://blog.whatsapp.com/its-time-to-reserve-your-whatsapp-username) 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/#contact-book)).

Because of this, the **user phone number** variable is being removed from Flowbuilder: it can no longer be guaranteed to always have a value. "Sometimes available" data leads to building logic that fails intermittently.

From now on, if a phone number is required for your process, it must be captured explicitly as a step within the flow. For identification and messaging when the phone number is absent, flows will now rely on Meta's new [**BSUID**](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/) (Business-Scoped User ID).

## How does this affect your flows?

- **Phone number masking:** If a user adopts a WhatsApp username, Meta will send only their [BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/) (unique technical identifier per company) 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.
- **Removal of global variable:** Since the phone number is now an optional field, the user phone number global variable has been removed from Flowbuilder to avoid execution failures in flows that relied on its implicit presence.

## Options for obtaining the number in the flow

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}

| 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 question node in the conversational flow. | No (only validates format). | Simple or non-critical cases. |

{{</table>}}

> **Recommendation:** If the number feeds rules or automated actions in [Webhooks/Automations](/guides/webhook_rule/), use **Option A**. For reference or complementary data, **B** or **C** are sufficient.

For more details on OTP phone validation, see the [Phone Validation Guide](/guides/phone_validation/).

## Integration with [Webhooks/Automations](/guides/webhook_rule/)

Events generated during flow execution (e.g., `process.started`, `process.succeeded`, `process.failed`) are evaluated in the rules engine using JSONLogic. In this context, the process variable `process.user_phone_number` in BRE operates under an automatic substitution (fallback) logic:

1. **Source Phone (WhatsApp):** If Meta provides the phone number in the user's initial webhook, `process.user_phone_number` will automatically adopt that value.
2. **Validated Number in Flow:** If Meta does not provide the source number (due to [BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/) / Username), the `process.user_phone_number` variable will take the value captured and verified in the flow (for example, through the Phone Validation node).
3. **Absent:** If Meta does not provide the number and the flow does not capture one, `process.user_phone_number` will be empty.

{{<notification message_top="**Important:** Since `process.user_phone_number` is no longer guaranteed, you must start leveraging the <a class='text-blue-600 hover:underline' href='https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/' target='_blank' rel='noopener'><strong>BSUID</strong></a> attribute in your rules and automations."
message_bottom="The <a class='text-blue-600 hover:underline' href='https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/' target='_blank' rel='noopener'>BSUID</a> acts as the primary, persistent user identifier across all events, ensuring your automated actions execute reliably even when the user's phone number is absent."
link=" "
link_text=" ">}}

For a full list of available events and variables, see [Webhooks: Events and variables](/guides/webhook_events_and_variables/).