BSUID API and Sending Changes

This page covers API request and response changes for BSUID support. For webhook payload changes, see BSUID webhook changes.

Messages API

Messages API requests add recipient, which accepts a BSUID or parent BSUID.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<USER_PHONE_NUMBER>",
  "recipient": "<BSUID>",
  "type": "text",
  "text": {
    "body": "Hello"
  }
}

Rules:

• Use to to send to a phone number.
• Use recipient to send to a BSUID or parent BSUID.
• If both to and recipient are present, to takes precedence.
• Meta recommends sending to phone numbers when possible so phone-number fields can continue appearing in webhooks.

Response changes:

If you send both to and recipient, the response follows the phone-number path because to takes precedence.

Marketing Messages API

The Marketing Messages API for WhatsApp also supports to and recipient.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<USER_PHONE_NUMBER>",
  "recipient": "<BSUID>",
  "type": "template",
  "template": {
    "name": "<TEMPLATE_NAME>",
    "language": {
      "code": "en_US"
    }
  }
}

The same precedence applies: to wins over recipient. Response fields mirror the Messages API response, with messages[].message_status included for Marketing Messages API pacing.

Unsupported Message Types

Meta adds error code 131062 for unsupported BSUID recipients:

One-tap, zero-tap, and copy-code authentication templates still require phone numbers. Do not send those templates to BSUIDs.

Groups API

Group API responses add BSUID fields while making phone numbers conditional.

GET group info and join-request responses can include:

• wa_id when phone number can be included,
• user_id,
• parent_user_id when enabled,
• username when the user has adopted a username.

Remove participant requests can use either user or user_id, but not both:

{
  "messaging_product": "whatsapp",
  "participants": [
    {
      "user_id": "US.13491208655302741918"
    }
  ]
}

Block Users API

Block and unblock requests support phone numbers or regular BSUIDs.

{
  "messaging_product": "whatsapp",
  "block_users": [
    {
      "user_id": "US.13491208655302741918"
    }
  ]
}

Rules:

• Use user for phone numbers.
• Use user_id for regular BSUIDs.
• If both are provided, user takes precedence.
• Parent BSUIDs are not supported for block or unblock requests.

Responses can include input, wa_id, and user_id. wa_id is omitted when the request used a BSUID and Meta cannot include the phone number.

GET blocked users can return wa_id, user_id, and parent_user_id when enabled and available.

Calling API

Business-initiated call requests add recipient:

{
  "messaging_product": "whatsapp",
  "to": "<USER_PHONE_NUMBER>",
  "recipient": "<BSUID>",
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<SDP>"
  }
}

Rules match messaging:

• to calls a phone number.
• recipient calls a BSUID or parent BSUID.
• If both are present, to takes precedence.

Call permission lookup can use user_wa_id for phone numbers or recipient for BSUIDs and parent BSUIDs.

Calling webhooks add user identifier fields such as from_user_id, to_user_id, recipient_user_id, and parent equivalents. See BSUID webhook changes.

SIP Signaling

SIP signaling can carry BSUIDs in places that previously carried phone numbers:

• SIP request URI or To / From values can include the BSUID or parent BSUID when the call used that identifier.
• User-initiated SIP messages can include x-wa-meta-user-id, x-wa-meta-parent-user-id, and x-wa-meta-username.

If you terminate SIP yourself, update SIP identity parsing and logging so BSUID-formatted identifiers do not fail phone-number validation.

Dualhook Boundary

Dualhook is not in your /messages, /marketing_messages, Groups API, Block Users API, Calling API, or SIP send path. These changes belong in your application code and downstream systems.

Dualhook's role is to configure direct routing and provide operational documentation. Your backend must choose when to use to, when to use recipient, and how to store the returned identifiers.