使用业务范围用户 ID

为什么存在 BSUID

WhatsApp 将于 2026 年推出可选的用户名功能。当用户启用用户名后，WhatsApp 可以显示该用户名而非用户的电话号码，并可能在 Webhook 有效负载中省略电话号码。每个用户均可自主选择是否启用用户名，因此企业无法再仅依赖电话号码来识别客户。为此，Meta 要求 WhatsApp Business Platform 商业用户与合作伙伴，以及 Click-to-WhatsApp 广告主支持 BSUID，以便能够继续处理来自启用用户名用户的消息。为了支持这一变更，Meta 于 2026 年 4 月初开始在 Webhook 有效负载中添加业务范围用户 ID（BSUID）。BSUID 是单个 Meta 商业资产组合内单个 WhatsApp 用户的后端标识符。无论用户是否启用了用户名，Meta 都会在消息 Webhook 中包含该标识符；当用户的电话号码不可用时，可使用它向用户发送消息。用户名与 BSUID 具有不同的生命周期。用户可以在不更改电话号码或 BSUID 的情况下更改其用户名。如果用户更改了电话号码，Meta 将生成一个新的 BSUID。请分别存储这些标识符，并在收到电话号码变更系统事件时更新它们的关联。在商业电话号码与该用户在过去 30 天内曾互通消息或通话，或者 Meta 通讯录中包含该用户时，电话号码仍可能出现。请将电话号码和用户名字段视为条件性字段，并更新解析器与身份存储，以便在接收其他任何现有标识符的同时接收 BSUID。本指南涵盖 BSUID 身份规则、消息和通话请求、Meta 通讯录以及集成需要存储的 Webhook 字段。 WhatsApp 用户用户名示例

了解标识符

标识符	范围	示例	何时使用
电话号码	一个 WhatsApp 账户	`+16315551111`	在电话号码可用且操作需要时使用。
BSUID	一个 Meta 商业资产组合和一个 WhatsApp 用户	`US.13491208655302741918`	从同一商业资产组合中的任意商业电话号码使用。
父级 BSUID	一组关联的 Meta 商业资产组合和一个 WhatsApp 用户	`US.ENT.11815799212886844830`	仅在 Meta 为关联资产组合启用父级 BSUID 后使用。

Meta 会自动生成常规 BSUID。每个 BSUID 均以用户的 ISO 3166 alpha-2 两位字母国家/地区代码开头，后跟一个句点以及最多 128 个字母数字字符。请保留完整值。切勿删除或更改国家/地区前缀、句点或标识符字符。 BSUID 具有以下生命周期规则：

BSUID 对特定的商业资产组合与用户对具有唯一性。
当用户更改其电话号码时，该用户的 BSUID 会发生变更。
父级 BSUID 可跨 Meta 为其启用了该功能的关联资产组合使用。
商业电话号码不能使用作用域限定为另一个商业资产组合的常规 BSUID。

单触式、零触式和复制代码验证消息模板需要电话号码。请勿仅使用 BSUID 发送这些类型的消息模板。

要关联资产组合并使用父级 BSUID，请联系您的 Meta 对接人以检查资格。在 Meta 启用父级 BSUID 之后，您仍可继续在其原有资产组合内使用常规 BSUID。业务范围用户 ID 示例

准备工作

将您的 YCloud API 密钥存储在 YCLOUD_API_KEY 中。
使用与常规 BSUID 归属于同一商业资产组合的 WhatsApp 商业电话号码。
将您的 Webhook 端点订阅至集成所需的 WhatsApp 事件。
在反序列化 Webhook 时，将每个新的 BSUID、父级 BSUID、电话号码和用户名字段均视为可选字段。
当常规 BSUID 和父级 BSUID 同时存在时，请分别独立存储。

使用 BSUID 发送消息

两个 WhatsApp 消息端点均支持 recipient：

端点	行为
`POST /whatsapp/messages/sendDirectly`	同步将消息提交到 WhatsApp Business API。
`POST /whatsapp/messages`	将消息加入队列以进行异步提交。

将 recipient 设置为常规 BSUID 或父级 BSUID。当希望 YCloud 通过 BSUID 寻址用户时，请省略 to。

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hello from YCloud!"
    }
  }'

将相同的请求体与 POST /whatsapp/messages 配合使用以将消息排入队列。

输入	结果
仅 `to`	YCloud 发送至该电话号码。
仅 `recipient`	YCloud 发送至该 BSUID 或父级 BSUID。
同时提供 `to` 和 `recipient`	YCloud 将使用 `to` 并忽略 `recipient`。
两个字段均未提供	YCloud 将拒绝该请求。

请求用户的电话号码

当您的工作流程需要未包含在 Webhook 中的电话号码时，可以使用请求联系人信息消息。用户可自行决定是否共享。

使用模板按钮

在实用性或营销模板中添加 REQUEST_CONTACT_INFO 按钮。按钮文本固定为 Share Contact Info，且该按钮不接受发送时参数。

{
  "type": "buttons",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

在发送之前创建并获批该模板。完整的模板请求请参见请求电话号码模板。

使用交互式消息

在不需要模板时，可以发送交互式 request_contact_info 消息：

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "interactive",
    "interactive": {
      "type": "request_contact_info",
      "body": {
        "text": "Please share your phone number."
      },
      "action": {
        "name": "request_contact_info"
      }
    }
  }'

处理联系人响应

当用户共享联系人信息时，YCloud 会发送一个消息 type 为 contacts 的 whatsapp.inbound_message.received 事件。对于响应您的请求所共享的联系人，contacts[].origin 为 contact_request。

{
  "type": "whatsapp.inbound_message.received",
  "whatsappInboundMessage": {
    "fromUserId": "US.13491208655302741918",
    "type": "contacts",
    "contacts": [
      {
        "origin": "contact_request",
        "phones": [
          {
            "phone": "+16315551111",
            "wa_id": "16315551111"
          }
        ]
      }
    ]
  }
}

验证事件签名，使用 2xx 响应确认收到，并异步处理电话号码。直接从 WhatsApp 共享的联系人还可以包含 vCard。请求联系人信息按钮

了解 Meta 的通讯录

Meta 的通讯录存储用户电话号码与 BSUID 之间的关联。启用该功能后，使用用户的电话号码发送或接收消息或通话均会记录这两个标识符。即使用户启用了用户名，Meta 仍可在 Webhook 中包含该关联。通讯录归属于各个独立的业务资产组合（Business Portfolio）。关联的资产组合不会共享或同步其条目：请在每个资产组合中分别独立记录该关联。 Meta 会保留条目，直到您停用该功能或注销账户。您可以在 Meta Business Suite > 业务设置 > 业务信息 中停用它。停用该功能将删除已存储的条目并停止记录新条目。重新启用将开始收集新条目，但不会恢复已删除的数据。 Meta 通讯录设置

联系人请求与本地存储 (Local Storage)

当用户通过请求联系人信息按钮共享其电话号码时，如果已启用该功能，Meta 会将电话号码添加到通讯录中。对于使用本地存储的企业，Meta 会从共享的 vCard 中提取电话号码，并将其存储在 Meta 数据中心的通讯录中。其他 vCard 数据不会保留超过标准保留期。 Meta 取消了之前要求发送单独消息来捕获此关联的限制。有关当前的本地存储行为，请参见官方 BSUID 文档。

删除 Meta 通讯录条目

通过某个 WhatsApp 商业电话号码删除常规 BSUID 对应的 Meta 通讯录条目： DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}

curl --request DELETE \
  "https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/%2B16315551111/contactBook/US.13491208655302741918" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Accept: application/json"

此操作请使用标准 BSUID。不支持包含 .ENT. 的父级 BSUID。手动构建路径时，请对电话号码前导的 + 进行 URL 编码，写为 %2B。 HTTP 200 响应始终包含 success: true。deleted 值为 true 表示 Meta 删除了匹配的条目。值为 false 表示 Meta 处理了请求但未找到匹配的条目。删除条目不会删除 YCloud 联系人、消息或 BSUID 业务记录。删除后，同一 Meta 业务资产组合中商业电话号码的 Webhook 事件将不再同时包含用户的电话号码和 BSUID。Meta 的 30 天缓存仍可能会提供这两个标识符，后续的互动也可以再次创建该通讯录条目。

使用 BSUID 发起通话

POST /whatsapp/calls/connect 也接受 recipient。适用相同的目标规则：提供 to 或 recipient，两者均存在时以 to 为准。

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/calls/connect \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "sdpType": "offer",
    "sdp": "SDP_OFFER"
  }'

有关完整的通话生命周期，请参见管理 WhatsApp 通话。

处理 BSUID Webhook 字段

以下 YCloud Webhook 有效载荷展示了为支持 BSUID 新增或修改的字段。请更新您的解析程序以接收新标识符并处理客户电话号码缺失的情况。

标记	含义
`<ADDED>`	为支持 BSUID 引入的新可选字段或对象。
`<CHANGED>`	现有的客户电话号码字段可能会被省略；其名称保持不变。
无标记	保留的现有字段，用于展示事件的完整结构。

示例中包含了 YCloud 事件封包，并展示了各字段出现的位置。可选字段遵循下方的省略规则。在将有效载荷用作 JSON 测试数据之前，请移除 // <ADDED> 和 // <CHANGED> 注释。

事件	需存储的可选字段
`whatsapp.message.updated`	`whatsappMessage.recipientUserId`, `whatsappMessage.parentRecipientUserId`, `whatsappMessage.customerProfile.name`, `whatsappMessage.customerProfile.username`
`whatsapp.inbound_message.received`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`
`whatsapp.user.preferences`	`whatsappUserPreference.userId`, `whatsappUserPreference.parentUserId`
`whatsapp.call.connect`	`callingConnect.toUserId`, `callingConnect.toParentUserId`, `callingConnect.fromUserId`, `callingConnect.fromParentUserId`
`whatsapp.call.terminate`	`callingTerminate.toUserId`, `callingTerminate.toParentUserId`, `callingTerminate.fromUserId`, `callingTerminate.fromParentUserId`
`whatsapp.call.status.updated`	`callingStatusUpdated.recipientUserId`, `callingStatusUpdated.parentRecipientUserId`
`whatsapp.group.participants_update`	`whatsappGroup.recipientUserId`、`whatsappGroup.parentRecipientUserId`、`whatsappGroup.customerProfile.username`，以及 `whatsappGroup.addedParticipants[]`、`whatsappGroup.removedParticipants[]` 和 `whatsappGroup.failedParticipants[]` 中的 `recipientUserId` 和 `parentRecipientUserId` 字段
`whatsapp.smb.history`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`, `whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`
`whatsapp.smb.app.state.sync`	`whatsappSmbAppStateSync.stateSync[].contact.userId`, `whatsappSmbAppStateSync.stateSync[].contact.parentUserId`, `whatsappSmbAppStateSync.stateSync[].contact.username`
`whatsapp.smb.message.echoes`	`whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`, `whatsappMessage.customerProfile.username`

遵循以下缺省规则：

当未启用父级 BSUID 时，父级 BSUID 字段将缺省。
如果您通过电话号码指定目标用户，则已发送消息或通话目标字段可能会缺省。
customerProfile 会出现在 sent、delivered 和 read 消息更新中，但不会出现在 failed 更新中。
当用户未启用用户名时，customerProfile.username 将缺省。它在 sent 状态更新中也会缺省。
即使对应的 BSUID 存在，电话号码也可能会缺省。

whatsapp.message.updated

该示例显示了一条已送达的消息。当电话号码不可用时，<CHANGED> 会将 to 标记为条件性字段。新增的 customerProfile 对象在 failed 中会被省略；对于 sent 或当用户没有用户名时，其 username 也会被省略。

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "delivered",
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "name": "Example customer", // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.inbound_message.received

将新的发送者标识符与现有的个人资料名称一起保存。企业接收者 to 保持不变；客户电话号码 from 可以省略。关于 system 消息，请参阅下方的更换电话号码示例。

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.user.preferences

偏好设置保留在 whatsappUserPreference 下。即使 contactPhoneNumber 缺省，也请使用所提供的用户标识符。

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": "WABA_ID",
    "businessPhoneNumber": "+16315551111",
    "businessPhoneId": "BUSINESS_PHONE_ID",
    "contactName": "Example customer",
    "contactPhoneNumber": "+16315552222", // <CHANGED>
    "userId": "US.13491208655302741918", // <ADDED>
    "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1791532800000"
  }
}

whatsapp.call.connect

对于企业发起的通话，客户标识符为 toUserId 和 toParentUserId。对于用户发起的通话，它们为 fromUserId 和 fromParentUserId。在这些示例中，只有客户电话号码字段可以省略。

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "answer",
    "sdp": "SDP_CONTENT"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "offer",
    "sdp": "SDP_CONTENT"
  }
}

whatsapp.call.terminate

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

whatsapp.call.status.updated

接收者标识符是 callingStatusUpdated 下 recipientPhone 的同级字段。

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingStatusUpdated": {
    "wabaId": "WABA_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "status": "RINGING",
    "recipientPhone": "+16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.group.participants_update

单个参与者更新可以直接在 whatsappGroup 下携带标识符。批量结果则在 addedParticipants、removedParticipants 或 failedParticipants 的每个项目中携带它们。请处理事件中对应操作的数组。

added
removed
failed

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "GROUP_ID@g.us",
    "addedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z",
    "waId": "16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "status": "removed",
    "groupId": "GROUP_ID@g.us",
    "removedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "failed",
    "groupId": "GROUP_ID@g.us",
    "failedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        },
        "errors": [
          {
            "code": 131000,
            "title": "Something went wrong",
            "message": "Please retry later."
          }
        ]
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

whatsapp.smb.history

保留特定事件的包装层：入站历史记录使用 whatsappInboundMessage，而出站历史记录使用 whatsappMessage。出站 toUserId 和 toParentUserId 是 recipientUserId 和 parentRecipientUserId 的兼容别名。这些示例展示了携带消息的事件；仅包含元数据的历史记录块可以省略这两个消息对象。

入站历史记录
出站历史记录

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.smb.app.state.sync

此有效负载保留自旧版 BSUID 迁移文档。该事件未列在当前的公开可订阅事件目录中；请勿根据此示例将其添加到 enabledEvents。仅在维护已经接收此旧版负载的集成时使用以下结构。

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.app.state.sync",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappSmbAppStateSync": {
    "wabaId": "WABA_ID",
    "phoneNumber": "+16315551111",
    "stateSync": [
      {
        "contact": {
          "fullName": "Example customer",
          "firstName": "Example",
          "phoneNumber": "+16315552222", // <CHANGED>
          "userId": "US.13491208655302741918", // <ADDED>
          "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
          "username": "example_customer" // <ADDED>
        },
        "action": "add",
        "timestamp": 1791532800000
      }
    ]
  }
}

whatsapp.smb.message.echoes

这些是从 WhatsApp Business 应用或受支持的配套设备发送的消息。旧版字段名称 toUserId 和 toParentUserId 是 recipientUserId 和 parentRecipientUserId 的兼容别名。个人资料保留在 whatsappMessage 下。

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

处理用户更换电话号码

当 whatsappInboundMessage.type 为 system 且 system.type 为 user_changed_number 时，外层发送者字段标识旧的用户身份。嵌套的 system 字段包含新的 BSUID 以及可用的新电话号码。请使用 system 内部的字段名称 user_id 和 parent_user_id。

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "system",
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    },
    "system": {
      "type": "user_changed_number",
      "wa_id": "16315553333", // <CHANGED>
      "user_id": "US.13491208655302741919", // <ADDED>
      "parent_user_id": "US.ENT.11815799212886844831" // <ADDED>
    }
  }
}

将 parent_user_id 视为可选字段。wa_id 中的新电话号码也可能会省略，因此请使用 user_id 以及提供的任何 parent_user_id 来更新身份映射。妥善保留新旧值，其保留时间应足以用于对齐现有会话并对身份存储库进行幂等更新。

企业用户名

企业用户名有助于客户在 WhatsApp 中找到您的企业。它不会隐藏您的企业电话号码。每个电话号码可以拥有一个用户名，且同一个用户名不能被两个 WhatsApp 电话号码共用。消费者的用户名可以在不更改该用户 BSUID 的情况下更改。请将用户名作为个人资料信息保存，而不是将其用作身份键。有关 3–35 个字符的格式规则以及认领与审核流程，请参阅认领企业用户名。企业用户名示例

保留用户名

您可以认领 Meta 保留的符合条件的用户名，或为您的品牌选择其他用户名。可以使用 WhatsApp 管理工具、Meta Business Suite 或用户名 API。获得批准本身并不意味着该用户名已对客户生效。如果预留用户名属于您的 Facebook 主页或 Instagram 账户，请在认领前将您的商业电话号码关联到该主页或账户。您可以在 Meta Business Suite 或 WhatsApp 管理工具中认领用户名时进行关联，也可以将电话号码添加到主页或账户。您需要完全控制权或具有 manage_phone 权限的基本部分访问权限。

聊天窗口显示优先级

WhatsApp 按照以下顺序显示商家身份：

客户通讯录中保存的名称。
已验证的商家名称或官方商业账户名称。
商家用户名。
电话号码。

您的商业电话号码在商业资料中仍保持可见。

迁移核对清单

将每个与 BSUID 相关的 Webhook 字段添加到您的反序列化模型中，作为可选字段。
将常规和父级 BSUID 与电话号码及用户名分开存储。
按业务资产组合（portfolio）和 BSUID 索引客户身份。请勿将 BSUID 视为全局通用的标识符。
通过 to 或 recipient 路由消息和通话请求，并测试 to 优先级规则。
测试仅用户名用户、缺少电话号码、电话号码变更、缺少父级 BSUID、重复 Webhook 以及通讯录重建等场景。

消息状态示例

检查已发送、已送达、已读和失败的消息载荷。

入站消息示例

检查联系人、系统更新及其他入站载荷。

开始使用

指南

接口

Webhooks

使用业务范围用户 ID

为什么存在 BSUID

了解标识符

准备工作

使用 BSUID 发送消息

请求用户的电话号码

使用模板按钮

使用交互式消息

处理联系人响应

了解 Meta 的通讯录

联系人请求与本地存储 (Local Storage)

删除 Meta 通讯录条目

使用 BSUID 发起通话

处理 BSUID Webhook 字段

处理用户更换电话号码

企业用户名

保留用户名

聊天窗口显示优先级

迁移核对清单

消息状态示例

入站消息示例

​为什么存在 BSUID

​了解标识符

​准备工作

​使用 BSUID 发送消息

​请求用户的电话号码

​使用模板按钮

​使用交互式消息

​处理联系人响应

​了解 Meta 的通讯录

​联系人请求与本地存储 (Local Storage)

​删除 Meta 通讯录条目

​使用 BSUID 发起通话

​处理 BSUID Webhook 字段

​处理用户更换电话号码

​企业用户名

​保留用户名

​聊天窗口显示优先级

​迁移核对清单

消息状态示例

入站消息示例

为什么存在 BSUID

了解标识符

准备工作

使用 BSUID 发送消息

请求用户的电话号码

使用模板按钮

使用交互式消息

处理联系人响应

了解 Meta 的通讯录

联系人请求与本地存储 (Local Storage)

删除 Meta 通讯录条目

使用 BSUID 发起通话

处理 BSUID Webhook 字段

处理用户更换电话号码

企业用户名

保留用户名

聊天窗口显示优先级

迁移核对清单