Business-scoped user IDs (BSUID)

WhatsApp will gradually roll out usernames in 2026. To support them, Meta introduced a backend user identifier called Business-scoped user ID (BSUID), which uniquely identifies a WhatsApp user and is tied to a specific business. This document describes how these changes affect API requests, responses and webhook payloads.

The ISV channel supports the identifiers and capabilities introduced by the WhatsApp Business Platform for 2026: BSUID, Parent BSUID, usernames, Contact Book, contact requests and new webhook fields, without breaking compatibility with integrations that still use phone numbers.

Official Meta reference: Business-scoped user IDs.

Quick summary

Area	Change
Identifiers	`user_id` as BSUID, `parent_user_id` as Parent BSUID and `username` are supported.
Message sending	`/messages` and `/marketing_messages` accept `recipient` for BSUID or Parent BSUID.
Compatibility	The `to` field is preserved. If both `to` and `recipient` are sent, the phone number in `to` takes priority.
Templates and interactive	Interactive messages and templates with `REQUEST_CONTACT_INFO` are supported.
Calls	Fields such as `to_user_id`, `to_parent_user_id`, `from_user_id` and `from_parent_user_id` are preserved.
Webhooks	New fields received from Meta are exposed, even when no phone number is present.
Business Username	Endpoints to query, adopt/change and delete the business username were added.
Contact Book	An endpoint to delete contacts by BSUID was added.

Supported identifiers

Field	Description
`to`	User phone number. Preserved for compatibility.
`recipient`	BSUID or Parent BSUID used as destination in outbound messages.
`user_id`	Business Scoped User ID (BSUID) of the user.
`parent_user_id`	Parent BSUID of the user when the client is enrolled.
`username`	Username of the user or business, depending on the payload context.
`from_user_id`	BSUID of the sender in inbound messages/webhooks.
`from_parent_user_id`	Parent BSUID of the sender in inbound messages/webhooks.
`recipient_user_id`	BSUID of the destination in status webhooks.
`recipient_parent_user_id`	Parent BSUID of the destination in status webhooks.

BSUID format

BSUIDs are generated automatically, prefixed with the user’s ISO 3166 alpha-2 country code and a period, followed by up to 128 alphanumeric characters. For example: US.13491208655302741918.

Parent BSUIDs follow the same format but include ENT between the country code and the identifier. For example: US.ENT.11815799212886844830.

Sending messages with `recipient`

The existing message endpoints preserve the previous contract and add BSUID/Parent BSUID support through recipient.

Endpoint	Change
`POST /{v}/{did}/messages`	Allows sending messages using `to`, `recipient` or both.
`POST /{v}/{did}/marketing_messages`	Allows sending marketing messages using `recipient`.

Message using BSUID

Request

POST /{v}/{did}/messages

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/v21.0/{did}/messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "recipient": "CL.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hello, this message is sent using BSUID."
    }
  }'

Message using phone number and BSUID

When both fields are provided, to keeps priority to preserve historical behavior.

Request

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/v21.0/{did}/messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+56912345678",
    "recipient": "CL.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hello, this message keeps compatibility with to."
    }
  }'

Interactive message to request contact information

Request

POST /{v}/{did}/messages

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/v21.0/{did}/messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "recipient": "US.13491208655302741918",
    "type": "interactive",
    "interactive": {
      "type": "request_contact_info",
      "body": {
        "text": "Share your number to continue."
      },
      "action": {
        "name": "request_contact_info"
      }
    }
  }'

Templates with `REQUEST_CONTACT_INFO`

The templates endpoint allows creating templates that request contact information from the user through a REQUEST_CONTACT_INFO button (available in utility and marketing categories).

Endpoint	Change
`POST /message_templates/{v}/{did}`	Allows `REQUEST_CONTACT_INFO` button types.

Request

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/v21.0/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "request_contact_info_template",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Share your phone number to continue."
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "REQUEST_CONTACT_INFO"
          }
        ]
      }
    ]
  }'

REQUEST_CONTACT_INFO buttons cannot be customized: the label is rendered automatically in the recipient’s language, so no parameters need to be sent when sending the template.

Business Username and Contact Book endpoints

These endpoints are exposed under /business_identifiers/{version}/{did}. They require the same authentication and channel validation as protected ISV endpoints.

Operation	Endpoint	Description
Get username	`GET /business_identifiers/{v}/{did}/username`	Queries the username associated with the business number.
Adopt or change username	`POST /business_identifiers/{v}/{did}/username`	Sends the payload required by Meta to adopt or change the username.
Delete username	`DELETE /business_identifiers/{v}/{did}/username`	Deletes the username associated with the business number.
Username suggestions	`GET /business_identifiers/{v}/{did}/username_suggestions`	Gets available username suggestions.
Parent BSUID Accounts	`GET /business_identifiers/{v}/{did}/parent-bsuid-accounts?business_id={business_id}`	Queries the Parent BSUID accounts associated with the business.
Delete Contact Book	`DELETE /business_identifiers/{v}/{did}/contact_book?bsuid={BSUID}`	Deletes a contact from the book using its BSUID.

Adopt or change username

Request

POST /business_identifiers/{v}/{did}/username

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/business_identifiers/v21.0/{did}/username' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "my.business"
  }'

Response

Success (200)

{
  "status": "approved"
}

status can be approved (approved and visible) or reserved (reserved, not yet visible until the feature is available).

Username errors

Code	Description
`147001`	Username not available (already claimed or fails internal checks).
`147002`	Account not eligible to request a username (requires a higher messaging limit).
`147003`	Facebook account not linked to the number.
`147004`	Instagram account not linked to the number.
`147005`	Username transfer required (in use by another number in the same portfolio).

Delete contact by BSUID

Request

DELETE /business_identifiers/{v}/{did}/contact_book?bsuid={BSUID}

curl --request DELETE \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/business_identifiers/v21.0/{did}/contact_book?bsuid=US.13491208655302741918' \
  --header 'Authorization: <JWT>'

Response

Success (200)

{
  "messaging_product": "whatsapp",
  "success": true,
  "deleted": true
}

success — true if the request was processed successfully.
deleted — true if the entry existed and was deleted; false if no entry was found for that BSUID.

New fields in webhooks

Webhooks preserve the new fields sent by Meta. This allows receiving events even when the phone number is not present in the payload.

Webhook	Relevant fields
`messages`	`user_id`, `parent_user_id`, `username`, `from_user_id`, `from_parent_user_id`.
`statuses`	`recipient_user_id`, `recipient_parent_user_id`, `username`.
`contacts`	`origin`, `vcard`, `from_user_id`, `from_parent_user_id`.
`system`	Number changes that may imply a BSUID change.
`business_username_updates`	Business username status changes.
`user_preferences`	User preferences, including BSUID/Parent BSUID identifiers when Meta reports them.

Example of a message received with BSUID

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Sheena Nelson",
                  "username": "realsheenanelson"
                },
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.11815799212886844830"
              }
            ],
            "messages": [
              {
                "from_user_id": "US.13491208655302741918",
                "from_parent_user_id": "US.ENT.11815799212886844830",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
                "timestamp": "1749416383",
                "type": "text",
                "text": {
                  "body": "Does it come in another color?"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Example of a business username update

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "business_username_updates",
          "value": {
            "display_phone_number": "15550783881",
            "username": "mybusiness",
            "status": "approved"
          }
        }
      ]
    }
  ]
}

Calls

The call endpoints preserve the new user fields when Meta requires or delivers them in the payload. See Official API (CALLING) for details.

Endpoint	Relevant fields
`POST /calls/{v}/{did}/signaling`	`to_user_id`, `to_parent_user_id`, `from_user_id`, `from_parent_user_id`.
`GET /calls/{v}/{did}/call_permissions`	Allows querying by `user_wa_id` and also preserving `user_id` when sent as a query param.

New or relevant errors

Code	Message	When it occurs
`131062`	`BSUID recipients are not supported for this message`	Meta rejects a message sent with BSUID for a message type that does not support it.
`147001` to `147005`	Username API errors	Meta rejects username operations due to format, availability, eligibility or business rules.

Groups API and Block Users API

The ISV also supports Meta’s Groups and Block Users APIs (groups, join requests, participants, and blocking/unblocking users). See Meta’s documentation for the behavior of these capabilities.

Compatibility

The microservice keeps compatibility with existing integrations because payloads are preserved towards Meta and towards the webhooks configured by the ISV. Integrations that still operate with phone numbers can continue using to; integrations that adopt BSUID or Parent BSUID can use recipient and the new webhook fields.

Official API (CALLING)

Business-scoped user IDs (BSUID)

Quick summary

Supported identifiers

BSUID format

Sending messages with recipient

Message using BSUID

Request

Message using phone number and BSUID

Request

Interactive message to request contact information

Request

Templates with REQUEST_CONTACT_INFO

Request

Business Username and Contact Book endpoints

Adopt or change username

Request

Response

Success (200)

Username errors

Delete contact by BSUID

Request

Response

Success (200)

New fields in webhooks

Example of a message received with BSUID

Example of a business username update

Calls

New or relevant errors

Groups API and Block Users API

Compatibility

Sending messages with `recipient`

Templates with `REQUEST_CONTACT_INFO`