BSUID & Target Format

Overview

WATI APIs now support BSUID (Business Solution User ID) — a stable, cross-channel identifier for contacts. This enables identification of contacts beyond phone numbers.

Three new identifiers are exposed:

Unified Target Format

Many API endpoints accept a polymorphic target parameter that supports multiple identifier formats:

The system automatically detects the format based on the value pattern.

API Changes

V1/V2 Endpoints

Route parameter endpoints (e.g., getMessages/{whatsappNumber}, sendSessionMessage/{whatsappNumber}):

• The path parameter now accepts Phone Number, Contact ID, or BSUID

Query parameter endpoints (e.g., sendTemplateMessage, assignOperator):

• whatsappNumber is now optional (was required)
• New target parameter added (optional)
• At least one of whatsappNumber or target must be provided

Body schema endpoints (e.g., sendTemplateMessages, updateChatStatus):

• whatsappNumber field is now nullable (was required)
• New target field added
• At least one must be provided per record

V3 Endpoints

V3 already uses a polymorphic target field. The change adds support for BSUID and Channel:BSUID formats to the existing resolver.

Template send/schedule endpoints:

• phone_number is now optional (was required)
• New target field added as alternative

Response Enrichment

Contact-related API responses now include additional identifiers:

{
  "id": "507f1f77bcf86cd799439011",
  "phone": "14155552671",
  "bsuid": "US.123124141512",
  "parentBsuid": "US.ENT.789456123",
  "username": "@bob"
}

📘

The phone field remains present in responses but is now nullable — it will be omitted when null. Existing consumers that assume phone != null should be updated.

Webhook Changes

Existing Webhooks (Additive)

All existing webhook event types now include bsuid, parentBsuid, and username when available:

{
  "eventType": "message",
  "waId": "8618719149214",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob",
  ...
}

• waId remains required (always present)
• bsuid / parentBsuid / username are optional (included when available)
• Existing consumers that ignore unknown fields continue to work

BSUID-First Webhooks (New Contract)

New webhook event types with _bsuid suffix use BSUID as the primary identifier:

{
  "eventType": "message_bsuid",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob",
  "waId": "8618719149214",
  ...
}

• bsuid is required (always present)
• waId is optional (may be omitted)
• Consumers must identify the user by bsuid, not phone

See the individual BSUID webhook pages for full payload examples.

Migration Guide