为什么需要 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 字段。
了解各类标识符
Meta 会自动生成常规 BSUID。每个 BSUID 均以用户的 ISO 3166 alpha-2 两位字母国家/地区代码开头,后跟一个句点及最多 128 个字母数字字符。请保留完整的值。请勿删除或更改国家/地区前缀、句点或标识符字符。
BSUID 具有以下生命周期规则:
- BSUID 对于单个业务资产组合和用户配对是唯一的。
- 当用户更改其电话号码时,用户的 BSUID 会发生变更。
- 父 BSUID 适用于 Meta 已为其启用的关联资产组合。
- 商业电话号码无法使用作用于另一个 资产组合的常规 BSUID。
准备工作
- 将您的 YCloud API 密钥存储在
YCLOUD_API_KEY中。 - 使用由该常规 BSUID 所属的同一资产组合所拥有的 WhatsApp 商业 电话号码。
- 让您的 Webhook 端点订阅集成所使用的 WhatsApp 事件。
- 反序列化 Webhook 时,将每个新的 BSUID、父 BSUID、电话号码和用户名 字段视为可选字段。
- 当常规 BSUID 和父 BSUID 同时存在时,分别独立存储它们。
使用 BSUID 发送消息
两个 WhatsApp 消息端点均支持recipient:
将
recipient 设置为常规 BSUID 或父 BSUID。当您希望 YCloud 按 BSUID 发送给用户时,请省略 to。
POST /whatsapp/messages 使用相同的请求体将消息排入队列。
请求用户手机号
当您的工作流程需要 Webhook 中未包含的手机号时,请使用请求联系人信息消息。由用户决定是否分享。使用模板按钮
在效用或营销模板中添加REQUEST_CONTACT_INFO 按钮。按钮文本固定为 Share Contact Info,且该按钮不接受发送时参数。
使用交互式消息
当您不需要模板时,发送交互式request_contact_info 消息:
处理联系人回复
当用户分享联系人信息时,YCloud 会发送一个消息type 为 contacts 的 whatsapp.inbound_message.received 事件。对于您请求的回复,contacts[].origin 为 contact_request。
2xx 响应确认收到,并异步处理该手机号。直接从 WhatsApp 分享的联系人还可以包含 vCard。
了解 Meta 的通讯录
Meta 的通讯录存储用户手机号与 BSUID 之间的关联。启用该功能后,使用用户的手机号发送或接收消息或通话都会记录这两个标识符。即使在用户采用用户名之后,Meta 仍可在 Webhook 中包含该关联。 通讯录归属于单个业务资产组合。关联合并的资产组合不会共享或同步其条目:请在每个资产组合中分别记录该关联。 Meta 会保留这些条目,直到您停用该功能或停用您的账户。您可以在 Meta Business Suite > 业务设置 > 业务信息 中停用它。停用该功能会删除已存储的条目并停止记录新条目。重新启用会开始收集新条目,但不会恢复已删除的数据。
联系人请求与本地存储 (Local Storage)
当用户通过请求联系人信息按钮分享手机号时,如果启用了该功能,Meta 会将手机号添加到通讯录中。对于使用本地存储 (Local Storage) 的企业,Meta 会从分享的 vCard 中提取手机号并存储在 Meta 数据中心的通讯录中。超出标准保留期后,其他 vCard 数据将不再保留。 Meta 已经取消了先前要求发送单独消息来记录此关联的规定。有关当前的本地存储行为,请参阅 官方 BSUID 文档。检查 Meta 通讯录条目
使用GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid} 检查 Meta 是否存在标准 BSUID 的手机号条目。此操作不会返回手机号或修改该条目。
403。WABA 必须可供您的账户使用,手机号必须绑定到该 WABA,且标准 BSUID 必须属于同一个 Meta 业务资产组合。不支持包含 .ENT. 的父级 BSUID。手动构建路径时,请将手机号开头的 + URL 编码为 %2B。
成功的响应始终包含布尔值 present:
200 且 present: false 表示不存在匹配的条目。无效输入、权限失败和上游错误仍然属于错误。上游 HTTP 404 并不意味着 present: false。
删除 Meta 通讯录条目
通过一个 WhatsApp 商业手机号删除常规 BSUID 的 Meta 通讯录条目:DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{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 优先。
处理 BSUID Webhook 字段
以下 YCloud Webhook 有效负载显示了针对 BSUID 支持添加或更改的字段。请更新您的解析器以接受新的标识符并处理缺失的客户电话号码。
这些示例包含 YCloud 事件信封,并显示了每个字段出现的位置。可选字段遵循下方的省略规则。在将有效负载用作 JSON 测试数据之前,请删除
// <ADDED> 和 // <CHANGED> 注释。
应用以下省略规则:
- 未启用父级 BSUID 时,父级 BSUID 字段不存在。
- 如果您通过电话号码定位用户, 已发送消息或通话目标字段可以不存在。
customerProfile会出现在sent、delivered和read消息更新中, 但不会出现在failed更新中。- 当用户未启用用户名时,
customerProfile.username不存在。 它在sent状态更新中也不存在。 - 即使对应的 BSUID 存在,电话号码也可能不存在。
whatsapp.message.updated
whatsapp.message.updated
该示例展示了一条已送达的消息。当电话号码不可用时,
<CHANGED> 将 to 标记为有条件的。对于 failed,新的 customerProfile 对象会被省略;对于 sent 或当用户没有用户名时,其 username 也会被省略。whatsapp.inbound_message.received
whatsapp.inbound_message.received
将新的发送者标识符与现有的个人资料名称一起存储。企业接收者
to 保持不变;客户电话号码 from 可以省略。请参阅下方的电话号码变更示例以了解 system 消息。whatsapp.user.preferences
whatsapp.user.preferences
偏好设置仍保留在
whatsappUserPreference 下。即使 contactPhoneNumber 不存在,也请使用提供的用户标识符。whatsapp.call.connect
whatsapp.call.connect
对于企业发起的通话,客户标识符为
toUserId 和 toParentUserId。对于用户发起的通话,它们为 fromUserId 和 fromParentUserId。在这些示例中,仅客户电话号码字段可以省略。- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.terminate
whatsapp.call.terminate
对于企业发起的通话,客户标识符为
toUserId 和 toParentUserId。对于用户发起的通话,它们为 fromUserId 和 fromParentUserId。在这些示例中,仅客户电话号码字段可以省略。- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.status.updated
whatsapp.call.status.updated
接收者标识符是
callingStatusUpdated 下 recipientPhone 的同级字段。whatsapp.group.participants_update
whatsapp.group.participants_update
单个参与者更新可以直接在
whatsappGroup 下携带标识符。批量结果会在 addedParticipants、removedParticipants 或 failedParticipants 中的每个项目上携带它们。请处理事件中对应操作的数组。- added
- removed
- failed
whatsapp.smb.history
whatsapp.smb.history
保留特定于事件的包装器:入站历史记录使用
whatsappInboundMessage,而出站历史记录使用 whatsappMessage。出站 toUserId 和 toParentUserId 是 recipientUserId 和 parentRecipientUserId 的兼容性别名。这些示例显示了包含消息的事件;仅包含元数据的历史记录块可以省略这两个消息对象。- 入站历史记录
- 出站历史记录
whatsapp.smb.app.state.sync
whatsapp.smb.app.state.sync
此有效负载保留自旧版 BSUID 迁移文档。此事件未列在当前公开的可订阅事件目录中;请勿根据此示例将其添加到
enabledEvents。在维护已接收此旧版有效负载的集成时,请使用以下结构。whatsapp.smb.message.echoes
whatsapp.smb.message.echoes
这些是从 WhatsApp Business 应用或受支持的配套设备发送的消息。旧版字段名称
toUserId 和 toParentUserId 是 recipientUserId 和 parentRecipientUserId 的兼容性别名。请将个人资料保留在 whatsappMessage 下。处理电话号码和 BSUID 变更
当whatsappInboundMessage.type 为 system 时,处理两种身份变更变体:
对于新身份,请使用
system.user_id 以及所提供的任何 system.parent_user_id。对于先前的身份,请在提供时使用 system.previous_user_id 和 system.previous_parent_user_id。这些嵌套字段保留了 Meta 原本的蛇形命名法(snake_case)名称。
以下示例展示了电话号码变更:
wa_id 是不带前导 + 的电话号码,可以省略;对于 user_changed_user_id,它也可以保持不变。不要仅仅因为事件中省略了现有电话号码就将其清除。请保留原标识符和新标识符足够长的时间,以便对账现有对话并以幂等方式更新您的身份存储。
有关没有电话号码的示例,请参阅入站 BSUID 变更消息。
商业用户名
商业用户名有助于客户在 WhatsApp 中找到您的业务。它不会隐藏您的商业电话号码。每个电话号码可以拥有一个用户名,且一个用户名不能由两个 WhatsApp 电话号码共用。 消费者用户名可能会发生变化,但用户的 BSUID 保持不变。请将用户名作为个人资料信息保存,而不是将其用作您的身份键。 有关 3–35 个字符的格式规则以及认领和审核流程,请参阅认领商业用户名。
预留用户名
您可以认领由 Meta 预留的符合条件的用户名,也可以为您的品牌选择其他用户名。使用 WhatsApp 管理工具、Meta Business Suite 或用户名 API。审核通过本身并不意味着用户名已对客户生效。 如果预留用户名属于您的 Facebook 公共主页或 Instagram 帐户,请在认领之前将您的商业电话号码关联到该公共主页或帐户。您可以在 Meta Business Suite 或 WhatsApp 管理工具中认领用户名时进行关联,也可以将电话号码添加到公共主页或帐户。您需要拥有完全控制权或具有manage_phone 权限的基础部分访问权限。
聊天窗口显示优先级
WhatsApp 按以下顺序显示商家身份:- 保存在客户通讯录中的名称。
- 已验证的商家名称或官方商业账户名称。
- 商业用户名。
- 电话号码。
迁移核对清单
- 将每个与 BSUID 相关的 Webhook 字段作为可选字段添加到 反序列化模型中。
- 将常规 BSUID 和父级 BSUID 与电话号码和用户名分开存储。
- 按业务资产组合和 BSUID 对客户身份建立索引。不要将 BSUID 视为 全局通用的标识符。
- 通过
to或recipient路由消息和通话请求,并测试to优先级规则。 - 测试仅限用户名的用户、缺失电话号码、电话号码变更、 电话号码未变时的 BSUID 变更、缺失父级 BSUID、重复的 Webhook,以及通讯录存在与重建。
消息状态示例
检查已发送、已送达、已读和失败的消息载荷。
入站消息示例
检查联系人、系统更新以及其他入站载荷。

