Skip to main content
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 without phone numbers. 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)
  • Keep sending outbound messages by phone number — BSUID-targeted sending is not live yet

​
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:

​
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 sending in Kapso remains phone-based for now
Not live yet:
  • sending outbound messages by BSUID-only recipient
  • changing your requests from to to a Kapso-specific BSUID send contract
If you send messages today, keep using phone numbers.

​
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:
LocationFields
Contact payloadswa_id, business_scoped_user_id, parent_business_scoped_user_id, username
Conversation payloadsphone_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 contextcontext.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: 
{
  "conversation": {
    "phone_number": "16315551181",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername"
  }
}
BSUID-only inbound identity: 
{
  "conversation": {
    "phone_number": null,
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": null,
    "username": "@testusername"
  }
}
Meta-style message identity: 
{
  "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: 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
  • keep outbound sending phone-based until Kapso documents BSUID-targeted sending support
  • 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

Meta has already started rolling out BSUIDs in inbound webhooks. Phone numbers can be omitted for username adopters. If you already consume Kapso WhatsApp payloads, adapt now.
  • 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
  • Early May 2026: Meta request-contact-information template button becomes available
  • May 2026: Meta says BSUID-targeted sending support arrives, but the exact date is still pending
  • Later in 2026: broader usernames rollout and business username features continue
Kapso will update this page when Meta publishes more concrete dates and when each later phase becomes available in Kapso.