Skip to main content
WhatsApp users can adopt a username (like @sheena) and hide their phone number from businesses. When that happens, you no longer see their phone number anywhere: instead, every webhook and API response identifies them by a business-scoped user ID (BSUID).
A BSUID is stable per business: the same user always has the same BSUID with you, but a different BSUID with every other business. You cannot derive a phone number from it. Zavu handles the identity plumbing automatically. Contacts are matched and de-duplicated by BSUID, conversations stay threaded, and if the user later shares their phone number, both identifiers point to the same contact. What you need to adapt in your integration is small, and it is all on this page.

​
Receiving messages from a username contact

Nothing changes in the event shape. The message.inbound webhook fires as usual, but data.from contains the BSUID instead of an E.164 phone number:
If your integration parses data.from as a phone number (regex for +, phone-number libraries, CRM lookups by E.164), it will break the first time a username contact writes in. Treat from as an opaque recipient identifier: it is either an E.164 phone number or a BSUID starting with a two-letter region prefix like US..
profileName still carries the user’s display name when available, so your inbox UI has something human to show.

​
Replying and sending to a BSUID

Pass the BSUID in to, exactly where a phone number would go. Zavu detects the format and routes it correctly on the WhatsApp API.
All WhatsApp message types work, including media, interactive messages and templates. The 24-hour conversation window rules are unchanged. Two exceptions:

​
Recovering the phone number

If your workflow eventually needs the real phone number (calls, SMS fallback, identity verification), ask for it in the conversation. WhatsApp provides a dedicated interactive message for this: request_contact_info. It renders a fixed Share Contact Info button; when the user taps it and confirms, their phone number arrives as a regular inbound contact message. Zavu then links the shared phone number to the BSUID contact automatically: the contact record gains a phoneNumber, and both identifiers resolve to the same contact and conversation from that point on. You can also add a request_contact_info button to a template to ask outside the 24-hour window.

​
Contacts in the dashboard

A contact created from a BSUID-only inbound has no phone number until the user shares one. The dashboard contact list and inbox display the username or BSUID instead, and flag conversations where a phone number was linked from a username contact. In the API, expect phoneNumber to be absent on these contacts. Key on the from value of the inbound events to correlate messages with your own records.

​
Your own business username

Your WABA can reserve a business username so customers can find and message you without knowing your number. Manage it from the dashboard under Accounts → WhatsApp → your WABA: the username section shows the current username, its status (reserved, approved, deleted) and lets you set or change it. Status changes arrive automatically; there is nothing to poll.
Username adoption is rolling out gradually on WhatsApp’s side. Your integration should handle BSUIDs today even if you have not seen one yet: any user can adopt a username at any time, and their next message to you will carry a BSUID.