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

# Business-scoped user IDs

> What changes when WhatsApp starts sending BSUIDs and how to adapt your integration

<Tip>
  Use the copy button to paste this guide into Codex, Claude Code, Cursor, or another coding agent and ask it to adapt your integration.
</Tip>

## TL;DR

Meta is rolling out **business-scoped user IDs (BSUIDs)** as a primary identity in WhatsApp. Inbound payloads can already arrive with BSUIDs, and phone numbers can be omitted in some username-related cases. Your integration needs to:

* Store `business_scoped_user_id`, `parent_business_scoped_user_id`, and `username`
* Make `phone_number` and `wa_id` nullable
* Match users by BSUID first, phone number second
* Handle identity-change events (`user_id_update`, `user_changed_user_id`)
* Use `to` for phone numbers and `recipient` for BSUID or parent BSUID outbound sends

## What changed

Meta is rolling out **business-scoped user IDs** for WhatsApp. They identify a user inside a business account and can appear together with a phone number or by themselves.

Kapso now exposes these additive fields where identity is already exposed today:

* `business_scoped_user_id`
* `parent_business_scoped_user_id`
* `username`

Relevant official guide:

* [Meta: business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/)

## What each field means

* `business_scoped_user_id`: the main WhatsApp identifier for a user inside your business context. When present, treat this as the primary identity key.
* `parent_business_scoped_user_id`: a parent BSUID that Meta only sends for eligible managed businesses with linked business portfolios. Unlike `business_scoped_user_id`, it can work across the linked portfolio group. Store it when present, but treat `business_scoped_user_id` as the primary identity key inside a normal single-portfolio integration.
* `username`: the user's WhatsApp username when available. Useful for display and some reconciliation flows, but not a stable primary identifier.

## Current status

What is live now in Kapso:

* inbound payloads can include both phone-based identity and BSUID-based identity
* some webhook and API payloads can have `phone_number` or `wa_id` as `null`
* conversations, contacts, messages, and flow context can now include the new identity fields
* outbound sends can target phone numbers with `to` or BSUIDs with `recipient`

### Outbound BSUID sends

Use `recipient` for a regular BSUID or parent BSUID:

```json theme={null}
{
  "messaging_product": "whatsapp",
  "recipient": "US.13491208655302741918",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en_US"
    }
  }
}
```

Use `to` for phone numbers. If both `to` and `recipient` are present, Meta uses the phone number in `to`.

Notes:

* non-template messages still require an open 24-hour customer service window
* template messages can start or reopen a conversation
* sandbox numbers do not support BSUID recipients
* authentication templates cannot be sent to BSUID recipients
* BSUIDs are scoped to the business portfolio that owns the sending phone number

## Payload shapes

Your parser should handle these inbound shapes:

* phone identity **and** BSUID identity together
* BSUID identity with **no phone number**
* `username` present with `phone_number` missing
* status payloads with recipient identity fields
* identity-change events: `user_id_update` and `user_changed_user_id`

Kapso surfaces the new fields in these places:

| Location                      | Fields                                                                                                                     |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Contact payloads              | `wa_id`, `business_scoped_user_id`, `parent_business_scoped_user_id`, `username`                                           |
| Conversation payloads         | `phone_number`, `business_scoped_user_id`, `parent_business_scoped_user_id`, `username`                                    |
| Message payloads (Kapso)      | `business_scoped_user_id`, `parent_business_scoped_user_id`, `username`                                                    |
| Message payloads (Meta-style) | `from_user_id`, `from_parent_user_id`, `to_user_id`, `to_parent_user_id`, `username`                                       |
| Workflow context              | `context.whatsapp_business_scoped_user_id`, `context.whatsapp_parent_business_scoped_user_id`, `context.whatsapp_username` |

### Payload assumptions

During the rollout, build for these cases:

* `phone_number` can be missing on some inbound or read payloads
* `wa_id` can be missing on some payloads
* `username` can change over time
* identity can transition over time through events like `user_id_update` and `user_changed_user_id`

### Example payloads

Phone number and BSUID together:

```json theme={null}
{
  "conversation": {
    "phone_number": "16315551181",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername"
  }
}
```

BSUID-only inbound identity:

```json theme={null}
{
  "conversation": {
    "phone_number": null,
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": null,
    "username": "@testusername"
  }
}
```

Meta-style message identity:

```json theme={null}
{
  "message": {
    "from": "16315551181",
    "from_user_id": "US.13491208655302741918",
    "from_parent_user_id": "US.ENT.506847293015824",
    "username": "@testusername"
  }
}
```

## Matching and storage

Treat WhatsApp identity as a compound shape, not just a phone number.

Recommended matching order:

1. `business_scoped_user_id` when present
2. `wa_id` or `phone_number` when present
3. keep both when you have both

Recommended storage rules:

* store `business_scoped_user_id`, `parent_business_scoped_user_id`, and `username`
* allow `wa_id` and `phone_number` to be nullable
* keep BSUID identity and phone identity on the same logical user/contact when both refer to the same person
* do not key your data model only by phone number anymore

If phone identity and BSUID identity point to different local records, do not silently create a third record. Merge or relink to a single canonical user/contact.

## Identity-change events

If you only consume normal Kapso webhooks and read the current state from Kapso APIs, this is lower priority at the beginning because Kapso already reconciles these identity changes internally.

If you keep your own identity store, mirror WhatsApp users into your own database, or consume forwarded Meta webhooks directly, these events matter and you should handle them.

Kapso does **not** currently emit a dedicated Kapso-formatted identity-change webhook event.

If you need the raw identity-change signal externally today, use raw Meta forwarding:

* `user_id_update` arrives as a raw Meta webhook field
* `user_changed_user_id` arrives as a raw Meta system message

See:

* [Receive messages](/docs/whatsapp/receive-messages)
* [Meta: business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/)

For `user_id_update` and `user_changed_user_id`:

* treat them as identity reconciliation events, not normal user content
* update the existing user/contact/conversation linkage instead of creating a new user blindly
* keep previous phone identity if it is still the same logical person
* use the event to move from phone-first matching to BSUID-first matching
* expect coexistence windows where old and new identifiers can both appear

## Migration checklist

* update your schema so `wa_id` and `phone_number` can be nullable where appropriate
* store `business_scoped_user_id`, `parent_business_scoped_user_id`, and `username`
* stop keying your users only by phone number
* make webhook parsers accept phone-based and BSUID-based payloads
* make your matching logic tolerate transition periods where both old and new identifiers can appear
* use `recipient` for BSUID or parent BSUID outbound sends
* use [request contact info](/docs/whatsapp/send-messages/request-contact-info) when you need the customer's phone number
* test at least these cases before rollout reaches your users:
  * phone + BSUID inbound payload
  * BSUID-only inbound payload
  * username + BSUID payload with no phone
  * status webhook with recipient identity
  * `user_id_update` or `user_changed_user_id` identity change event

## Timeline

<Info>
  Meta has already started rolling out BSUIDs in inbound webhooks. Phone numbers can be omitted for username adopters in some cases, but many payloads will still include phone numbers during the rollout, especially after recent interaction or when the user is present in Meta's contact book. If you already consume Kapso WhatsApp payloads, adapt now.
</Info>

* **Early April 2026**: BSUIDs begin appearing in inbound webhooks
* **Early April 2026**: Meta contact book rollout begins, which affects when phone numbers can still appear after prior interactions
* **June 29, 2026**: businesses can reserve usernames through Meta tools or the Username API
* **Early July 2026**: Meta begins enabling BSUID sends and phone number request CTAs
* **2026**: broader usernames rollout continues gradually by region

## What's next

Planned follow-up areas:

* expanding examples and API references as later username and BSUID phases become generally available
* updating this guide as Meta publishes more concrete rollout dates

Until then, treat this page as the source of truth for the currently supported Kapso behavior.

## Related docs

* [Receive messages](/docs/whatsapp/receive-messages)
* [Request contact info](/docs/whatsapp/send-messages/request-contact-info)
* [Business usernames](/docs/whatsapp/business-usernames)
* [Webhook event types](/docs/platform/webhooks/event-types)
* [WhatsApp data](/docs/platform/whatsapp-data)
* [Variables and context](/docs/flows/variables-and-context)

## Changelog

* **2026-06-30**: Added BSUID outbound sends, request contact info, and username rollout notes.
* **2026-04-20**: Clarified that phone numbers can be omitted only in some rollout cases, added identity-change event guidance, and expanded the timeline with Meta's published dates.