Handling WhatsApp Usernames and BSUIDs
This guide walks you through the changes you need to make to your Vonage Messages API integration to support WhatsApp usernames and BSUIDs.
Prerequisites
- An active Vonage application with the Messages capability enabled
- A WhatsApp Business Account (WABA) and a WhatsApp Phone number connected to Meta and Vonage
- Webhook endpoints configured for inbound messages and status callbacks
Update Your Send Message Requests
You can now send messages using a BSUID in addition to, or instead of, a phone number. The to field now accepts either a phone number or a BSUID for WhatsApp recipients.
Send to a phone number only (existing behaviour, unchanged):
Send to a BSUID only:
Important: When using a BSUID, always include the full value - country code prefix, period, and all alphanumeric characters. Omitting or modifying any part of the BSUID will cause the request to fail.
Handle the Updated Send Message Response
The send message response is unchanged. For details, see the Send Message API specification.
Update Your Status Callback (Webhook) Handler
Status callbacks for sent, delivered, and read outgoing messages now include a whatsapp.recipient object and a profile object with new fields.
Updated status callback payload:
{
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"status": "read",
"channel": "whatsapp",
"profile": {
"name": "John Smith",
"username": "johnSmith"
},
"usage": { "currency": "EUR", "price": "0" },
"whatsapp": {
"pricing": {
"type": "regular",
"pricing_model": "CBP",
"category": "service"
},
"recipient": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
},
"conversation": {
"id": "1234567890",
"origin": { "type": "marketing" }
}
}
}
New and changed fields:
| Field | Description |
|---|---|
profile.username | The user's WhatsApp username, if they have adopted one. Omitted for sent status or if the user has no username. |
whatsapp.recipient.user_id | The user's BSUID. Always present for delivered and read statuses. |
whatsapp.recipient.parent_user_id | The user's parent BSUID. Only present if your business has enabled parent BSUIDs. |
whatsapp.recipient.wa_id | The user's phone number. Omitted if the message was sent to a BSUID and the phone number cannot be included. |
For failed status callbacks, recipient_user_id is omitted if the message was sent to a phone number.
Update Your Inbound Message (Webhook) Handler
Inbound message webhooks now include a whatsapp.sender object and an updated profile object.
Updated inbound message callback payload:
{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"profile": {
"name": "Jane Smith",
"username": "janeSmith"
},
"message_type": "text",
"text": "Hello from Vonage!",
"whatsapp": {
"sender": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
}
}
}
The from field will contain the user's phone number if it is available. If the phone number is not available, the BSUID will be displayed instead.
New and changed fields:
| Field | Description |
|---|---|
profile.username | The user's WhatsApp username, if they have adopted one. Omitted if the user has no username. |
whatsapp.sender.user_id | The user's BSUID. Always present. |
whatsapp.sender.parent_user_id | The user's parent BSUID. Only present if your business has enabled parent BSUIDs. |
whatsapp.sender.wa_id | The user's phone number. Omitted if the user has adopted a username and the phone number cannot be included per the conditions described above. |
Request a User's Phone Number (Optional)
If your integration requires a user's phone number - for example, for authentication or verification purposes - you can request it directly in the conversation. There are two ways to do this: via a pre-approved template message or via an interactive message.
Option 1: Template Message with a Contact Info Request Button
You must first create and get a WhatsApp template approved that includes a REQUEST_CONTACT_INFO button via the WhatsApp Template Management API. Once approved, send the template using the Vonage Messages API:
Option 2: Interactive Message with a Contact Info Request Button
You can also request a phone number within an active conversation window using an interactive message, without requiring a pre-approved template: