Meta BSUID Changes in WhatsApp Webhooks | MyOperator

How do I handle Meta's BSUID change in my WhatsApp webhook?

To handle Meta's BSUID change in your WhatsApp webhook, update your integration so it can store and process either a phone number or the new Business-Scoped User ID (BSUID) in the customer_identifier field and capture the additional meta_bsuid and meta_username fields.

What the BSUID is and why it matters

Meta is rolling out a Business-Scoped User ID (BSUID) for WhatsApp users in India. After the rollout, Meta may omit the customer’s mobile number and instead place the BSUID in customer_identifier. The BSUID consists of a two-letter country code, a dot, and a 128-character alphanumeric string, for example IN.3243412413241241. If your systems validate customer_identifier strictly as a phone number, WhatsApp events that contain only a BSUID will fail to reach you unless you adjust your logic.


Who needs to act

  • Only customers who receive WhatsApp Business API (WABA) events from MyOperator through a webhook must change their code.
  • If you do not use a WhatsApp webhook, no action is required.
  • Call webhooks are not affected; their payloads continue to carry the caller’s phone number exactly as today.
  • If an external developer or agency maintains your integration, forward this information to them.

Field-level changes in the WABA webhook

FieldWhereTodayAfter BSUID rollout
customer_identifierEnvelope rootCustomer phone number in E.164Phone number in E.164; the BSUID (not E.164) if and only if the phone number is missing
meta_bsuidconversation object in each payloadNot presentNew. BSUID as received from Meta
meta_usernameconversation object in each payloadNot presentNew. WhatsApp username as received from Meta

Webhook events affected

EventMethod
message.receivedPOST
message.sentPOST
message.deliveredPOST
message.readPOST
message.failedPOST
message.link_trackingPOST
conversation.assignPOST
conversation.closePOST

The conversation object in every event listed above now carries meta_bsuid and meta_username.


How customer_identifier is resolved

What Meta sendscustomer_identifiermeta_bsuidmeta_username
Phone number only (no BSUID rollout yet)Phone numberAbsentAbsent
Phone number and BSUIDPhone numberBSUIDUsername, if the user has set one
BSUID only (phone number missing)BSUIDBSUIDUsername, if present

Whenever Meta supplies a phone number, it takes precedence. The BSUID is used only when the phone number is missing, and the new meta_ fields are forwarded unchanged in every case.


Required changes to your integration

  • Accept customer_identifier values that can be either all digits (phone number) or an alphanumeric BSUID that may contain a dot.
  • Store meta_bsuid with each contact record when it is present so you can recognise the same customer in future events, whether the identifier is a phone number or a BSUID.
  • Increase the length limit of customer_identifier to at least 131 characters.
  • Do not change anything in your call webhook handling; those payloads remain exactly the same.

Sample payload with a phone number

{
"company_id" : "69ddcadb46536124",
"event_id" : "event-6576745fc0df84a7d230bfae2d1d8f3bd51fd0428d1001150755b15a265219c37f0b0770",
"event_type" : "message.received",
"event_sequence" : 1,
"event_version" : "1",
"timestamp" : "2026-04-20T10:06:07.835252916Z",
"channel" : "whatsapp",
"direction" : "incoming",
"session_id" : "e8e99f13-f41e-4655-b393-09e03cb5f91c",
"system_identifier" : "1196177000238423",
"customer_identifier" : "917779812955",
"payload" : {
"id" : "1975ec0a-67fe-4a37-af4b-4ed7449862ab",
"action" : "incoming",
"status" : "received",
"data" : {
"type" : "text",
"context" : { "body" : "Offer" }
},
"conversation" : {
"id" : "e8e99f13-f41e-4655-b393-09e03cb5f91c",
"customer_country_code" : "91",
"customer_contact" : "7779812955",
"customer_name" : "Suraj Singh",
"meta_bsuid" : "IN.3243412413241241",
"meta_username" : "suraj",
"status" : "assigned"
},
"phone_number_id" : "1196177000238423",
"mode" : "lc",
"source" : "lc"
}
}

If Meta omits the phone number, the payload is identical except that customer_identifier holds the value IN.3243412413241241, matching payload.conversation.meta_bsuid.


Timeline and next steps

As of October 2026, Meta still provides the mobile number for Indian users, so your current setup continues to work for now. Meta has not announced an exact go-live date and may provide only short notice. Update and test your integration ahead of time to avoid any disruption.


Need help?

Email support@myoperator.com or call +91 81029 81029 if you need additional sample payloads or assistance testing the new behaviour.


Keywords

BSUID, Business-Scoped User ID, WhatsApp webhook, WABA webhook, customer_identifier, meta_bsuid, meta_username, Meta, phone number, integration update, conversation object, MyOperator