WhatsApp 即将上线用户名（Username）功能，部分用户的手机号将不再出现在消息回调中。本文介绍如何使用 Business-Scoped User ID保障消息收发不中断，以及您需要完成的对接改造。
功能介绍
背景
Meta 正在为 WhatsApp 引入用户名（Username）功能。用户启用后，其用户名将在 App 中替代手机号显示，手机号也将不再默认出现在发给商家的 Webhook 中，若用户没有在 WhatsApp 中启用用户名功能，则 Webhook 中仍然会包括用户的手机号码。
为了让商家在用户启用用户名后仍能正常识别用户、收发消息，Meta 引入了一个新的用户标识符——Business-Scoped User ID，简称 BSUID。
BSUID 功能在 Meta 侧将分批开放，Meta 预计将于2026年9月全球发布，在全量发布之前，您可能不会遇到手机号为空的情况。正式时间以 Meta 公布为准。
此文档用于介绍 Meta BSUID 功能，Webhook 部分非 API 客户可无需关注。
什么是 BSUID
BSUID 是 WhatsApp 为每位用户自动生成的唯一标识符，与您的 BM（Business Manager）绑定。无论用户是否启用用户名功能，BSUID 都会出现在所有消息 Webhook 中。
BSUID 的格式为两字母国家代码加句点，后跟字母数字字符串，例如：
US.13491208655302741918BSUID 具有以下特性：
由 Meta 系统自动生成，无需手动申请
与您的 BM 绑定。同一个 BM 下，无论您有多少个 WABA、多少个商家号码，面对同一位用户拿到的都是同一个 BSUID，任意商家号码均可使用该 BSUID 向用户发消息
不同 BM 之间的 BSUID 相互隔离。即使是同一位用户，在不同 BM 下会有不同的 BSUID，不可混用
BSUID 仅在用户更换手机号时重新生成，并通过 Webhook 通知您新旧 BSUID 的对应关系。用户启用或禁用用户名功能、更改用户名，均不会影响其 BSUID
如何使用 BSUID
BSUID 的主要用途有两个：识别用户和发送消息。
识别用户
在现有的集成中，您可能使用手机号作为识别用户的唯一标识。引入 BSUID 后，建议将 BSUID 作为主要的用户标识符存储在您的系统中，并与手机号、会话记录、用户标签等数据进行关联。
从 2026 年 7 月 15 日，所有消息 Webhook 中将包含 UserId （消息状态中出现）或FromUserId（上行消息中出现）字段，其值即为该用户的 BSUID。您可以从现在开始读取并存储这一字段，为后续对接做好准备。
发送消息
从 2026 年 7 月 15 日，您可以直接使用 BSUID 向用户发送消息，无需手机号。这对于用户启用用户名功能后手机号不可见的场景尤为重要。历史上通过手机号码主动发送消息给终端客户的流程不受 BSUID 影响，您仍然可以直接通过用户手机号发送消息。
手机号和 BSUID 可以同时使用，也可以单独使用。同时提供时，手机号优先。需要注意的是，身份验证类模板（one-tap、zero-tap、copy code）不支持 BSUID，必须使用手机号发送消息。
Parent BSUID （父级 BSUID)
父级 BSUID 用于企业跨 BM 识别同一个用户使用。如果您的企业拥有多个 BM，不同 BM 下的 BSUID 是相互隔离的，无法跨 BM 识别或联系同一位用户。若需要跨 BM 统一识别和联系用户，请联系阿里云向 Meta 申请开通 Parent BSUID 使用权限。
权限开通后。面对同一位用户，不同 BM 下的任意商家号码均可使用该 Parent BSUID 发消息，无需分别维护各 BM 下的 BSUID。
Parent BSUID 的格式包含 ENT 标识，例如：
US.ENT.11815799212886844830开通后，Webhook 中会同时包含该 BM 下的普通 BSUID 和 Parent BSUID。Parent BSUID 需申请开通。
企业必要改造
以下是本次变更中必须完成的修改项。如未完成，将直接影响您与用户的正常通信。
上行消息处理（接收用户消息）
当用户启用用户名功能后，以下情况将不会再包括用户手机号码：
纯新用户（此前完全没有与您的商家号码有过任何互动）
您和用户之间在 30 天内没有使用手机号码有过消息交互
其发来的消息中将不包含手机号，Webhook 中只有 BSUID。如果您的系统强依赖手机号来识别用户或建立会话，将无法处理这类消息，也无法向该用户回复。
若用户没有在 WhatsApp 中启用用户名功能，则 Webhook 中仍然会包括用户的手机号码。
必须修改：
Webhook 解析逻辑中，手机号相关字段（
from）可能是手机号码也可能是用户 BSUID。必须读取并存储
FromUserId字段（BSUID），将其作为识别用户的主要标识符。企业系统中与用户相关的会话、记录、标签等数据，必须支持以 BSUID 进行关联和查询（需企业自行存储手机号码与 BSUID 的关联关系，Chat App 消息服务不做处理）。
下行消息发送（向用户发送消息）
当用户启用用户名功能且首次向您发送消息或者您与该用户的交互超出 30 天窗口期后，您将只能获取到该用户的 BSUID，而无法获取其手机号。如果您的发送接口只支持手机号，将无法向这类用户发送任何消息，所以您需要对您的发送接口进行改造以支持通过 BSUID 进行消息发送或消息回复。
如果您的业务只涉及商家主动通过手机号码发送消息给终端用户且不对用户上行消息进行回复，则无需关注 BSUID 。但是仍然建议您对 BSUID 进行兼容，以便处理纯新用户或交互超出 30 天窗口期后给您的商家号码上行消息时无用户手机号码导致的无法识别用户的情况。
Chat App 消息服务使用 BSUID 发送消息的能力将于2026 年 7 月 15 日开放。
必须修改：
发送消息时，必须支持以 BSUID 作为目标标识符。
企业系统中存储的用户标识符，必须包含 BSUID，以备手机号不可用时使用。
不受影响的场景
以下场景在本次变更后不受影响，无需修改现有逻辑：
通过已有手机号发送消息：如果您的系统中已存有用户手机号，直接使用手机号发送消息的方式不受任何影响，继续正常使用即可。
未启用用户名的用户：对于未启用用户名功能的用户，Webhook 中的手机号字段与现在完全一致，不会有任何变化。
30 天内有过交互的用户：即使用户启用了用户名功能，只要您在 30 天内与该用户有过消息或通话交互，其手机号仍会出现在 Webhook 中，现有逻辑不受影响。
企业通讯录中的用户：存入企业通讯录的用户，其手机号将始终出现在 Webhook 中，通讯录为 Meta 提供的功能，该功能不提供页面查询。
计费与数据分析：本次变更不涉及计费规则和分析数据结构的调整。
为了保证您的消息可以正常发送和接收，强烈建议您对 BSUID 进行兼容改造。
不改造的影响
如果未能完成 BSUID 对接，随着用户名功能的逐步普及，以下问题将持续出现并不断扩大影响范围。
无法处理部分用户的上行消息
当用户启用用户名功能且不满足 30 天交互条件时，Webhook 中将不包含手机号。若您的系统依赖手机号识别用户，将无法匹配这类用户，导致消息处理失败、无法回复，对话上下文丢失。
无法向部分用户发送消息
若您的发送逻辑仅支持手机号，当手机号不可用时，将无法主动触达这类用户。随着越来越多的用户启用用户名功能，若您的系统发送接口不支持 BSUID 格式，将导致消息触达率将持续下降。
系统稳定性风险
若您的代码假设
from字段始终认为是手机号码，那么当 from 是 BSUID 时，可能引发程序异常，影响整体系统稳定性。历史会话关联断裂
现有用户启用用户名功能后，若您的系统无法通过 BSUID 关联历史记录，将导致客户信息碎片化，无法为用户提供连续的服务体验。
影响范围随时间持续扩大
用户名功能将在逐步向所有 WhatsApp 用户开放。初期影响可能有限，但随着采用率提升，未完成改造的系统将面临越来越多无法处理的用户和消息，建议尽早完成对接。
上行消息时手机号码的可见性
当用户启用用户名功能后，其手机号默认不再出现在 Webhook 中。但在以下任一条件满足时，手机号仍会被包含：
在 Webhook 触发前 30 天内，曾向该用户的手机号发送过消息或拨打过电话
在 Webhook 触发前 30 天内，曾收到过该用户手机号发来的消息或来电
该用户已存入您的联系人通讯录（Contact Book）
上述 30 天条件按商家号码维度独立计算。若您在同一个 WABA 下使用多个商家号码，某一个商家号码满足条件，不代表其他商家号码也满足。
发送消息场景说明
发送消息时，手机号和 BSUID 可以灵活选择使用，以下是不同场景下的建议。
何时使用手机号发送
以下情况建议优先使用手机号发送消息：
您已知用户手机号：系统中已存有用户手机号，直接使用即可，无需任何改动。
需要维持 30 天交互窗口：向用户手机号发送消息后，在接下来的 30 天内，Webhook 中会持续包含该用户的手机号，有助于保持对话上下文的连续性。
发送身份验证类模板：身份验证类模板不支持 BSUID 发送，必须使用手机号发送。
何时使用 BSUID 发送
以下情况建议使用 BSUID 发送消息：
手机号不可用：用户已启用用户名功能，且不满足 30 天交互条件，Webhook 中仅包含 BSUID 而无手机号。
超出 30 天未互动的用户：与用户的最近一次交互已超过 30 天，手机号不再出现在 Webhook 中，此时只能通过 BSUID 回复消息。
跨 BM 通信（使用 Parent BSUID）：您的企业拥有多个 BM 且已开通 Parent BSUID，希望使用统一的标识符跨 BM 联系同一位用户。
Webhook 变化说明 （需要整体确定 Chat App 中的 Webhook 字段名称）
入站消息 Webhook
收到用户发来的消息时，Webhook 中的用户标识字段变化如下：
字段 | 说明 | 变化说明 |
FromUserId | 用户 BSUID | 新增。始终包含用户 BSUID |
FromUserName | 用户名 | 新增。用户启用用户名时包含 |
From | 消息发送方手机号 | 可能为空。 |
FromParentUserId | 用户的父级 BSUID | 新增。 |
出站消息状态 Webhook
消息发出后的 sent、delivered、read 状态 Webhook 变化如下：
字段 | 说明 | 变化说明 |
UserId | 用户 BSUID | 新增。始终包含用户 BSUID |
UserName | 用户名 | 新增。delivered/read 状态且用户有用户名时包含 |
To | 消息接收方手机号或 BSUID | 可能是手机号码也可能是 BSUID |
ParentUserId | 父级 BSUID | 新增 |
用户偏好设置 Webhook（user_preferences ）
字段 | 说明 | 变化说明 |
wa_id | 用户手机号 | 可能为空 |
user_id | 用户 BSUID | 新增。始终包含用户 BSUID |
username | 用户名 | 新增。用户启用用户名时包含 |
From | 消息发送方手机号或 BSUID | 修改，兼容了 BSUID |
FromUserId | 用户 BSUID | 新增。始终包含用户 BSUID |
FromUserName | 用户名 | 新增。用户启用用户名时包含 |
FromParentUserId | 父级 BSUID | 新增 |
WhatsApp 提供了一个设置优惠和公告，允许 WhatsApp 用户表明他们对您商家所发送营销消息的感兴趣程度，还允许用户完全停止或恢复接收您商家发送的营销消息。仅停止和恢复操作会触发用户偏好 Webhook。
群组相关 Webhook(群组成员变更）
字段 | 说明 | 变化说明 |
participantUserId | 成员的 BSUID | 新增 |
participantNumber | 成员的手机号码 | 可能为空 |
participantParentUserId | 成员父级 BSUID | 新增 |
participantUserName | 成员用户名 | 新增 |
群组相关 Webhook(群组消息回执）
字段 | 说明 | 变化说明 |
RecipientParticipantUserName | 群上行消成员的用户名 | 新增 |
RecipientParticipantUserId | 群上行消息成员的 BSUID | 新增 |
RecipientParticipantId | 群上行消息成员的 BSUID或手机号码 | 修改，可能是手机号码也可能是 BSUID |
RecipientParticipantParentUserId | 群上行消息成员的父级 BSUID | 新增 |
群组相关 Webhook(群组消息上行）
字段 | 说明 | 变化说明 |
FromUserId | 群上行消息成员的 BSUID | 新增 |
FromUserName | 群上行消息成员的用户名 | 新增 |
From | 群上行消息成员的 BSUID或手机号码 | 修改可能是手机号码也可能是 BSUID |
FromParentUserId | 群上行消息成员的父级 BSUID | 新增 |
通话相关 Webhook
用户发起通话：
字段 | 说明 | 变化说明 |
FromUserId | 用户的 BSUID | 新增 |
FromUserName | 用户的用户名 | 新增 |
From | 用户的手机号码或 BSUID | 修改，可能是手机号码也可能是 BSUID |
FromParentUserId | 用户的父级 BSUID | 新增 |
商家发起通话：
字段 | 说明 | 变化说明 |
UserId | 用户的 BSUID | 新增 |
UserName | 用户的用户名 | 新增 |
To | 用户手机号或 BSUID | 修改，可能是手机号码也可能是 BSUID |
ParentUserId | 用户的父级 BSUID | 新增 |
WhatsApp Business App 共存相关 Webhook
echos: 商家通过 Business APP 发消息给用户后回传给 Cloud API 的数据
字段 | 说明 | 变化说明 |
UserId | 用户的 BSUID | 新增 |
UserName | 用户的用户名 | 新增 |
To | 消息接收者 | 可能是手机号码也可能是 BSUID |
ParentUserId | 用户的 BSUID | 新增 |
history inbound：同步历史消息后用户上行消息数据
字段 | 说明 | 变化说明 |
From | 用户的手机号码或 BSUID | 修改，可能是手机号码也可能是 BSUID |
FromUserId | 用户的 BSUID | 新增 |
FromParentUserId | 用户的父级 BSUID | 新增 |
FromUserName | 用户的用户名 | 新增 |
history outbound：同步历史消息后商家下行消息数据
字段 | 说明 | 变化说明 |
To | 消息接收者 | 可能是手机号码也可能是 BSUID |
UserId | 用户的 BSUID | 新增 |
ParentUserId | 用户的父级 BSUID | 新增 |
UserName | 用户的用户名 | 新增 |
新增 Webhook 类型
businessUsernameUpdate（商家业务账号变更）
当您的商家业务账号状态发生变更时触发，状态值包括 approved（已审批）、reserved（已预留）、deleted（已删除）。
新增功能
联系人通讯录（Contact Book）
Meta 提供由其托管的联系人通讯录，无需您进行任何集成工作，但是此功能不提供页面查询。
功能开启后，每当您的商家号码与用户发生消息或通话交互，该用户的手机号和 BSUID 将自动存入通讯录。通讯录中的用户，其手机号将始终出现在后续的 Webhook 中，不受用户名功能影响。
通讯录按 BM 维度隔离。同一个 BM 下任意商家号码与用户的交互，都会将该用户存入通讯录，BM 内所有商家号码均可受益。但不同 BM 之间的通讯录数据不共享
仅记录功能上线后的新交互，历史交互不会被追溯录入
可在 Meta Business Suite 的业务设置中关闭该功能，关闭后已存数据将被删除
如需从通讯录中删除某位用户的记录，可通过 Chat App 消息服务提供的相应接口操作，删除后该用户的手机号将不再出现在 Webhook 中（除非重新满足 30 天交互条件）。
联系人通讯录的限制：
通讯录按 BM 维度隔离。如果您有多个 BM 加入了同一个 Parent BSUID 账户，各 BM 的通讯录数据是独立的，不会跨 BM 共享或同步。同一位用户的手机号和 BSUID 需要在每个 BM 下分别触发交互后才能各自录入
如果您使用了本地存储（Local Storage），当用户点击 REQUEST_CONTACT_INFO 按钮分享手机号时，Meta 会从用户的 vCard 中提取手机号并存入通讯录，存储位置为 Meta 数据中心。除手机号外，vCard 中的其他信息不会被保留
请求用户手机号按钮（REQUEST_CONTACT_INFO）
当您不知道用户手机号时，可以通过此按钮在对话中主动请求用户分享。该按钮可添加至 utility 或 marketing 类模板，也可作为独立的互动消息发送。
用户点击按钮后，其手机号将以联系人 Webhook 的形式推送给您。若您开启了联系人通讯录，该手机号还会自动存入通讯录。
商家业务账号（Business Username）
您可以为您的商家号码申请一个业务账号，方便用户通过精确搜索找到您的业务。业务账号与商家电话号码一一对应，同一个用户名不能同时绑定多个号码。
业务用户名格式要求：
仅支持英文字母（a-z）、数字（0-9）、句点（.）和下划线（_）
不支持非英文字符（如 ñ、é、ü）
长度为 3 至 35 个字符
必须包含至少一个英文字母
不能以句点开头或结尾，不能包含连续两个句点
不能以 www 开头，不能以域名后缀结尾（如 .com、.org 等）
您可以通过 Chat App 消息服务申请、查询或删除业务用户名。
商家账号名称显示规则
用户在聊天窗口中看到的商家名称，按以下优先级从高到低显示：
用户自己保存的联系人名称
已认证的商家显示名称或官方商业账户（OBA）名称
业务账号名称
商家手机号码
例如，若用户未将您的号码保存为联系人，且您的账户没有已认证的显示名称或通过审核的显示名称，则用户看到的将是您的业务用户名。若您也未设置业务用户名，则显示手机号码。
设置业务用户名不会隐藏您的手机号码。无论是否设置了业务用户名，您的手机号码始终会显示在您的商家资料中。
常见问题
为什么必须支持 BSUID？
用户名功能是可选的，您无法控制您的用户是否启用。一旦用户启用，其手机号将不再出现在 Webhook 中。如果您的系统无法处理缺少手机号的情况，将无法正常接收和处理这些用户的消息。BSUID 是在这种情况下唯一可靠的用户标识符。
如果我暂时没有完成对接，会发生什么？
对于启用了用户名的新用户，Webhook 仍会正常下发，但若您的系统无法处理缺少手机号的情况，可能导致消息处理失败。对于已有用户，若满足 30 天交互条件，手机号仍会包含在 Webhook 中，短期内影响有限。但随着用户名功能逐步普及，影响范围将持续扩大，建议尽早完成对接。
用户换手机号后，我如何知道是同一个用户？
用户更换手机号后，BSUID 会重新生成，同时会触发
user_id_updateWebhook，其中包含旧 BSUID 和新 BSUID 的对应关系。您可以通过这一 Webhook 在系统中完成用户身份的更新和关联。BSUID 可以跨我的多个商家号码使用吗？
可以。同一个 BM 下的所有商家号码，无论归属于哪个 WABA，面对同一位用户拿到的都是同一个 BSUID，任意商家号码均可使用该 BSUID 向用户发消息。但不同 BM 之间的 BSUID 是隔离的，不可混用。如需跨 BM 使用，需申请 Parent BSUID。
如果我仍然需要用户的手机号怎么办？
历史上通过手机号码主动发送消息给终端客户的流程不受 BSUID 影响，您仍然可以直接通过用户手机号发送消息。
除此之外，您可以通过以下方式获取或保持手机号的可用性：在 30 天内保持与用户的消息或通话交互；启用联系人通讯录，与用户互动后手机号会自动存入；或在对话中使用 REQUEST_CONTACT_INFO 按钮主动请求用户分享手机号。
商家号码业务账号和显示名称有什么区别？
显示名称不唯一，用户无法通过显示名称搜索到您的业务。业务账号名称是全局唯一的，用户可以通过精确搜索找到您。当两者同时存在时，显示名称优先展示。