MessageBird WhatsApp BSUID

MessageBird WhatsApp BSUID Integration

MessageBird (now Bird.com) is updating its WhatsApp API integration to support Business Scoped User IDs (BSUIDs). While the MessageBird Inbox product automatically maps BSUIDs to existing contacts, direct API users need to update their webhook parsing logic.

Automatic Mapping in MessageBird Inbox

For customers using MessageBird's Inbox product, BSUIDs are automatically mapped to contact profiles. The Inbox UI will display the username and associated metadata without requiring any manual configuration.

Direct API Considerations

If you use MessageBird's WhatsApp Business API directly, your webhook endpoint will receive BSUIDs in the from field of inbound messages. You need to update your parser to handle alphanumeric sender IDs.

API Payload Changes

Legacy: {"from":"31234567890","message":"Hello"}

BSUID: {"from":"BSUID.a1b2c3d4e5f6","message":"Hello"}

Implementation Steps

1. Audit your MessageBird webhook endpoint for from field type assumptions
2. Update database schemas to store BSUID strings (VARCHAR(64)) alongside wa_id
3. Implement dual-mode parsing that handles both formats during the transition period
4. Test with sample BSUID payloads from MessageBird's API documentation

Transition Timeline

MessageBird will support dual-mode through Q3 2026. Starting Q4 2026, username-initiated conversations will exclusively use BSUIDs.