# WhatsApp usernames and BSUIDs

URL: https://developers.cuedesk.com/webhooks/whatsapp_usernames_and_bsuids

> How webhooks identify WhatsApp users who hide their phone number with a username and a Business-Scoped User ID (BSUID).

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.

<Callout type="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.
</Callout>

## Customer whose phone number is known [#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`.

```jsonc
{
  "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 [#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.

<Tabs items={["Inbound message","Outbound message","Status update"]}>
<Tab value="Inbound message">

```jsonc
{
  "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?"
    }
  }
}
```

</Tab>
<Tab value="Outbound message">

```jsonc
{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2026-09-22T09:14:09.100804607Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "text",
    "uuid": "ee027936-5483-45fb-a40b-00d02ba3b0b0",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2026-09-22T09:14:08.394802120Z",
    "to": "GB.13491208865530274191", // BSUID
    "from": "447418371579",
    "origin": "flow",
    "chatType": "flow",
    "content": {
      "text": "Yes, it ships today."
    }
  }
}
```

</Tab>
<Tab value="Status update">

```jsonc
{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "createdAt": "2026-09-22T09:14:11.530951603Z",
  "trigger": "message_status_update",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "message_status_update",
    "channelType": "whatsapp",
    "to": "GB.13491208865530274191", // BSUID
    "from": "447418371579",
    "content": {
      "messageUuid": "ee027936-5483-45fb-a40b-00d02ba3b0b0",
      "status": "delivered",
      "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a"
    }
  }
}
```

</Tab>
</Tabs>

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 [#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.

<Tabs items={["Outbound request","Inbound contact card"]}>
<Tab value="Outbound request">

```json
{
  "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."
    }
  }
}
```

</Tab>
<Tab value="Inbound contact card">

```jsonc
{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2026-09-22T09:15:40.127971112Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "contacts",
    "uuid": "ee01c066-248f-41c5-aae2-04db9e0be2aa",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2026-09-22T09:15:40.035914665Z",
    "to": "447418371579",
    "from": "GB.13491208865530274191",
    "origin": "whatsapp",
    "chatType": "flow",
    "content": {
      "contacts": [
        {
          "name": "Thandi M", // All card fields are optional
          "first_name": "Thandi",
          "last_name": "M",
          "phones": [
            {
              "phone": "+44 7576 209857", // As typed by the customer
              "type": "CELL"
            }
          ]
        }
      ]
    }
  }
}
```

</Tab>
</Tabs>

## Ticket events [#ticket-events]

[Ticket events](/webhooks/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 [#sending-to-a-bsuid]

`to` on the [Messages API](/api/messages_api) and [Templates API](/api/templates/templates_api_v2) 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](/api/contacts_api), `whatsapp_id` is `null` for a hidden-number customer.

<Callout type="info">
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.
</Callout>
