BSUID in Webhooks

BSUID in Webhooks

Every event relayed to your webhook endpoint now carries the BSUID alongside the phone number, in a different property depending on the direction of the message. Both properties live inside the Base64-encoded content of the event.

The two new properties

Direction	Property	Meaning
MT (outbound)	ToBsuid, next to To	BSUID of the recipient of the message you sent
MO (inbound)	FromBsuid, next to From	BSUID of the customer who wrote to you

Rule of thumb: the MT event carries the BSUID of who you write to (ToBsuid); the MO event carries the BSUID of who writes to you (FromBsuid).

The phone number may be missing

Both properties are omitted from the JSON when empty, exactly like To and From. This is not a cosmetic detail:

• Meta omits the phone number (wa_id, from) once the user has enabled their username, unless you interacted in the last 30 days or the number is already in the contact book Meta keeps for you.
• As a result, a conversation held entirely over a username arrives with ToBsuid / FromBsuid present and without To / From.

Important: your integration must not assume the phone number is always present, and must not use it as the primary key of the contact. If your system breaks today when From arrives empty, that is the pending work.

Example: MO event content

Code
{
  "FromBsuid": "MX.1513909853481480",
  "To": "5215512345678",
  "ContactName": "Ana",
  "MessageContent": {
    "text": "Hello"
  }
}

Note there is no From property: that customer did not share their phone number.

Sensitive messages

Events flagged as sensitive are relayed without the BSUID. If your process depends on that identifier, handle this case.

Inbound contact event

When you send a customer a Share contact info template and they tap the button, WhatsApp shares their phone number in the conversation thread. That arrives as an inbound (MO) event.

The same event type is produced when the customer shares a contact card in the chat on their own, without you asking. The two are told apart by the Origin property.

Field	Value
Event category	Contact
Category type	MO (inbound)
Origin	contact_request if it came from the button; other if the customer shared it on their own

Important: only Origin = contact_request is a reply to your template. If you segment by origin, do not mix the two cases.

What the payload contains

Origin	Content
contact_request	The customer's phone number. Meta does not include the vCard in this case.
other	The full contact card: name, company, phones, emails, addresses and URLs.

Important: do not design your process around fields that will not arrive. If what you need is the phone number, that one does arrive in both cases.

The contact is delivered as data, not as a stored profile. Persisting the received phone number and linking it to the BSUID you already had is the responsibility of the system consuming the webhook.

Once you hold both identifiers for the same customer, you can keep using the phone number for everything the BSUID does not cover — for example the one tap, zero tap and copy code authentication templates.

See Contacts for the full contact payload, and Troubleshooting for known limitations.