[alpha] Usernames

Audience: Developers integrating WhatsApp via 360dialog Status: Pre-GA. Usernames launch later in 2026 (exact date pending). Some backend changes are already live. Last updated: June 2026

---

TL;DR — Why this is a breaking change

WhatsApp is launching usernames: users will be able to hide their phone number and show a handle (e.g. @maria.lopez) instead. When a user adopts a username, their phone number may disappear from your webhooks.

If your system uses the consumer's phone number as the primary key — for contact records, conversation routing, CRM matching, deduplication, or replies — it will break for users who adopt usernames and have no recent interaction history with you.

Rollout works in two stages. Over the coming months, Meta is enabling username adoption for end users country by country (countries not disclosed in advance) — so you may start seeing the username field in webhooks at any time. During this phase phone numbers remain in webhooks; they only start being withheld at full GA. Use this window to migrate: by GA your systems must handle webhooks with no phone number at all.

The replacement identifier is the Business-Scoped User ID (BSUID): a stable, per-business-portfolio user ID (e.g. BR.13491208655302741918). Meta already sends it in every webhook today. Your job before GA:

1. Store the BSUID from every webhook you receive, starting now.

2. Stop assuming wa_id / from is always present and always a phone number.

3. Support sending to a BSUID (recipient field) in addition to a phone number (to).

4. Handle the username field in webhooks for display purposes.

---

1. Key concepts

Concept	What it is
User username	Optional handle a WhatsApp user can set. If set, it is displayed instead of their phone number, and their phone number is withheld from businesses (with exceptions, see §3). One per user; changeable periodically. Changing it does not change the BSUID.
BSUID (user_id)	Stable user identifier, scoped to one business portfolio. Format: ISO country code + period + up to 128 alphanumerics, e.g. BR.1502576394655843. The same consumer has a different BSUID for every business portfolio they talk to. Regenerated only if the user changes their phone number (triggers a system webhook).
Parent BSUID (parent_user_id)	For managed businesses with multiple portfolios that enroll with Meta: one ID usable across all enrolled portfolios. Format includes ENT, e.g. US.ENT.11815799212886844830. Opt-in via Meta point of contact.
Meta Contact Book	Meta-hosted phone↔BSUID store, live since early April 2026, recording automatically — no integration needed. Any message/call between your portfolio and a user stores their phone + BSUID. While a user is in the contact book, their phone number keeps appearing in your webhooks even if they adopt a username. Scoped per portfolio; only interactions after launch are captured.
30-day cache	Independently of the contact book, a user's phone number appears in webhooks if that specific business phone number exchanged a message/call with the user's phone number in the last 30 days. Evaluated per business phone number, not per portfolio.
Business username	Handle for your business number (claimable now as "reserved"). Does not hide your business phone number — it's for discoverability/branding, not privacy.

Critical scoping rule: a BSUID only works with business phone numbers in the same portfolio. Sending to a customer's BSUID from a number in a different portfolio fails. The same consumer appears as a different BSUID to each portfolio — never share or compare BSUIDs across clients.

---

2. Timeline

When	What
Late March / early April 2026 — LIVE	BSUID (user_id, from_user_id, recipient_user_id) included in all messages and status webhooks, globally.
Early April 2026 — LIVE	Meta Contact Book recording interactions for all businesses.
Now — available	Claim your reserved business username (WhatsApp Manager, Meta Business Suite, or API).
Early July 2026	REQUEST_CONTACT_INFO buttons (templates + interactive). Available in production — see §5.
May Early July 2026	Sending messages to BSUIDs only (recipient field)
Coming months — phased rollout	Meta will progressively enable username adoption for end users in selected countries (not disclosed in advance). You may start seeing the username field in webhooks at any time. Phone numbers keep appearing in webhooks during this phase — nothing breaks yet.
GA, later in 2026 (date pending)	Full feature launch. Phone numbers start being withheld from webhooks for username adopters per §3. Business usernames go visible/searchable.

Everything in this guide describes the target GA behavior as confirmed with Meta engineering during 360dialog's alpha testing. It supersedes Meta's public docs where they differ (Meta is updating them).

---

3. When do you still get the phone number?

After GA, a user's phone number is included in webhooks if any of:

1. That business phone number sent the user a message/call in the last 30 days, or

2. That business phone number received a message/call from the user in the last 30 days, or

3. The user is in your portfolio's contact book.

Otherwise — username-adopting user, no history — you get BSUID only.

Practical consequence: because the contact book has been recording since April, most of your existing active users will keep showing phone numbers. The BSUID-only case hits you with new users who already adopted a username — exactly the contacts you cannot recover by any other means. This is why BSUID storage must be in place before GA.

---

4. What changes on the wire

4.1 Inbound message webhooks

New fields (already live), plus conditional omission of phone fields after GA:

{
  "contacts": [{
    "profile": {
      "name": "Nehemiah",
      "username": "nehemiah.babel"          // ADDED — only if user adopted a username
    },
    "wa_id": "310601600963",            // CAN BE OMITTED after GA (see §3)
    "user_id": "RS.1502576394655843"    // ADDED — always present
  }],
  "messages": [{
    "from": "310601600963",             // CAN BE OMITTED after GA
    "from_user_id": "RS.1502576394655843",  // ADDED — always present
    "type": "text",
    "text": { "body": "Hello!" }
  }]
}

Notes confirmed in alpha testing:

• username is serialized without the @ prefix ("shalabajza", not "@shalabajza").

• If parent BSUIDs are enabled, parent_user_id appears alongside user_id.

4.2 Status webhooks (sent / delivered / read / failed)

A contacts array is added (sent/delivered/read only), and the statuses block gains BSUID fields:

{
  "contacts": [{
    "profile": { "name": "Nehemiah", "username": "nehemiah.babel" },
    "wa_id": "310601600963",                      // omitted if phone unavailable
    "user_id": "RS.1502576394655843"
  }],
  "statuses": [{
    "id": "wamid.XXX",
    "status": "delivered",
    "recipient_id": "310601600963",               // omitted if phone unavailable
    "recipient_user_id": "RS.1502576394655843"    // always present
  }]
}

For failed statuses: the contacts array is omitted entirely, and recipient_user_id is omitted if the message was sent to a phone number.

4.3 Identifier quick reference

Inbound messages:

Field	User has username	No username
wa_id / from	Only if phone available per §3	Always
user_id / from_user_id	Always	Always
username	Always	Never

Outbound statuses (sent/delivered/read):

Field	Sent to phone	Sent to BSUID
wa_id, recipient_id	Always	Only if phone available per §3
user_id, recipient_user_id	Always	Always
username	delivered/read, if user has one	delivered/read, if user has one

4.4 Sending messages

The Messages API gains a recipient field for BSUIDs. Via 360dialog (https://waba-v2.360dialog.io, D360-API-KEY header):

POST https://waba-v2.360dialog.io/messages
D360-API-KEY: <your-api-key>
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "310601600963",               // phone — optional
  "recipient": "RS.1502576394655843", // BSUID — optional
  "type": "text",
  "text": { "body": "Hello!" }
}

Rules:

• Provide to, recipient, or both. If both, to (phone) takes precedence — recommended where you have the phone, because phone-based sends keep refreshing your 30-day cache and contact book.

• BSUIDs must be sent complete and exact: country code, period, full identifier.

• BSUIDs work for all message types except one-tap, zero-tap, and copy-code authentication templates (phone required). Attempting it returns error 131062 ("BSUID recipients are not supported for this message").

• A BSUID-only send to a user whose 24-hour service window is closed fails with the standard window error (131047) — you cannot open a conversation with a free-form message to a BSUID any more than you can to a phone number. Use a template.

4.5 Send responses

// Sent to phone (or phone + BSUID — phone wins):
{ "contacts": [{ "input": "310601600963", "wa_id": "310601600963" }],
  "messages": [{ "id": "wamid.XXX" }] }

// Sent to BSUID only:
{ "contacts": [{ "input": "RS.1502576394655843", "user_id": "RS.1502576394655843" }],
  "messages": [{ "id": "wamid.XXX" }] }

• input echoes what you sent; wa_id only appears for phone sends; user_id only for BSUID sends. Never expect a BSUID inside wa_id — if your parser sees wa_id, it can safely treat it as a phone number.

• The /marketing_messages endpoint follows the same request/response shape (including message_status: "accepted").

• A successful send always returns a wamid — store it; it is your only correlation key to delivery/read/button-tap webhooks when no phone number is present.

---

5. Recovering phone numbers: REQUEST_CONTACT_INFO

When you only hold a BSUID, you can ask the user to share their phone number with one tap. Available as a button in utility and marketing templates or as an interactive message.

Stability note (June 2026): Meta now lists this feature as available starting early July 2026 (moved from early May — consistent with our testing, which showed it was not working reliably in production).

Template — the text field is optional and the button label cannot be customized (a fixed label is always shown). If you do include text, any value other than Share Contact Info is rejected at template creation (subcode 2388153):

{
  "name": "request_number",
  "category": "utility",
  "language": "en_US",
  "components": [
    { "type": "BODY", "text": "Please share your phone number so we can continue." },
    { "type": "BUTTONS", "buttons": [
      { "type": "REQUEST_CONTACT_INFO"}
    ]}
  ]
}

Interactive message — note interactive.type is "request_contact_info":

POST https://waba-v2.360dialog.io/messages
{
  "messaging_product": "whatsapp",
  "recipient": "RS.1502576394655843",
  "type": "interactive",
  "interactive": {
    "type": "request_contact_info",
    "body": { "text": "Please share your phone number so we can continue." },
    "action": { "name": "request_contact_info" }
  }
}

On tap, you receive a contacts webhook:

• messages[0].type = "contacts", with from_user_id (BSUID) and the shared phone in messages[0].contacts[0].phones[0].

• origin = "contact_request" (button tap) → no vCard included. origin = "other" (user shared a contact manually) → vCard included.

• The shared number is automatically added to your contact book, so subsequent webhooks include the phone again.

• Normalize on phones[0].wa_id (clean digits, no +, no spaces) as the canonical phone value.

---

6. Business usernames

• Claimable now as reserved names; they become visible/searchable at GA. Your business phone number is never hidden.

• Format: 3–35 chars, a–z 0–9 . _, at least one letter, no leading/trailing/double periods, must not start with www or end with a domain suffix. Case-insensitive; . and _ are significant.

• If your reserved name is already used by your Facebook Page or Instagram account, link the phone number to that asset first.

Endpoints (360dialog conventions; same paths as the Graph API minus the phone-number-ID segment):

Action	Call
List reserved suggestions	GET /username_suggestions
Claim / change	POST /username with { "username": "yourbrand" }
Check current	GET /username → { "username": "...", "status": "..." }
Delete	DELETE /username

Statuses: reserved → approved → active at GA

Things to know:

• Username changes are rate-limited: (Meta enforces a maximum number of changes per phone number within a rolling window). Hitting the limit returns a rate-limit error — do not retry immediately.

• Other claim errors: 147001 not available, 147002 portfolio messaging limit too low, 147003/147004 FB/IG asset not linked, 133010 number not registered.

• Subscribe to the new business_username_update webhook field on each app to be notified of status changes (approved / reserved / deleted).

• Chat header display priority: saved contact name → verified business name / OBA name → username → phone number.

---

7. What you must change — checklist

Data model

• Add user_id (BSUID) to your contact/conversation records, keyed per portfolio (and parent_user_id if applicable). Start persisting it from webhooks today — it's already being sent.

• Make the consumer phone number nullable everywhere. Build a BSUID↔phone mapping table; treat phone as enrichment, not identity.

• Add username (display string, no @, can change over time — never use as a key).

Webhook consumers

• Remove any assumption that contacts[0].wa_id, messages[0].from, or statuses[0].recipient_id exists. Fall back to user_id / from_user_id / recipient_user_id.

• Don't run E.164 validation on identity fields generically; route on field name (wa_id = phone, user_id = BSUID).

• Tolerate unknown/new fields (username, parent_user_id, recipient_parent_user_id, from_user_id).

• Handle failed statuses having no contacts array.

Send path

• Support recipient (BSUID) in your send layer; choose phone when you have it (keeps phone visibility alive via the 30-day cache/contact book).

• Store the wamid from every send response and correlate statuses by wamid, not by recipient phone.

• Handle 131062 (BSUID not supported for auth templates) and 131047 (window closed) on BSUID sends.

Phone recovery & UX

• Implement a REQUEST_CONTACT_INFO flow (template + interactive) for BSUID-only contacts whose phone number you need (e.g. for auth templates or cross-channel matching).

• Update your UIs to display username or BSUID when no phone is available.

Account setup

• Claim your business username (and advise your clients to claim theirs) before GA — handles are first come, first served at the suggestion level.

• Subscribe apps to business_username_update.

• Multi-portfolio managed businesses: evaluate parent BSUID enrollment with your 360dialog contact.

---

8. What you can test today

Test	How
BSUID parsing	Inspect your live webhooks — user_id, from_user_id, recipient_user_id are already present in production. Verify your pipeline stores them.
Sending to a BSUID Available Early July	Live in production, no allowlist needed. Take a user_id from a recent webhook and send with recipient instead of to (§4.4). Verify your response parsing handles the { input, user_id } shape.
Username claiming	GET /username_suggestions, claim via POST /username or WhatsApp Manager, verify with GET /username.
Contact book	It's recording already; nothing to integrate. Optionally test DELETE /contact_book?messaging_product=whatsapp&bsuid=<BSUID> to remove an entry (also clears the 30-day cache during alpha).

Not yet usable: REQUEST_CONTACT_INFO flows (documented but unstable — see §5) and usernames visible in the app (GA).

Follow the Validation guide to ensure your system is ready for when usernames become Generaly Available

---

9. FAQ

Timeline and rollot

When exactly does this start affecting me?

You may see username fields in webhooks any time from now, as Meta enables adoption in selected (undisclosed) countries — but phone numbers remain in webhooks throughout this pre-GA rollout, so nothing breaks yet. Phone withholding starts at full GA. Even then, existing active conversations are protected (contact book + 30-day cache); the breaking case is new inbound contacts who adopted a username: BSUID-only from the first message.

What are the firm key dates and the mandatory migration deadline?

Confirmed live: BSUID in webhooks (Mar–Apr 2026), Meta Contact Book (Apr), sending to BSUIDs (May), REQUEST_CONTACT_INFO buttons (May, unstable). Username adoption then rolls out country-by-country, not disclosed in advance.

There is no strict mandatory cutover date and no forced API-version upgrade — username adoption is optional for consumers, so the timeline is consumer-driven rather than enforced by Meta.

That said, migration is a functional necessity, not optional in practice: once end users in a country can hide their phone numbers, any integration that hasn't been updated to accept BSUIDs and tolerate an empty phone number will start failing and conversations will break. Meta therefore strongly advises completing your integration by late June 2026 — when the first users in test countries gain the ability to hide their numbers. Full global GA is targeted for the second half of 2026 (exact date to be confirmed; we'll notify).

During the transition, will webhooks still carry both the phone number and the BSUID when available?

Yes. Pre-GA, phone numbers remain in all webhooks alongside the BSUID. Post-GA you get the phone if any of: that business number messaged the user in the last 30 days, the user messaged that business number in the last 30 days, or the user is in your portfolio's contact book — otherwise BSUID only.

Identifiers & mapping

Is the BSUID the same across my clients?

No. It's scoped per business portfolio. The same consumer has a different BSUID for each of your clients. Never dedupe or share BSUIDs across portfolios.

Does a username change break my mapping?

No. Usernames can change; the BSUID stays stable. Switching to a new device or handset (same phone number) doesn't change it either. Only a user changing their phone number regenerates the BSUID — and you'll get a system webhook when that happens.

// Sytem message webhook
// https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/#system-messages-webhooks
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "system",
                "system": {
                  "body": "User...",                       <!-- CHANGED -->
                  "wa_id": "<NEW_WHATSAPP_USER_ID>",       <!-- CHANGED -->
                  "user_id": "<NEW_BSUID>",                <!-- ADDED -->

                  <!-- Only included if parent BSUIDs enabled -->
                  "parent_user_id": "<NEW_PARENT_BSUID>",  <!-- ADDED -->
                  "type": "<SYSTEM_CHANGE_TYPE>"           <!-- CHANGED -->
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Can the username feature be turned off by the user, and what happens if they toggle it?

Yes. Consumers can fully remove or delete their username at any time. Deleting a username makes their phone number visible again, and it simply resumes flowing into your webhooks. Deleting or disabling a username does not change the user's underlying BSUID, so your mapping stays intact. In fact, if a user had previously hidden their phone number, deleting the username acts as a trigger to share it — populating your Contact Book so the number is available for future interactions.

What's the recommended migration strategy when the phone number is my primary database key?

Make the consumer phone nullable everywhere; persist user_id (BSUID, per portfolio — plus parent_user_id if applicable) from every webhook starting now; build a BSUID↔phone mapping table and treat phone as enrichment, not identity. Route on field name (wa_id = phone, user_id = BSUID) rather than E.164 validation, and correlate sends by wamid.

Can I match a brand-new username-only user to my historical phone-based records?

Not automatically. A user who only messaged you before launch and returns username-only with no recent history arrives as BSUID only — unrecoverable by mapping alone. Use REQUEST_CONTACT_INFO to ask them to share their number, then map. Users with any post-launch interaction stay matchable via the contact book / 30-day cache.

Sending messages

Where does the BSUID go in the send request — in to?

No. to is phone-only. BSUIDs go in the separate recipient field (omit to for a BSUID-only send). Putting a BSUID in to fails. See §4.4.

Can I keep messaging by phone number — and for how long?

Yes, wherever you have it — and it's recommended, since phone-based interactions keep the phone visible in webhooks via the 30-day cache/contact book. No deprecation or sunset date for phone-based sending has been published.

I collected a phone number outside WhatsApp (web form, CRM, etc.). Can I still start the conversation if that user is username-only?

Yes. Send a template to the phone number as usual. Because the message was sent to the phone number, the send response and the user's reply include both the phone number (wa_id/from) and the BSUID — and that first business-initiated contact creates the contact book entry, so the phone number keeps appearing in subsequent webhooks. Store the BSUID from the first reply and you're fully mapped. Username privacy only hides numbers WhatsApp would have to reveal to you; numbers you already have keep working.

Do utility templates and the 24-hour service window behave differently for BSUID-only users?

No window difference — a BSUID send into a closed 24h window fails with 131047; use a template. Utility and marketing templates work to BSUIDs. The exception is authentication templates (one-tap, zero-tap, copy-code), which require a phone and fail with 131062.

What breaks for authentication / identity-verification flows?

Auth templates aren't supported for BSUID recipients (131062). Recover the phone number via REQUEST_CONTACT_INFO first, then send the auth template.

Can I start a conversation using the user's username instead of their phone number?

No. The username is display-only and can change over time — never use it to address a message. You send to a phone number (to) or a BSUID (recipient); see §4.4. The BSUID is the stable identifier and does not change when the user changes their username. Standard initiation rules still apply: to open a conversation with a BSUID-only user you need a template (a free-form send into a closed 24h window fails with 131047), and authentication templates aren't supported for BSUIDs (131062).

Phone recovery & contact book

If I ask via REQUEST_CONTACT_INFO, does the phone come back in all subsequent webhooks?

Yes — a shared number is automatically added to your contact book, so later webhooks include the phone again. Caveat: as of June 2026, REQUEST_CONTACT_INFO is not yet reliable in production — stage it but don't depend on it in live traffic until we confirm stability.

Can I clear a phone number from the 30-day cache or contact book?

No. 30 day cache is there even after DELETE /contact_book was requested.

There is no supported API or workaround to bypass or clear the 30-day rolling cache once the feature is live. Plan your testing and data flows around the cache window rather than expecting to flush it on demand.

Business usernames

Do business usernames hide my clients' business numbers?

No. Business usernames are branding/discoverability only.

How does the business display name work in chat?

Chat-header display priority is: saved contact name → verified business / OBA name → username → phone number. Claim your reserved handle now; it goes visible/searchable at GA.

How do API clients reserve a business username?

Starting June 29, 2026 a business username can be adopted or changed via Meta Business Suite, WhatsApp Manager, the WhatsApp Business app, or the Username API. API clients can reserve directly today through the 360dialog API (§6: POST /username) — no need to go through the app. A 360dialog UI for this is coming.

If a client reserves the username in the WhatsApp Business app and later migrates to the API, is it retained?

The username is attached to the business account/phone-number asset, so it is expected to persist through migration and not need re-reserving. We're confirming this with Meta and will update here.

Groups

What about group messages?

Send responses echo the group ID in input; group flows are otherwise unaffected by this guide's scope.

Account types & migration

Does this apply to WhatsApp Business API accounts, and what about Coexistence?

Yes. BSUIDs and usernames are a platform-level change across the whole WhatsApp ecosystem — Cloud API, and Coexistence setups all get BSUIDs in webhooks and can be addressed by BSUID. Nothing in this guide is API-only; the migration steps in §7 apply to any integration that consumes webhooks or sends messages.

We're migrating between the WhatsApp Business app and the API — does anything break?

The BSUID is tied to the user↔business-portfolio relationship, not to how you access the account, so identity mapping is not expected to change on migration. One item we're confirming with Meta: whether Contact Book entries and the 30-day cache carry over across the migration (they may reset, which would flip some contacts to BSUID-only until the next interaction). We'll update this section once confirmed.

---

Questions? Contact your 360dialog account manager or support. Source references: Meta "Business-scoped user IDs" developer documentation and 360dialog's E2E alpha testing program with Meta engineering (May–June 2026).