To support Meta's BSUID rollout starting March 31, 2026, YCloud has updated several webhook payloads related to messaging and user identity.

This document describes the webhook payload changes introduced for BSUID support. These changes are backward compatible. Existing webhook fields are unchanged. Integrations should update their parsers to accept the new optional BSUID-related fields. We recommend that businesses review these updates and start capturing users' BSUIDs whenever available for future messaging use cases.

**Recommended actions: **

Update webhook deserialization models.
Treat new BSUID-related fields as optional.
Store BSUID and parent BSUID when present.
Do not assume phone number is the only stable user identifier after March 31, 2026.

📘
YCloud will continue to update additional API documentation. Please follow our updates via the changelog or the BSUID explanation documentation.

Messages webhooks

whatsapp.message.updated

Occurs when a WhatsApp outbound message status is updated, and the status changes to failed, sent, delivered, or read.

Webhook parameter change specifications

Field Name	Data Type	Description
recipientUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
parentRecipientUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
customerProfile	Object	New object. Only included for sent, delivered, and read status messages. Will be omitted entirely for failed status messages webhooks.
customerProfile.name	String	New property. Value will be set to the WhatsApp user’s display name.
customerProfile.username	String	New property. Will be set to the WhatsApp user’s username if the user has enabled the usernames feature. Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature

Sample

{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "from": "WHATSAPP_BUSINESS_PHONE_NUMBER",
    "to": "CUSTOMER_PHONE_NUMBER",
    "recipientUserId" : "US.13491208655302741918",        <!-- ADDED --BSUID -->                       
    "parentRecipientUserId": "US.11815799212886844830",   <!-- ADDED-- PARENT_BSUID --> 
    "customerProfile": {                                  <!-- ADDED -->
      "name": "Pablo M.",                                 <!-- ADDED --USER_DISPLAY_NAME--> 
      "username": "@pablomorales"                         <!-- ADDED-- USER_NAME--> 
    },
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}`

whatsapp.inbound_message.received

Occurs when a WhatsApp inbound message is received.

Webhook parameter change specifications

Field Name	Data Type	Description
fromUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
fromParentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
customerProfile.username	String	New property. Will be set to the WhatsApp user’s username if the user has enabled the usernames feature. Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature
system.user_id	String	New property. NEW_BSUID. Will be set to the user’s New BSUID or New parent BSUID. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely. This field follows Meta's original naming within the system object
system.parent_user_id	String	New property. NEW_PARENT_BSUID be set to the user’s New parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely. This field follows Meta's original naming within the system object

Sample of Received an inbound message from users

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER", 
    "fromUserId" : "US.13491208655302741918",         <!-- ADDED --BSUID-->
    "fromParentUserId": "US.11815799212886844830",    <!-- ADDED --PARENT_BSUID-->
    "customerProfile": {                             
      "name": "Joe",                                  
      "username": "@JoeJoe"                           <!-- ADDED --USER_NAME-->
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}

Sample of user changed WhatsApp phone number

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",           <!-- ADDED -- BSUID-->
    "fromParentUserId": "US.11815799212886844830",      <!-- ADDED --PARENT_BSUID-->
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"                             <!-- ADDED --USER_NAME-->
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "system",
    "system": {
      "body": "User A changed from 18325355831 to 15129984441",
      "wa_id": "15129984441",
      "user_id": "US.13491208655302741919",              <!-- ADDED -- NEW_BSUID-->
      "parent_user_id": "US.11815799212886844831",       <!-- ADDED -- NEW_PARENT_BSUID-->
      "type": "user_changed_number"             
    }
  }
}

whatsapp.user.preferences

Occurs when

A WhatsApp user stops marketing messages.
A WhatsApp user resumes marketing messages.

Webhook parameter change specifications

Field Name	Data Type	Description
userId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
parentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.

Sample

{
  "id": "evt_690c76bf20f2a632b25fca28",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2025-11-06T10:21:51.582Z",
  "whatsappUserPreference": {
    "wabaId": "WABA-ID",
    "businessPhoneNumber": "BUSINESS-PHONE-NUMBER",
    "businessPhoneId": "BUSINESS-PHONE-ID",
    "contactName": "CUSTOMER-WHATSAPP-NAME",
    "contactPhoneNumber": "CUSTOMER-PHONE-NUMBER",
    "userId" : "US.13491208655302741918",                            <!-- ADDED -- BSUID-->
    "parentUserId": "US.11815799212886844830",                       <!-- ADDED --PARENT_BSUID-->
    "detail": "User requested to resume/stop marketing messages",
    "category": "marketing_messages",
    "value": "resume/stop",
    "timestamp": 1762325346000
  }
}

Calling webhooks

Call permission update webhooks

Webhook parameter change specifications

Field Name	Data Type	Description
fromUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
fromParentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
customerProfile.username	String	New property. Will be set to the WhatsApp user’s username if the user has enabled the usernames feature. Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature

Sample： The customer accepted your calling request.

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",           <!-- ADDED --BSUID-->  
    "fromParentUserId": "US.11815799212886844830",      <!-- ADDED-- PARENT_BSUID--> 
    "customerProfile": {                                <!-- ADDED -->
      "name": "Joe",                                    <!-- ADDED --USER_DISPLAY_NAME--> 
      "username": "@JoeJoe"                             <!-- ADDED-- USER_NAME-->
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
        "type": "call_permission_reply",
        "call_permission_reply": {
        "response": "accept",
        "is_permanent": true,
        "response_source": "user_action"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}

whatsapp.call.connect

When a WhatsApp user calls your business, a Call Connect webhook will be triggered.

Webhook parameter change specifications

Field Name	Data Type	Description
callingConnect.toUserId	String	New property. Indicate the recipient's BSUID. Will be set to the user’s BSUID or parent BSUID, if you raise a call to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
callingConnect.toParentUserId	String	New property. Indicate the recipient's parent BSUID. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
callingConnect.fromUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
callingConnect.fromParentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.

Sample: Business-initiated connected calls webhooks

{
  "id": "evt_676e5a0d7a9cb742d02d7645",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:01.554Z",
  "callingConnect": {
    "id": "676e5a0d94c533526d3c5ad5",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "from": "+6283138205150",
    "to": "+6283138205150",
    "toUserId": "US.13491208655302741918",          <!-- ADDED --BSUID--> 
    "toParentUserId": "US.11815799212886844830",    <!-- ADDED-- PARENT_BSUID--> 
    "direction": "BUSINESS_INITIATED", 
    "sdpType": "answer",
    "sdp": "<<RFC 4566 SDP>>",
    "dialTime": 1735283452000
  }
}
}

Sample : User-initiated connected calls webhooks

{
  "id": "evt_6757b723a5a42d369ef48480",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:36:03.749Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxrtLopSdPMwd",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "US.13491208655302741918",          <!-- ADDED --BSUID--> 
    "fromParentUserId": "US.11815799212886844830",    <!-- ADDED-- PARENT_BSUID--> 
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "sdpType": "offer",
    "sdp": "<<RFC 4566 SDP>>"
  }
}

whatsapp.call.terminate

A webhook notification whatsapp-calling-terminate-webhook is sent whenever a call ends, for any reason. This includes when the WhatsApp user hangs up, or when the business sends a terminate or reject request to the endpoint.

Webhook parameter change specifications

Field Name	Data Type	Description
callingTerminate.toUserId	String	New property. Indicate the recipient's BSUID. Will be set to the user’s BSUID or parent BSUID, if you raise a call to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
callingTerminate.toParentUserId	String	New property. Indicate the recipient's parent BSUID. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
callingTerminate.fromUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
callingTerminate.fromParentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.

Sample: Business-initiated terminated calls webhooks

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTE",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "toUserId": "US.13491208655302741918",         <!-- ADDED --BSUID-->
    "toParentUserId": "US.11815799212886844830",   <!-- ADDED-- PARENT_BSUID--> 
    "direction": "BUSINESS_INITIATE",          
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Sample: User-initiated terminated calls webhooks

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTE",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "US.13491208655302741918",         <!-- ADDED --BSUID-->
    "fromParentUserId": "US.11815799212886844830",   <!-- ADDED-- PARENT_BSUID--> 
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

whatsapp.call.status.updated

The webhook is dispatched upon the call status event, like RINGING, ACCEPTED, on the WhatsApp user's client device

Webhook parameter change specifications

Field Name	Data Type	Description
callingStatusUpdated.recipientUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you raise a call to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
callingStatusUpdated.parentRecipientUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.

Sample

{
 "id": "evt_676e5ab57a9cb742d02d7646",
 "type": "whatsapp.call.status.updated",
 "apiVersion": "v2",
 "createTime": "2024-12-27T07:41:28.422Z",
 "callingStatusUpdated": {
   "wabaId": "188234691048809",
   "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
   "status": "RINGING",
   "recipientPhone": "+6281361905133", 
   "recipientUserId" : "US.13491208655302741918",             <!-- ADDED --BSUID-->
   "parentRecipientUserId": "US.11815799212886844830"         <!-- ADDED-- PARENT_BSUID-->
 }
}

SMB webhooks

whatsapp.smb.history

Occurs when the WhatsApp Business app chat history of a business that has chosen to share their chat history with a solution provider, or the business's decision to decline chat history sharing.For more examples, see WhatsApp Business App History Message Webhook Examples.

Webhook parameter change specifications

Field Name	Data Type	Description
whatsappInboundMessage.fromUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you raise a call to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
whatsappInboundMessage.fromParentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
whatsappInboundMessage.customerProfile.username	String	New property. Will be set to the WhatsApp user’s username if the user has enabled the usernames feature. Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature
whatsappMessage.toUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you raise a call to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
whatsappMessage.toParentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.

Sample: Inbound message

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",         <!-- ADDED --BSUID-->
    "fromParentUserId": "US.11815799212886844830",   <!-- ADDED-- PARENT_BSUID-->
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeWick"                          <!-- ADDED-- USER_NAME-->
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}

Sample: Outbound message

{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId" : "US.13491208655302741918",         <!-- ADDED --BSUID-->
    "toParentUserId": "US.11815799212886844830",    <!-- ADDED-- PARENT_BSUID-->
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "context": {
      "message_id": "wamid.BgNODYxN..."
    }
  }
}

whatsapp.smb.app.state.sync

Occurs when a business customer onboards their WhatsApp Business App number on YCloud and chooses 'Share Chats' on the app, YCloud will sync the contacts info from the WhatsApp Business App number adds, edits, or removes a WhatsApp contact in WhatsApp Business App

Webhook parameter change specifications

Field Name	Data Type	Description
whatsappSmbAppStateSync.stateSync.contact.userId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you raise a call to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
whatsappSmbAppStateSync.stateSync.contact.parentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
whatsappSmbAppStateSync.stateSync.contact.username	String	New property. Will be set to the WhatsApp user’s username if the user has enabled the usernames feature. Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature

Sample

{
  "id": "evt_68aff15e1695f42ed52ef9cd",
  "type": "whatsapp.smb.app.state.sync",
  "apiVersion": "v2",
  "createTime": "2025-08-28T06:04:09.539Z",
  "whatsappSmbAppStateSync": {
    "wabaId": "WABA-ID",
    "phoneNumber": "BUSINESS-PHONE-NUMBER",
    "stateSync": [
      {
        "contact": {
          "fullName": "CUSTOMER-FULL-NAME",
          "firstName": "CUSTOMER-FIRST-NAME",
          "phoneNumber": "CUSTOMER-PHONE-NUMBER",
          "userId": "US.13491208655302741918",         <!-- ADDED --BSUID-->
          "parentUserId": "US.11815799212886844830",   <!-- ADDED-- PARENT_BSUID-->
          "username": "@Joejoe"                        <!-- ADDED-- USER_NAME-->
        },
        "action": "add",
        "timestamp": 1756354684879
      },{
        "contact": {
          "fullName": "CUSTOMER-FULL-NAME",
          "firstName": "CUSTOMER-FIRST-NAME",
          "phoneNumber": "CUSTOMER-PHONE-NUMBER",
          "userId": "US.13491208655302741912",          
          "parentUserId": "US.11815799212886844822",
          "username": "@Mike2334"
        },
        "action": "remove",
        "timestamp": 0
      }
    ]
  }
}

whatsapp.smb.message.echoes

Occurs when message sent by a business customer to a WhatsApp user with the WhatsApp Business app or a supported companion device.

Webhook parameter change specifications

Field Name	Data Type	Description
toUserId	String	New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted.
toParentUserId	String	New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely.
customerProfile	Object	New object. Only included for sent, delivered, and read status messages. Will be omitted entirely for failed status messages webhooks.
customerProfile.username	String	New property. Will be set to the WhatsApp user’s username if the user has enabled the usernames feature. Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature

Sample

{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",              <!-- ADDED --BSUID-->  
    "toParentUserId": "US.1181579921288684483",         <!-- ADDED-- PARENT_BSUID--> 
    "customerProfile": {                                <!-- ADDED-->
      "username": "@joee"                               <!-- ADDED-- USER_NAME-->
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "context": {
      "message_id": "wamid.BgNODYxN..."
    }
  }
}