Vonage WhatsApp BSUID Updates

Vonage Messages API BSUID migration guide. Update your WhatsApp webhook to handle string-based Business Scoped User IDs for username-initiated conversations.

Vonage BSUID updates card

Vonage Messages API: BSUID Support

Vonage (formerly Nexmo) is rolling out support for WhatsApp Business Scoped User Identities across its Messages API. If your application processes inbound WhatsApp messages through Vonage, you must ensure your sender ID parser accepts string-based identifiers.

What Is Changing

When a user contacts your business via a WhatsApp username, Vonage will pass the BSUID in the from field of the inbound message object. Unlike the legacy phone number format (1234567890), BSUIDs are alphanumeric strings prefixed with BSUID..

Vonage Payload Comparison

Legacy: {"message_uuid":"abc123","from":"1234567890","text":"Hi"}

BSUID: {"message_uuid":"abc123","from":"BSUID.a1b2c3d4e5f6","text":"Hi"}

Implementation Guide

  1. Replace numeric type assertions with string parsing in your inbound message handler
  2. Detect BSUID prefix and route to BSUID-aware CRM logic
  3. Store the BSUID alongside your existing wa_id during the dual-mode transition
  4. Use Vonage's webhook debugger to test with sample BSUID payloads

Dual-Mode Support

Vonage will support both phone numbers and BSUIDs during Q3 2026. After Q4 2026, username-initiated conversations will exclusively use BSUIDs.