> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Usernames & BSUIDs

> Handle WhatsApp contacts who adopted a username and hid their phone number. Receive, reply and send using business-scoped user IDs (BSUIDs).

WhatsApp users can adopt a **username** (like `@sheena`) and hide their phone number from businesses. When that happens, you no longer see their phone number anywhere: instead, every webhook and API response identifies them by a **business-scoped user ID (BSUID)**.

```
US.13491208655302741918
```

A BSUID is stable per business: the same user always has the same BSUID with you, but a *different* BSUID with every other business. You cannot derive a phone number from it.

Zavu handles the identity plumbing automatically. Contacts are matched and de-duplicated by BSUID, conversations stay threaded, and if the user later shares their phone number, both identifiers point to the same contact. What you need to adapt in your integration is small, and it is all on this page.

## Receiving messages from a username contact

Nothing changes in the event shape. The `message.inbound` webhook fires as usual, but `data.from` contains the BSUID instead of an E.164 phone number:

```json theme={null}
{
  "id": "evt_1705312200000_abc123",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_xyz789",
    "from": "US.13491208655302741918",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "text",
    "text": "Hi, I saw your listing",
    "profileName": "Sheena",
    "providerTimestamp": 1705312199000
  }
}
```

<Warning>
  If your integration parses `data.from` as a phone number (regex for `+`, phone-number libraries, CRM lookups by E.164), it will break the first time a username contact writes in. Treat `from` as an opaque recipient identifier: it is either an E.164 phone number or a BSUID starting with a two-letter region prefix like `US.`.
</Warning>

`profileName` still carries the user's display name when available, so your inbox UI has something human to show.

## Replying and sending to a BSUID

Pass the BSUID in `to`, exactly where a phone number would go. Zavu detects the format and routes it correctly on the WhatsApp API.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const message = await zavu.messages.send({
    to: "US.13491208655302741918",
    channel: "whatsapp",
    text: "Thanks for reaching out! How can we help?"
  });
  ```

  ```python Python theme={null}
  message = zavu.messages.send(
      to="US.13491208655302741918",
      channel="whatsapp",
      text="Thanks for reaching out! How can we help?"
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/messages \
    -H "Authorization: Bearer zv_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "US.13491208655302741918",
      "channel": "whatsapp",
      "text": "Thanks for reaching out! How can we help?"
    }'
  ```
</CodeGroup>

All WhatsApp message types work, including media, interactive messages and templates. The [24-hour conversation window](/guides/whatsapp/overview) rules are unchanged.

Two exceptions:

| Limitation                                                           | Behavior                                                                                                                                |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication templates with one-tap, zero-tap or copy-code buttons | Rejected by WhatsApp (error `131062`). These flows verify a phone number, so they need one. Send to the contact's phone number instead. |
| Broadcasts                                                           | BSUID and `@username` recipients are rejected with a clear error. Broadcasts require phone numbers.                                     |

## Recovering the phone number

If your workflow eventually needs the real phone number (calls, SMS fallback, identity verification), ask for it in the conversation. WhatsApp provides a dedicated interactive message for this: [`request_contact_info`](/guides/whatsapp/messages/request-contact-info). It renders a fixed **Share Contact Info** button; when the user taps it and confirms, their phone number arrives as a regular inbound `contact` message.

Zavu then links the shared phone number to the BSUID contact automatically: the contact record gains a `phoneNumber`, and both identifiers resolve to the same contact and conversation from that point on.

You can also add a `request_contact_info` button to a [template](/guides/whatsapp/templates/overview#button-types) to ask outside the 24-hour window.

## Contacts in the dashboard

A contact created from a BSUID-only inbound has no phone number until the user shares one. The dashboard contact list and inbox display the username or BSUID instead, and flag conversations where a phone number was linked from a username contact.

In the API, expect `phoneNumber` to be absent on these contacts. Key on the `from` value of the inbound events to correlate messages with your own records.

## Your own business username

Your WABA can reserve a business username so customers can find and message you without knowing your number. Manage it from the dashboard under **Accounts → WhatsApp → your WABA**: the username section shows the current username, its status (reserved, approved, deleted) and lets you set or change it. Status changes arrive automatically; there is nothing to poll.

<Note>
  Username adoption is rolling out gradually on WhatsApp's side. Your integration should handle BSUIDs today even if you have not seen one yet: any user can adopt a username at any time, and their next message to you will carry a BSUID.
</Note>