Webhook Changes for WhatsApp Usernames Webhook Changes for WhatsApp Usernames

Webhook Changes for WhatsApp Usernames

DK Sah

Background

Please see this KB article

 

Message Status callbacks / webhooks - with Username & BSUID information

 

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "read",
   "error": {
      "type": "https://developer.vonage.com/api-errors/messages#1000",
      "title": "1000",
      "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
      "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
   },
   "client_ref": "abc123",
   "workflow": {
      "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
      "items_number": "1",
      "items_total": "2"
   },
   "channel": "whatsapp",
   "profile": {                          // NEW
      "name": "John Smith",              // NEW
      "username": "johnSmith"            // NEW
   },
   "usage": {
      "currency": "EUR",
      "price": "0"
   },
   "whatsapp": {
      "pricing": {
         "type": "regular",
         "pricing_model": "CBP",
         "category": "service"
      },
       "recipient":{                            // NEW
       "user_id": "<BSUID>" ,                   // NEW
       "parent_user_id": "<PARENT_BSUID>" ,     // NEW
       "wa_id": "<PHONE_NUMBER>" ,              // NEW
      },
      "conversation": {
         "id": "1234567890",
         "origin": {
            "type": "marketing"
         }
      }
   }
}

 

Here, in a business-initiated message to a user, the "recipient" object houses the contact details of the user.

  • "user_id": New field; shows the BSUID attached with the phone number
  • "parent_user_id": New field; shows the PARENT BSUID attached with the phone number, if available (parent BSUIDs enabled need to be enabled by Meta for every organisation) (see details here)
  • "wa_id": New field; shows the end user's phone number, if available (see below for details)

The above fields are apart from the phone number or BSUID value that is used in the "to" field, which will always show what the business used for messaging.

Also, in the "from" field, the business's phone number will be always displayed, even if the business has itself adopted a username for their WhatsApp phone number. 

The "profile" object (New Object) captures:

  • "name": the profile name associated with the WhatsApp phone number
  • "username": the username a user has adopted with Meta
For "Display Priority" of these business names, in the chat window of a business and a user, please see Meta doc here: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#chat-window-display-priority

 

Incoming Message callbacks / webhooks - with Username & BSUID information

 

{
   "channel": "whatsapp",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "profile": {
      "name": "Jane Smith",
      "username": "johnSmith"                      // NEW
   },
   "context_status": "available",
   "context": {
      "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
      "message_from": "447700900000"
   },
   "provider_message": "Message delivered",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "whatsapp": {
      "referral": {
         "body": "Check out our new product offering",
         "headline": "New Products!",
         "source_id": "212731241638144",
         "source_type": "post",
         "source_url": "https://fb.me/2ZulEu42P",
         "media_type": "image",
         "image_url": "https://example.com/image.jpg",
         "video_url": "https://example.com/video.mp4",
         "thumbnail_url": "https://example.com/thumbnail.jpg",
         "ctwa_clid": "1234567890"
      },
     "sender":{                                             // NEW
       "user_id": "<BSUID>" ,                               // NEW
       "parent_user_id": "<PARENT_BSUID>",                  // NEW
       "wa_id": "<PHONE_NUMBER>",                           // NEW
      },
   },
   "_self": {
      "href": "https://api-eu.vonage.com/v1/messages/aaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
   }
}

 

Here, in a user-initiated message to a business, the "sender" object houses the contact details of the user.

  • "user_id": New field; shows the BSUID attached with the phone number
  • "parent_user_id": New field; shows the PARENT BSUID attached with the phone number, if available (parent BSUIDs enabled need to be enabled by Meta for every organisation) (see details here)
  • "wa_id": New field; shows the end user's phone number, if available (see below for details)

In the "from" field, user's phone number, if available, will always be shown in higher preference to the user's BSUID.

Also, in the "to" field, the business's phone number will be always displayed, even if the business has itself adopted a username for their WhatsApp phone number. 

The "profile" object (New Object) captures:

  • "username": the username a user has adopted with Meta

 

When will a username-adopted user's phone number be available to a business instead of their BSUID?

  • Business/user has messaged or called the user's/business’s phone number within the last 30 days of the webhook being triggered
    The user is in business's contact book
  • Contact book feature is enabled by default for your Meta Business Portfolio. Phone numbers of users messaging/calling a business gets automatically added to business's contact book and are stored indefinitely.
  • If the business has used the REQUEST_CONTACT_INFO button type in a template, and user has shared their contact card.

 

 

 

 

Articles in this section