Migration Guide: Deprecation of user phone number Global Variable and Phone Capture in Flowbuilder
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, 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 (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 (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
| 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. |
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.
For more details on OTP phone validation, see the Phone Validation Guide.
Integration with Webhooks/Automations
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:
- Source Phone (WhatsApp): If Meta provides the phone number in the user’s initial webhook,
process.user_phone_numberwill automatically adopt that value. - Validated Number in Flow: If Meta does not provide the source number (due to BSUID / Username), the
process.user_phone_numbervariable will take 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_numberwill be empty.
process.user_phone_number is no longer guaranteed, you must start leveraging the BSUID attribute in your rules and automations.The BSUID 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.
For a full list of available events and variables, see Webhooks: Events and variables.