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

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

This document describes all the api changes for BSUID support. These changes are backward compatible. Existing fields are unchanged.

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.

WhatsApp Messages

Send a message directly

The message is submitted to the WhatsApp Business API synchronously. Typically used for sending OTP and instant messages.

Parameter change specifications

Field Name	Data Type	Description
recipient	String	New property. Can be set to the user’s BSUID or parent BSUID.

Sample:

curl --request POST \
     --url https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
     --header 'X-API-Key: {{apikey}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data 
'{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "recipient": "US.13491208655302741918",       <!-- ADDED --> 
  "type": "text",
  "text": {
    "body": "hello",
  }
}'

You can include both to (phone number) and recipient (BSUID or parent BSUID) in your request. If you do, to (phone number) will take precedence. If you prefer, you can also use one or the other:

To send a message using only the user’s phone number:

set to to the user’s phone number
omit the recipient property

To send a message using only the user’s BSUID or parent BSUID:

set recipient to the user’s BSUID or parent BSUID
omit the to property

Enqueue a message

Enqueues an outbound WhatsApp message for sending. Queued messages will be submitted to the WhatsApp Business API asynchronously.

Parameter change specifications

Field Name	Data Type	Description
recipient	String	New property. Can be set to the user’s BSUID or parent BSUID.

Sample:

curl --request POST \
     --url https://api.ycloud.com/v2/whatsapp/messages \
     --header 'X-API-Key: {{apikey}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data 
'{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "recipient": "US.13491208655302741918",       <!-- ADDED --> 
  "type": "text",
  "text": {
    "body": "hello",
  }
}'

You can include both to (phone number) and recipient (BSUID or parent BSUID) in your request. If you do, to (phone number) will take precedence. If you prefer, you can also use one or the other:

To send a message using only the user’s phone number:

set to to the user’s phone number
omit the recipient property

To send a message using only the user’s BSUID or parent BSUID:

set recipient to the user’s BSUID or parent BSUID
omit the to property

Requesting phone numbers from users

Using templates request-phone-number-template

To add a request contact information button to a utility or marketing template, include a REQUEST_CONTACT_INFO button in the components array when creating the template:

curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "{{TEMPLATE_NAME}}",
  "language": "en",
  "category": "utility",
  "components": [
    {
      "type": "body",
      "text": "<BODY_TEXT>"
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "REQUEST_CONTACT_INFO",
          "text": "Share Contact Info"
        }
      ]
    }
  ]
}'

Request contact information buttons cannot be customized, so you do not need to include any parameter values when sending the template:

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "recipient": "US.13491208655302741918",
  "type": "template",
  "template": {
    "name": "{{TEMPLATE_NAME}}",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    }
  }
}'

Using interactive messages

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "recipient": "US.13491208655302741918",
  "type": "interactive",
  "interactive": {
    "type": "request_contact_info",
    "body": {
      "text": "<BODY_TEXT>"
    },
    "action": {
      "name": "request_contact_info"
    }
  }
}'

Contacts webhook

When a user shares their contact information — either by tapping a REQUEST_CONTACT_INFO button or by sharing a contact directly in the chat — a contacts webhook will be triggered.

{
  "id": "evt_6a18081bb809230f21d55148",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-05-28T09:17:15.512Z",
  "whatsappInboundMessage": {
    "id": "6a18081bb809230f21d55147",
    "wamid": "wamid.HBgNODYxODI1...",
    "wabaId": "WABA-ID",
    "from": "WHATSAPP_BUSINESS_PHONE_NUMBER",
    "fromUserId": "CN.2123983504836150",
    "customerProfile": {
      "name": "whatsapp name",
      "username": "USERNAME"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2026-05-28T09:17:14.000Z",
    "type": "contacts",
    "contacts": [
      {
        "name": {
          "formatted_name": "whatsapp name",
          "first_name": "whatsapp first name"
        },
        "phones": [
          {
            "phone": "WHATSAPP_BUSINESS_PHONE_NUMBER",
            "type": "MOBILE",
            "wa_id": "WHATSAPP_BUSINESS_PHONE_NUMBER"
          }
        ],
        "vcard": "QkVHSU46VkNBUkQK...",
        "origin": "contact_request"
      }
    ]
  }
}

WhatsApp 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
  }
}

WhatsApp Calling

Connect a call

Initiates a WhatsApp call connection.

Establishes the initial connection for a WhatsApp call by providing SDP offer information. This endpoint is used for business-initiated calling scenarios.

Parameter change specifications

Field Name	Data Type	Description
recipient	String	New property. Can be set to the user’s BSUID or parent BSUID.

Sample:


curl 'https://api.ycloud.com/v2/whatsapp/calls/connect' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
    "from": "+62831382000",
    "to": "+6281369051330",
    "recipient": "US.13491208655302741918",       <!-- ADDED --> 
    "sdpType": "offer",
    "sdp": "RFC 4566 OFFER SDP"
}'

You can include both to (phone number) and recipient (BSUID or parent BSUID) in your request. If you do, to (phone number) will take precedence. If you prefer, you can also use one or the other:

To send a message using only the user’s phone number:

set to to the user’s phone number
omit the recipient property

To send a message using only the user’s BSUID or parent BSUID:

set recipient to the user’s BSUID or parent BSUID
omit the to property

WhatsApp Calling webhooks

Call permission update

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-->
 }
}

WhatsApp coexistence 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..."
    }
  }
}