Business-scoped user IDs

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

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 if you consume raw Meta webhooks or keep your own identity store
Reply with to when you have a phone number, or recipient when you only have a BSUID

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

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:

{
  "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. When replying to an inbound message:

const destination = message.from
  ? { to: message.from }
  : { recipient: message.from_user_id };

Do not pass a BSUID in to. Use the full BSUID in recipient, including its country prefix and period. With the TypeScript SDK, every message builder takes recipient alongside to:

await client.messages.sendText({
  phoneNumberId: '123',
  recipient: 'US.13491208655302741918',
  body: 'On its way.'
});

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

Addressing contacts by BSUID

The Platform contacts API accepts a BSUID or parent BSUID wherever it accepts a contact UUID or phone number:

curl https://api.kapso.ai/platform/v1/whatsapp/contacts/US.13491208655302741918 \
  -H "X-API-Key: $KAPSO_API_KEY"

This works for GET, PATCH, and DELETE on /platform/v1/whatsapp/contacts/{identifier}. Pass the BSUID verbatim, including the country prefix and period. A parent BSUID (US.ENT.…) can be shared by several contacts in a project, and the same BSUID can exist under two portfolios. An ambiguous lookup returns 409 Conflict with the candidate contact UUIDs instead of guessing; address the contact by its UUID in that case. To list instead of fetch a single contact, filter with business_scoped_user_id:

curl "https://api.kapso.ai/platform/v1/whatsapp/contacts?business_scoped_user_id=US.13491208655302741918" \
  -H "X-API-Key: $KAPSO_API_KEY"

Starting workflows by BSUID

POST /platform/v1/workflows/{id}/executions accepts recipient in place of phone_number. See Start and resume via API.

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 system messages: user_changed_number 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, wa_id, from, or to can be omitted instead of set to null
username can change over time
identity can transition over time through system messages like user_changed_number and user_changed_user_id

Example payloads

Phone number and BSUID together:

{
  "conversation": {
    "phone_number": "16315551181",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername"
  }
}

Kapso webhook with a BSUID-only inbound message:

{
  "message": {
    "id": "wamid.123",
    "type": "text",
    "from_user_id": "US.13491208655302741918",
    "username": "@testusername",
    "text": {
      "body": "Hello"
    }
  },
  "conversation": {
    "id": "conv_123",
    "phone_number": null,
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": null,
    "username": "@testusername"
  }
}

message.from is omitted and conversation.phone_number is null in this case. Do not reject the webhook because the phone identity is missing. Forwarded Meta webhooks follow the same rule: entry[].changes[].value.messages[].from can be absent while from_user_id is present. Forwarded Meta status identity without a phone number:

{
  "contacts": [
    {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.506847293015824",
      "profile": {
        "username": "@testusername"
      }
    }
  ],
  "statuses": [
    {
      "id": "wamid.456",
      "status": "delivered",
      "recipient_user_id": "US.13491208655302741918",
      "recipient_parent_user_id": "US.ENT.506847293015824"
    }
  ]
}

The forwarded Meta payload uses user_id in contacts and recipient_user_id in statuses. Phone-based fields such as wa_id and recipient_id can be omitted.

When phone numbers are included

If a WhatsApp user enables a username, Meta omits their phone number unless at least one condition applies:

the receiving business phone number messaged or called the user’s phone number in the last 30 days
the receiving business phone number received a message or call from the user’s phone number in the last 30 days
the user is stored in the business portfolio’s Meta contact book

The 30-day checks apply per business phone number. An interaction through another number in the same portfolio does not satisfy those checks on its own. The contact book is portfolio-scoped. Once it records the identity mapping, any business phone number in that portfolio can receive the phone number in eligible webhooks.

There is no universal date when Meta will stop sending phone numbers. Availability depends on username adoption and the conditions above.

Matching and storage

Treat WhatsApp identity as a compound shape, not just a phone number. Recommended matching order:

business_scoped_user_id when present
wa_id or phone_number when present
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, merge or relink them only when the same Meta payload or an identity-change event establishes the relationship. Otherwise, keep the records separate for manual reconciliation.

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. Meta announces a BSUID rotation on the regular messages field as a system message. user_changed_number is used when the new phone number can be shared, user_changed_user_id when only the BSUID transition can be shared. Both carry the current user_id (and parent_user_id when enabled) plus previous_user_id and previous_parent_user_id. There is no subscribable user_id_update field.

{
  "type": "system",
  "system": {
    "type": "user_changed_number",
    "wa_id": "12195555358",
    "user_id": "US.99225512874400319256",
    "previous_user_id": "US.13491208655302741918"
  }
}

Kapso reconciles the change onto the existing contact, conversation, and sandbox session, then emits whatsapp.contact.identity_changed. These system messages are not delivered as whatsapp.message.received and do not reach workflows or agents. See:

If you consume raw Meta webhooks yourself:

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
review validations, unique indexes, searches, and CRM mappings that require a phone number
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 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_changed_number or user_changed_user_id identity change system message

Timeline

The rollout has started. If you already consume Kapso WhatsApp payloads, adapt now.

Phone numbers can be omitted for username adopters, but many payloads still include them during the rollout - especially after a recent interaction, or when the user is in Meta’s contact book.

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.

Changelog

2026-08-04: Added addressing Platform API contacts by BSUID or parent BSUID.
2026-07-30: Added BSUID-only webhook examples, reply routing, phone number availability rules, and safer reconciliation guidance.
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.

Getting started

WhatsApp

For your team

Onboard customers

Automations

TL;DR

What changed

What each field means

Current status

Outbound BSUID sends

Addressing contacts by BSUID

Starting workflows by BSUID

Payload shapes

Payload assumptions

Example payloads

When phone numbers are included

Matching and storage

Identity-change events

Migration checklist

Timeline

What’s next

Changelog

​TL;DR

​What changed

​What each field means

​Current status

​Outbound BSUID sends

​Addressing contacts by BSUID

​Starting workflows by BSUID

​Payload shapes

​Payload assumptions

​Example payloads

​When phone numbers are included

​Matching and storage

​Identity-change events

​Migration checklist

​Timeline

​What’s next

​Related docs

​Changelog

TL;DR

What changed

What each field means

Current status

Outbound BSUID sends

Addressing contacts by BSUID

Starting workflows by BSUID

Payload shapes

Payload assumptions

Example payloads

When phone numbers are included

Matching and storage

Identity-change events

Migration checklist

Timeline

What’s next

Related docs

Changelog