Recipient Identifiers

Recipient Identifiers

Every WhatsApp send method takes the recipient in the same to field. That field now accepts two kinds of value: a phone number (MSISDN) or a BSUID. The platform inspects the value you send, classifies it and builds the correct payload for Meta.

BSUID format

A BSUID is made of the country code (ISO 3166 alpha-2), a dot and an alphanumeric string:

Code
MX.1513909853481480
US.13491208655302741918

Parent identifiers, at business portfolio level, also include the ENT. segment:

Code
US.ENT.11815799212886844830

Important: use the value complete and unmodified, including the country code and the dot. If you trim, normalize or reformat the BSUID, the send fails.

Validation rules

Any value that matches neither format is rejected with a validation error before it reaches Meta.

How it is translated for Meta

Note: in Meta's API, if to and recipient are both sent, the phone number takes precedence. Our platform never sends both: it classifies the value and fills in only the matching one.

Identifier scope

• The BSUID is scoped to your business portfolio. Any number in your portfolio can message that BSUID; a number from another portfolio fails.
• The BSUID applies to WhatsApp only. SMS and RCS always use a phone number.
• The BSUID is regenerated if the user changes their phone number. Meta notifies you with a system webhook; if you store the BSUID, you must handle the update.

Request example

The body is exactly the one you already use. Only the value of to changes.

EndPoint (URL)

Code
/api/v1/WhatsApp/messages

HTTP Method

Code
{
  "from": "5215512345678",
  "to": "5215598765432",
  "content": {
    "type": "text",
    "body": "Your order is on its way."
  }
}

Note: there is no bsuid field and no recipientType field. The same field covers both cases and the platform tells them apart.

Continue with BSUID in Webhooks.