Log inStart Free Trial
Meta Tech Provider

WhatsApp usernames and business-scoped user IDs (BSUID): what changes in Cloud API webhooks

WhatsApp usernames let users show a name instead of their phone number, so since early April 2026 Cloud API messages webhooks also carry a business-scoped user ID (BSUID), such as US.13491208655302741918, in user_id and from_user_id. For a user with a username who has had no message or call with the number in 30 days and is not in the contact book, wa_id and from are left out.

easyCoexistence connects a WhatsApp Business app number to the Cloud API through Coexistence and routes its messages and smb_message_echoes webhooks to your endpoint as Meta sends them, BSUID fields included, while get_api_credentials gives your code what it needs to reply with recipient.

April 2026

When BSUIDs began appearing in Cloud API webhooks, ahead of usernames reaching WhatsApp users.

July 2026

When the APIs began accepting messages sent to a BSUID, set in recipient instead of to.

30 days

Lookback, per business phone number, in which any message or call with the user keeps their number in webhooks.

128

Most alphanumeric characters after a BSUID's two-letter country code and period.

131062

Messages API error: Business-scoped User ID (BSUID) recipients are not supported for this message.

user_changed_user_id

System message type for a BSUID change reported without a phone number, with the old BSUID in previous_user_id.

What are WhatsApp usernames and BSUIDs?

A username is an optional, unique name a WhatsApp user can set, shown in the app instead of their phone number; Meta is rolling usernames out gradually in 2026. A BSUID is the backend identifier Meta added so businesses can still tell users apart: generated automatically, unique to each business portfolio and user pair, and written as the user's ISO 3166 two-letter country code, a period and up to 128 alphanumeric characters. Meta requires partners and directly integrated businesses to support it, since no business controls whether its users adopt usernames.

Which fields carry the new identifiers?

New properties beside the ones that held the phone number, across the messages, status, system and user_preferences webhooks. The parent fields appear only for business portfolios Meta has enrolled in parent BSUIDs, which work across the enrolled portfolios:

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

When is the phone number left out?

When the user has a username and none of Meta's three conditions holds. The number stays in webhooks if the business phone number messaged or called that user's number in the last 30 days, received a message or call from it in that time, or the user is in the portfolio's contact book. The 30-day lookback is counted per business phone number, so a second number in the same portfolio may receive only the BSUID for the same user. Users without a username keep arriving with both their phone number and their BSUID.

What does an incoming message look like now?

Like before, with the BSUID beside the phone number or in its place. In Meta's example of a user with a username whose number cannot be shared, contacts carries profile.name, profile.username and user_id, and the message carries from_user_id where from used to be:

messages webhook: a text from a user known only by BSUID
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
        "contacts": [{
          "profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
          "user_id": "US.13491208655302741918"
        }],
        "messages": [{
          "from_user_id": "US.13491208655302741918",
          "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
          "timestamp": "1749416383",
          "type": "text",
          "text": { "body": "Does it come in another color?" }
        }]
      }
    }]
  }]
}

How do status webhooks change?

Sent, delivered and read statuses gain a contacts array with the user's name, user_id, wa_id when the number can be shared, and username on delivered and read. In statuses, recipient_user_id carries the BSUID, and recipient_id is left out when you sent to a BSUID and the number cannot be shared. A failed status has no contacts array and omits recipient_user_id when the message went to a phone number, so tie failures to the message id.

How should you store and match users?

By BSUID first, with the phone number as a second key whenever it arrives. Store the whole BSUID as a string, country code and period included, since Meta rejects requests that alter any part of it, and store the parent BSUID too if your portfolios are enrolled. Join existing records on wa_id while it still arrives and keep the BSUID beside them, because a user who adopts a username later may come back without a number. Meta's FAQ asks for the same joins in CRMs and in the tools they feed.

What happens when a user changes their phone number?

Their BSUID is regenerated, and the change arrives on the messages field as a system message, since Meta has no user_id_update field to subscribe to. system.type is user_changed_number when the new number can be shared with you, or user_changed_user_id when only the BSUID change can be reported; system.user_id holds the new BSUID and system.previous_user_id the old one, which is how a record carries over. Handle both types.

How do you reply to a user known only by a BSUID?

Send to /<BUSINESS_PHONE_NUMBER_ID>/messages with recipient set to the BSUID and to left out; with both present, to wins and the reply goes to the phone number. The response's contacts entry then carries input and user_id rather than wa_id. Any message type works except one-tap, zero-tap and copy code authentication templates, which need a phone number, and only numbers in the same business portfolio can reach a BSUID. Error 131062 means the message type does not accept BSUID recipients.

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a BSUID
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "US.13491208655302741918",
  "type": "text",
  "text": { "body": "Yes, it also comes in blue." }
}

How do you ask a user for their phone number?

With the REQUEST_CONTACT_INFO button, added to a utility or marketing template or sent as an interactive message of type request_contact_info. A user who taps it shares their number in the thread, and a contacts webhook arrives with origin set to contact_request and the number in phones[].wa_id; a contact shared by hand arrives with origin other and a vCard. Meta made the button available in early July 2026, and its label cannot be customized.

What is the contact book?

A store Meta hosts for each business portfolio, with no integration work: once a business phone number messages, calls or hears from a user's phone number, that number and the BSUID are recorded and used to fill later webhooks with the phone number, username or not. Only interactions after its launch count. It can be turned off in Meta Business Suite, Business settings, Business info, which deletes what it holds, and GET or DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book with a bsuid checks or removes one entry.

What should a Coexistence integration change?

Its handling of the three webhooks only a Coexistence number gets, which change as well. In history, each thread gains a context object with wa_id, user_id and username, and its messages gain from_user_id. In smb_message_echoes, a contacts array is added, and message_echoes[].to can be left out while to_user_id carries the BSUID; edits and revokes made in the WhatsApp Business app arrive the same way. In smb_app_state_sync, a contact's phone_number can be left out, with user_id and username beside it. Match echoes and imported chats on user_id as well as the number.

How can you test before users adopt usernames?

With Meta's test tool in the App Dashboard: under Use cases, Connect with customers through WhatsApp, Customize, Configuration, the Test link beside the messages webhook sends a sample to your endpoint. It covers incoming messages and statuses in four scenarios:

  • A user without a username: BSUID and phone number fields, and no username.
  • A user with a username whose number is unavailable: username and BSUID, with no phone number fields.
  • A user with a username whose number is available: username, BSUID and phone number.
  • A portfolio enrolled in parent BSUIDs: a parent BSUID beside the portfolio's own BSUID.

How does easyCoexistence handle BSUIDs?

It passes them on as Meta sends them. A number routed to your endpoint with set_webhook_destination gets its messages and smb_message_echoes webhooks straight from Meta, user_id, from_user_id, to_user_id and username included, and with automations or forwarding on, easyCoexistence forwards the value Meta sent unchanged. To reply to a BSUID, your code uses get_api_credentials, which returns the number's phone number ID, its send endpoint and, when available, your own token; the send_message and send_template tools take a phone number in international digits.

Common mistakes

  • Keying contacts on wa_id alone. A user with a username who has had no contact with the number in 30 days arrives with only user_id and from_user_id, and a handler that requires wa_id misses the message.
  • Trimming a BSUID's country prefix. Meta wants the whole value, country code and period included, and a request with any part changed fails.
  • Waiting for a user_id_update field. Meta has none: BSUID changes arrive on messages as system messages of type user_changed_number or user_changed_user_id.
  • Matching Coexistence echoes on to only. In smb_message_echoes the to field can be left out, so a reply typed in the app goes unseen unless to_user_id is matched too.
Doing this with EasyCoexistence

Every connection is monitored 24/7. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Do users without a username get a BSUID too?

Yes. Meta sets user_id in messages webhooks whether or not the user has a username, so most users arrive with both their phone number and their BSUID.

Can a Coexistence number have a business username?

Yes. Since June 29, 2026 a business can adopt or change one in Meta Business Suite, WhatsApp Manager, the WhatsApp Business app or the Username API; it does not hide the business number, and business_username_updates reports each status change.

Does a BSUID work across business portfolios?

No. A BSUID belongs to one portfolio and user, and a number in another portfolio cannot message it. Managed businesses that Meta enrolls get parent BSUIDs, with ENT after the country code, that work across their enrolled portfolios.

How much does easyCoexistence cost for a WhatsApp number?

US$ 9 to US$ 0.75 per connection per month, depending on how many connections you have, and the first 3 days are free. Meta's own message charges stay on your WhatsApp Business Account's payment method.

Keep reading

Ready to get started?

Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.

Start Free Trial

Verified on