Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Business-scoped user IDs

A business-scoped user ID (BSUID) lets you message a WhatsApp user without their phone number. It identifies the user within your Meta business portfolio.

WhatsApp usernames

WhatsApp users with a username can message you without sharing their phone number. Their messages include from.bsuid; from.phone_number may be missing. Users without a username can also have a BSUID.

Meta includes the phone number if the user is in your Meta contact book or has exchanged messages or calls with your business number in the past 30 days. The 30-day rule applies per business number.

from.username and from.display_name are optional. You cannot send messages to either value.

BSUID format

A BSUID has an uppercase ISO 3166 alpha-2 country code, a period, and up to 128 letters or digits. For example: US.13491208655302741918.

Store and send the full value unchanged. Use a sender number from the same business portfolio. Meta rejects messages sent from other portfolios.

A BSUID changes when the user changes their phone number, so store it under your own customer ID.

A parent BSUID works across portfolios enrolled by a managed business. It adds ENT. after the country code: US.ENT.11815799212886844830. The 128-character limit applies to the part after ENT.. Bird accepts both formats.

Request a phone number

These message API examples show only the fields needed for this exchange.

1. The user messages you

This message includes the user's BSUID but no phone number.

You have 24 hours to reply without a template.

Code example
{
  "direction": "inbound",
  "from": {
    "bsuid": "US.13491208655302741918"
  },
  "to": {
    "phone_number": "+14155550100"
  },
  "text": {
    "body": "Can I book a repair?"
  }
}

2. Ask for their number

Send a contact info request to the BSUID. WhatsApp shows a button for sharing a phone number.

Outside the 24-hour window, send a template with a request_contact_info button.

Code example
{
  "direction": "outbound",
  "from": {
    "phone_number": "+14155550100"
  },
  "to": {
    "bsuid": "US.13491208655302741918"
  },
  "interactive": {
    "type": "request_contact_info",
    "body_text": "Share your number."
  }
}

3. The user taps the button

You receive a contact card with origin: "contact_request" and the shared number in phone_numbers.

In this reply, from also includes the user's phone number.

Code example
{
  "direction": "inbound",
  "from": {
    "bsuid": "US.13491208655302741918",
    "phone_number": "+14155550101"
  },
  "contact_cards": [
    {
      "origin": "contact_request",
      "phone_numbers": [
        {
          "phone_number": "+14155550101"
        }
      ]
    }
  ]
}

If the user dismisses the request, you receive no message or webhook. Set a timeout so your app can continue without the number.

Send a message

Set to to the BSUID and from to your WhatsApp business number:

Code example
{
  "to": "US.13491208655302741918",
  "from": "+14155550100",
  "text": { "body": "Your repair is booked." }
}

If the incoming message has only a BSUID, reply to that BSUID from the same business number. A phone number from your own records may have no open service window, causing 422 E15044.

  • Authentication templates require a phone number.
  • An invalid phone number or BSUID returns 422 E15001.
  • Message pricing depends on the BSUID's country code.

The customer service window also applies to BSUIDs. A 202 response means the API accepted your request. Check the message status to confirm delivery.

Find messages

On messages and webhooks, from identifies the sender and to identifies the recipient. Each can contain a phone_number, a bsuid, or both.

To list messages, filter by:

  • from or to for a sender or recipient, using their phone number or BSUID.
  • bsuid for messages sent to or received from the same WhatsApp user.

The phone_number filter is deprecated. Use from or to instead.

Related resources

Continue with the documentation, guides and examples for this topic.

Try the practice and get an implementation brief