Skip to main content

WhatsApp usernames and BSUIDs

WhatsApp users can choose a username and hide their phone number from businesses. When a user does this, Meta identifies them to your business with a Business-Scoped User ID (BSUID) instead of a phone number. A BSUID looks like GB.13491208865530274191: a two-letter country code, a dot, and up to 125 letters and digits. It is unique to the user and your business, and Meta issues a new one if the user changes their phone number.

The webhook payloads have not changed shape. When Cue knows a customer's phone number, from and to contain the phone number as before. When the customer has hidden their number, they contain the BSUID instead. The BSUID is never sent alongside a known phone number, and the username is not included in webhooks.

info

Meta includes a username user's phone number only if your business messaged or called that number in the last 30 days, received a message or call from it in the last 30 days, or has the user in its Meta contact book. This is checked per business phone number.

Customer whose phone number is known​

Below is an example of an inbound message from a customer whose phone number Cue knows. This is unchanged, whether or not the customer has set a username. Outbound messages and status updates for this customer carry the phone number in to.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2026-09-22T09:14:03.412820993Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "text",
    "uuid": "ee01ade7-55ee-4024-a857-25bcf9c80e50",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2026-09-22T09:14:02.940940892Z",
    "to": "447418371579",
    "from": "447576209857", // Phone number
    "origin": "whatsapp",
    "chatType": "flow",
    "content": {
      "text": "Hi, is my order ready?"
    }
  }
}

Customer whose phone number is hidden​

Below are examples of webhook payloads for a customer who has hidden their phone number. The only difference is the value of from on inbound messages and to on outbound messages and status updates.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2026-09-22T09:14:03.412820993Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "text",
    "uuid": "ee01ade7-55ee-4024-a857-25bcf9c80e50",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2026-09-22T09:14:02.940940892Z",
    "to": "447418371579",
    "from": "GB.13491208865530274191", // BSUID
    "origin": "whatsapp",
    "chatType": "flow",
    "content": {
      "text": "Hi, is my order ready?"
    }
  }
}

A hidden-number customer becomes known by phone number when they share it, when you message their number, or when the 30-day window reopens. From then on their messages arrive with the phone number in from. Cue attaches the number to the same contact, and merges the contact into an existing one if the number was already known. An open conversation keeps its sessionUuid.

Requesting a phone number​

A flow can send a card with a Send contact info button. It goes out as a request_contact_info message. When the customer taps it, their number arrives as a contacts message. Customers can also share any contact card from their address book, and it arrives the same way.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2026-09-22T09:15:01.151959288Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "request_contact_info",
    "uuid": "ee02ee86-0963-498b-bae2-6eeb40558daa",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2026-09-22T09:15:01.151957417Z",
    "to": "GB.13491208865530274191",
    "from": "447418371579",
    "origin": "flow",
    "chatType": "flow",
    "content": {
      "body": "Please share your number so we can call you back."
    }
  }
}

Ticket events​

Ticket events include a contact object. For a hidden-number customer, contact.phoneNumber is omitted. The contact object has no BSUID field, so use clientReference or externalContactId to match tickets to your own records.

Sending to a BSUID​

to on the Messages API and Templates API accepts a phone number or a BSUID. Cue sends to the phone number it holds for the contact when there is one, and to the BSUID otherwise. Authentication templates require a phone number and are rejected for a BSUID-only contact. On the Contacts API, whatsapp_id is null for a hidden-number customer.

note

Do not assume from and to are phone numbers. Accept up to 128 characters of letters, digits and a dot, and do not parse, strip or store them as numbers. Make sure your receiver accepts the contacts and request_contact_info message types, and handles a missing phoneNumber on ticket events.