WhatsApp Identities and BSUID

Historically, many WhatsApp integrations treated the customer phone number as the stable contact identifier. WhatsApp usernames and business-scoped user IDs change that assumption.

Identifier Types

Field Meaning Recommended use
contactPhone Legacy phone-like identifier when available Display only; do not use as a required primary key
wa_id WhatsApp ID returned by Meta in legacy payloads Fallback identity when BSUID is not present
user_id / BSUID Business-scoped user ID Preferred WhatsApp identity when present
parent_user_id Parent business-scoped identity when Meta provides one Store for future reconciliation; do not require it
username WhatsApp username when exposed Display/search aid; do not assume it is always present

Our API Fields

contactIdentifier is the stable key to store.

contactIdentifierType tells you whether the key is a phone, legacy WhatsApp ID, BSUID, or username.

contactReplyTo is the value to use when sending a reply:

{
  "type": "text",
  "to": "AR.ABC123",
  "text": "Thanks, we received your message."
}

contactPhone remains available when Meta provides a phone-like identifier, but it can be null.

Templates and Limits

Meta and BSP documentation indicate that authentication templates may still require phone-number delivery in scenarios where BSUID delivery is available for other message types. Treat template category support as Meta-controlled behavior and validate against the current Meta documentation for your WABA before relying on BSUID for authentication flows.

Internal Model

This project keeps contacts phone-scoped. A contact belongs to one local phone inbox and stores the small set of WhatsApp identifiers we need today: phone, wa_id, BSUID, parent BSUID, and username. It is intentionally not a full omnichannel CRM.

References