A WhatsApp Business API integration identifies a customer who uses a WhatsApp username by a business-scoped user ID (BSUID), a code unique to each customer and business portfolio. The webhook still includes the phone number when the same business number exchanged a message or call with the customer in the last 30 days. The number also stays in webhooks for customers in the Contact Book, a list Meta keeps of phone numbers from past conversations. Every other message from a customer with a username arrives with a BSUID and no phone number. A webhook handler must accept messages that arrive with a BSUID and no phone number. If it rejects them, those messages are lost, and Meta has no way to send them again.
Key Takeaways
- Meta requires partners, directly integrated businesses, and click-to-WhatsApp advertisers on the WhatsApp Business Platform to support BSUIDs.
- A customer’s phone number keeps arriving for 30 days after a message or call on the same business number, and for as long as the customer stays in the Contact Book.
- A message can go to a BSUID, a phone number, or both, and only one-tap, zero-tap, and copy code authentication templates still need the phone number.
- A business that needs a phone number can ask for it in the chat with a button, and the customer decides whether to share it.
- 360Dialog, an Official Meta Solution Partner, gives businesses WhatsApp Business API access that accepts BSUIDs as message recipients.
What Is a Business-Scoped User ID (BSUID)?
A business-scoped user ID (BSUID) is an identifier WhatsApp generates for each pair of customer and business portfolio, and it arrives in webhooks whether or not the customer has a username. Storing it gives an integration one customer key that keeps working when a customer stops sharing their phone number.
A username is an optional, unique name a WhatsApp user can show in place of their phone number, and WhatsApp is rolling usernames out gradually.[1] Our guide to WhatsApp usernames for business covers what changes for customers and the teams that answer them.
Meta requires every partner and directly integrated business on the WhatsApp Business Platform to support BSUIDs, and the requirement extends to click-to-WhatsApp advertisers.[2] BSUIDs have appeared in webhooks since early April 2026. On the Cloud API, the value sits in the user_id field of every messages webhook.
Store and send each BSUID in full, because a request with a missing or changed part fails. A database column for it needs room for the two-letter country code, the period, and up to 128 letters and digits after it. Each BSUID works inside one business portfolio, formerly called Business Manager, and only that portfolio’s business phone numbers can message it. The same customer therefore has a different BSUID in each portfolio.
When Does the API Still Return a Customer’s Phone Number?
Webhooks still carry a customer’s phone number when that business phone number exchanged a message or call with the customer in the last 30 days, or when the customer is in the business’s Contact Book. Knowing which case applies tells a team which conversations need BSUID handling first.
Five situations decide which identifiers a webhook carries, per Meta’s BSUID documentation.
| Situation | Phone Number | BSUID |
|---|---|---|
| Customer has no username | Included | Included |
| Customer has a username, and this business number sent or received a message or call with them in the last 30 days | Included | Included |
| Customer has a username and is in the portfolio’s Contact Book | Included | Included |
| Customer has a username and shares their number with the Request Contact Info button | Included in a contacts webhook | Included |
| Customer has a username and meets none of the conditions above | Omitted | Included |
The 30-day check runs per business phone number, while the Contact Book covers the whole portfolio. A returning customer outside both can look like a new thread. Calls count the same as messages, including calls made through the WhatsApp Calling API. A conversation that starts from click-to-WhatsApp ads follows the same conditions.
How Does the Contact Book Work in the API?
The Contact Book is a list Meta hosts for each business portfolio, and it stores a customer’s phone number next to their BSUID once the customer and the business exchange a message or call. While a customer stays in it, webhooks keep carrying their phone number after the 30-day window closes. Two API calls let an integration check and remove single entries.
The Contact Book needs no setup, and entries stay until the business switches the feature off in Meta Business Suite, under Business settings > Business info, or deactivates its account. Switching it off deletes every entry for good. It records only interactions from after Meta launched it, and its phone numbers appear in webhook payloads only.
Meta added the check call on August 24, 2026, and changed the delete call’s response on August 25, 2026.[3] Both calls take one standard BSUID and reject parent BSUIDs.
| Call | Request | Response |
|---|---|---|
| Check | GET /<BUSINESS_PHONE_NUMBER_ID>/contact_book?messaging_product=whatsapp&bsuid=<BSUID> | contacts with bsuid and present (true or false), never the phone number |
| Delete | DELETE on the same path | success and deleted, with deleted set to false for any BSUID without an entry |
A false deleted value looks the same for an unknown BSUID, an invalid one, and one from another portfolio. After a deletion, the phone number can still appear within the 30-day window or after a new interaction.
How Do You Request a Phone Number With the Request Contact Info Button?
The Request Contact Info button asks a customer to share their phone number in the chat, and the number comes back in a contacts webhook next to the BSUID. It lets any flow that needs a phone number collect it inside the conversation, with the customer’s consent.
The button has been available since early July 2026 on utility and marketing templates, and on an interactive message. A number shared this way also enters the Contact Book automatically when the business uses it. Meta’s guidance asks bots that need a number to request it and to handle customers who decline.
How Do You Send Messages to a BSUID?
A business sends a message to a BSUID through the same send request it uses for phone numbers, with the BSUID in a field of its own. Messaging by BSUID lets a business keep talking to customers whose phone number it never received.
Meta dates BSUID sending from July 2026. A request names the customer by phone number, by BSUID, or by both, and the phone number takes precedence when both are present.
Every message type works with a BSUID except one-tap, zero-tap, and copy code authentication templates, which still need a phone number. The Marketing Messages API accepts BSUIDs too, and Meta recommends phone numbers there because webhooks then keep returning the number.
Our Usernames and BSUID documentation shows the full send request, response, and error codes on the 360Dialog API.[4]
What Changes in Webhooks?
Webhooks now carry the customer’s BSUID in every incoming message and in sent, delivered, and read statuses, and the phone number appears only when one of Meta’s phone number conditions applies. A parser that treats the BSUID as the required identifier keeps processing every message.
The BSUID sits next to the phone number in the same payloads, in fields of its own. The phone number fields appear when the customer has no username, when a phone number condition applies, or when the message went to a phone number, and the customer’s username arrives as a profile detail when they have one. Fields that do not apply are left out of the payload.
A phone number change gives the customer a new BSUID, reported on the messages webhook as a system message of type user_changed_number or user_changed_user_id. Both carry previous_user_id, the old BSUID. An integration uses it to find the customer record already on file. Meta documents no separate user_id_update webhook field.
How Do You Manage a Business Username Through the API?
A business sets, reads, and deletes each business phone number’s username through Meta’s Username API, which also reports status changes by webhook. Building these calls into a platform lets a team track usernames for many numbers in one place.
A business can set or change a username for each business phone number, read its status, approved or reserved, and delete it, and a suggestions call returns reserved names with a higher chance of approval. An approved username becomes active once usernames are available in the business’s country. 360Dialog clients do this with the business username endpoints in our API reference.[5]
Each business phone number can set 2 new usernames in any rolling 14-day period, or 10 when the result has reserved status, and a request over the limit fails. The count is kept per number, and deleting a username leaves it unchanged.
The business_username_updates webhook, which each app subscribes to, reports approved, deleted, and reserved statuses. When Meta revokes a username, the webhook says so, and the username is either deleted or replaced with a generated one.
How Do Parent BSUIDs Work Across Multiple Portfolios?
A parent BSUID is one identifier per customer that every business portfolio enrolled in the same parent BSUID account can use. It lets a managed business with several portfolios recognize the same customer across all of them.
Meta offers parent BSUIDs to managed businesses, and the business’s Meta point of contact checks eligibility. Webhooks then carry the parent BSUID next to the regular BSUID, in parent_user_id, from_parent_user_id, and recipient_parent_user_id. A parent BSUID adds ENT after the country code, and any business phone number in an enrolled portfolio can message it.
Enrollment leaves each portfolio’s access controls, billing, and administration unchanged. Contact Books stay separate per portfolio. To list enrolled portfolios, a business calls GET https://api.facebook.com/<BUSINESS_ID>/parent-bsuid-accounts, which returns parent_bsuid_account_id and enrolled_business_portfolios.
Platforms that run a multi-tenant WhatsApp integration keep each client’s BSUIDs inside that client’s portfolio.
What Should Your Integration Handle Now?
An integration ready for BSUIDs stores the BSUID as a core customer identifier, treats the phone number as optional, and asks for a number only where a flow needs one. These changes keep every conversation tied to the right customer record.
In practice, webhook parsers and database columns accept messages that carry only a BSUID, and each customer record keeps the BSUID next to the phone number. CRM, campaign, measurement, and billing systems then match customers on the BSUID as well. Flows that need a number ask for it with the Request Contact Info button and keep a path for customers who decline, and Meta’s webhook test tool checks the parser against each case. Teams planning AI-assisted replies can read how the AI agent works with the API in our complete guide to Meta Business Agent. Once every system keys customers on the BSUID, each conversation lands in the customer record it belongs to, and the agent answering it sees the full history.
360Dialog is an Official Meta Solution Partner for the WhatsApp Business API, and our Usernames and BSUID documentation gives the step-by-step integration checklist with the send requests and webhook payloads on the 360Dialog API. Get API access to build and test BSUID handling on your own WhatsApp Business API number. Talk to us about preparing your WhatsApp Business API integration for BSUIDs.
Frequently Asked Questions
Can a Business Message a Customer by Their Username?
A business cannot use a username as a message address on the WhatsApp Business API. Send requests accept a phone number in the to field or a BSUID in the recipient field. The username reaches the business in webhooks as a profile detail, and the customer can change it at any time. The BSUID stays the same through that change and is the identifier to store.
Are Authentication Messages Still Sent to Phone Numbers?
One-tap, zero-tap, and copy code authentication templates still go to the customer’s phone number, and sending one to a BSUID fails with error 131062. A business that holds only a BSUID can first ask for the number with the Request Contact Info button. Once the customer shares it, the business sends the authentication template to that number.
How Do You Test a Webhook Handler for BSUIDs?
Meta’s webhook test tool sends sample BSUID payloads to a webhook handler from the App Dashboard. Open Use cases, then Connect with customers through WhatsApp, Customize, and Configuration, and select Test next to the messages field. The tool covers four cases: no username, a username without a phone number, a username with a phone number, and a payload with a parent BSUID.
Do Partners Need to Update Client Integrations for BSUIDs?
Partners on the WhatsApp Business Platform must support BSUIDs, and Meta applies the same requirement to directly integrated businesses and click-to-WhatsApp advertisers. A partner’s app can message a client’s BSUIDs from the client’s own business phone numbers. Using a client’s BSUID with the partner’s own number fails, because each BSUID belongs to one business portfolio.
Sources
[1] WhatsApp Help Center, “About usernames,” https://faq.whatsapp.com/658755553162769/ (accessed October 29, 2026).
[2] Meta for Developers, “Business-scoped user IDs,” updated October 23, 2026, https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/ (accessed October 29, 2026).
[3] Meta for Developers, “Changelog,” https://developers.facebook.com/documentation/business-messaging/whatsapp/changelog/ (accessed October 29, 2026).
[4] 360Dialog documentation, “Usernames & BSUID,” https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-bsuid (accessed October 29, 2026).
[5] 360Dialog documentation, “Business Username,” https://docs.360dialog.com/docs/messaging-api/api-reference/business-username (accessed October 29, 2026).
