Business-scoped user IDs

​

TL;DR

• 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

• business_scoped_user_id
• parent_business_scoped_user_id
• username

• 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

• 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

{
  "messaging_product": "whatsapp",
  "recipient": "US.13491208655302741918",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en_US"
    }
  }
}

• 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

• 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

​

Payload assumptions

• 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

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

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

{
  "message": {
    "from": "16315551181",
    "from_user_id": "US.13491208655302741918",
    "from_parent_user_id": "US.ENT.506847293015824",
    "username": "@testusername"
  }
}

​

Matching and storage

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

• 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

​

Identity-change events

• user_id_update arrives as a raw Meta webhook field
• user_changed_user_id arrives as a raw Meta system message

• Receive messages
• Meta: business-scoped user IDs

• 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 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

• 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

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

​

Related docs

• Receive messages
• Request contact info
• Business usernames
• Webhook event types
• WhatsApp data
• 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.