关于WhatsApp用户名与BSUID的一切须知（2026年6月起实施）

WhatsApp为何引入用户名？

哪些内容将变更？

认证消息（验证码/OTP）必须通过手机号码发送

还有一个重要限制：认证消息仍需使用手机号码。
仅凭BSUID无法发送OTP或复制验证码的认证消息。如果该流程对您的业务至关重要，您需要明确的方式请求并存储用户的手机号码。

在某些情况下，WhatsApp仍可能与企业共享手机号码，例如：

• 用户主动选择分享
• 用户与企业之间已存在对话记录
• 企业保存在用户的WhatsApp联系人中

因此企业现在需要同时支持两种情况：

• 仅通过BSUID识别的客户
• 通过电话号码和BSUID识别的客户

这就是为什么这不仅是一个产品更新，而是一个系统更新。

什么是BSUID（业务范围用户ID）

BSUID的工作原理

• 它由WhatsApp自动生成
• 它出现在webhook负载中（作为user_id）
• 即使缺少电话号码，它也能正常工作
• 它与特定的业务组合相关联

因此，从系统的角度来看，这成为了您的 新用户在接入会话中的标识符。

BSUID格式（外观示例）

BSUID遵循固定结构：

• 以用户的ISO 3166 alpha-2 两位国家代码开头
• 后接一个 点号（.）
• 然后是 唯一字母数字字符串（最长128字符）

Example:
US.13491208655302741918

在API中使用时， 必须完整使用该值且保持原样。
任何修改或截断都会导致请求失败。

关键规则须知

• BSUID具有 业务组合-用户对的唯一性 （业务组合曾被称为Business Managers）
• 当用户 更改电话号码时会重新生成 （这将触发系统状态消息webhook）
• 其作用域 限定于单个业务组合 （不能跨不同组合使用）
• 即使 用户未启用用户名，仍会出现在webhook中

BSUID的限制

BSUID功能强大，但不能完全替代电话号码。

• 您 无法发送认证消息（OTP、验证码） 使用 BSUID
• 这些流程仍然需要一个电话号码
• 因此，如果你的用例依赖于 OTP，你必须从用户那里收集号码

哪些内容不会改变

消息发送和接收机制

• 消息模板的使用保持不变。
• 对各种消息类型（文本、图片、视频、文档等）的支持保持不变。
• 消息发送 API 接口的结构基本保持一致，只是标识符参数需要兼容 BSUID。
• 已经通过现有对话获取用户电话号码信息的企业不会丢失这些信息，并且可以继续使用它们来向联系人发送消息。

对话计费规则

• 24小时对话窗口机制保持不变。
• 对话计费方式保持不变。
• 无论客户使用电话号码还是用户名，计费逻辑保持一致。

还有哪些内容？

• 电话号码仍然是 WhatsApp 工作方式的一部分。
• 如果用户尚未采用用户名，企业将同时收到他们的电话号码和业务范围的标识符。

这意味着企业应将其主要精力放在客户识别和数据关联上；核心消息通信能力和业务逻辑将继续保持不变

接下来，我们来看看企业在适应这一新的识别系统时将面临的挑战。

企业面临的挑战

挑战一：无法直接获取新用户的电话号码

当新用户使用用户名联系时，您只会收到一个 BSUID。

默认情况下您无法获取其电话号码。

您仍可使用BSUID进行回复并继续对话。但如果业务需要电话号码（例如OTP或验证），现在您必须 在聊天中明确索取 并等待用户同意。

挑战二：将BSUID与现有客户数据映射

当前大多数CRM系统都以电话号码为核心构建。

• 客户档案
• 聊天记录
• 订单
• 用户分群

所有数据都以电话号码为主键进行关联。

现在引入BSUID后，您需要决定：

• 是添加BSUID作为新字段？
• 还是在电话号码和BSUID之间建立单独的映射层？

这不仅是个技术决策，更会影响 数据一致性、查询逻辑和系统复杂度。

挑战三：当客户在不同标识符间切换时保持对话连续性

对用户而言一切如常，仍是同一次对话。

但对您的系统来说，可能出现断层。

示例：

• 首次互动 → 通过BSUID识别
• 后续 → 用户分享电话号码

若系统未能正确关联两者，同一用户可能被视作 两个不同的客户

后果：

• 重复记录
• 聊天记录断裂
• 糟糕的客户体验

挑战4：验证与OTP流程处理

BSUID不能用于认证消息

因此若您的流程依赖：

• OTP验证
• 登录验证
• 账户关联

您必须首先 收集用户的电话号码

这意味着现有流程可能需要重新设计以：

• 明确请求授权
• 获取号码
• 正确存储并映射

接下来我们看看若忽视这些挑战会导致哪些实际故障

故障表现（若忽视此问题）

以下是可能出现的故障：

• 您可能会错过对话
  通过用户名进入的新用户无法在您的系统中正确映射。
  

• 消息流程中断
  服务消息和CTWA（点击到WhatsApp广告）流程可能无法按预期触发。
  

• 聊天记录断开连接
  同一用户可能显示为多个身份。
  

• CRM数据不可靠
  客户资料可能无法正确存储或映射数据。
  

• 重复用户增加
  一个用户 = 多个记录，跨越电话号码和BSUID。
  

• 自动化停止工作
  与电话号码绑定的工作流程无法触发。
  

• 端到端工作流程中断
  从潜在客户捕捉到后续跟进，整个流程开始崩溃。
  

• 销售团队失去可视性
  潜在客户无法被正确识别或跟踪。
  

这就是为什么影响比看起来更大。
这不仅是一个数据问题，它会影响您的整个客户旅程。

接下来，我们来看看如何解决这个问题并正确处理客户识别。

客户识别解决方案

场景一：新客户首次通过用户名发起联系（仅BSUID）

当新客户使用用户名发起对话时，您的系统可能仅接收到 BSUID。

这种情况下，BSUID将成为该客户档案的起点。

处理方法如下：

• 您的数据模型应支持 同一客户拥有多个标识符 。
• 您的CRM系统需能够 使用BSUID创建客户档案
• 您的系统应支持 通过BSUID进行查询和识别
• 若业务需要电话号码（例如需提供配送地址或发送验证码时），应在对话适当时机主动询问
• 用户提供号码后，存储该号码并 将其关联至基于BSUID的同一档案

场景二：已掌握电话号码的客户

若您的业务已存有客户电话号码，可继续使用该号码

此部分无需变更

即使用户启用了用户名功能，您仍可使用已知号码发送消息。但若该用户后续通过用户名发起对话，您的系统需能将新获取的 BSUID 与现有基于电话号码的记录关联

处理方法如下：

• 您的数据模型仍需支持 单个客户对应多个标识符。
• 当出现BSUID时，将其关联至现有客户记录
• 您的系统应支持通过 电话号码或BSUID。
• 优先使用 电话号码进行外发消息，特别是在验证或认证流程中

时间表与行动计划

WhatsApp正在分阶段推出此功能，这给了您准备时间，但前提是您要尽早开始。

时间表

• 2026年3月31日→ BSUID将开始出现在Webhook中。
• 2026年5月→ BSUID测试可用（您可以开始使用BSUID发送）。
• 2026年6月→ 测试国家的用户可开始采用用户名。用户名功能开始推出。
• 2026年剩余时间→ 全球用户可开始采用用户名。

企业应采取的措施

1. 准备阶段（当前）

• 学习并理解BSUID机制及技术细节。
• 识别电话号码在工作流程中的使用场景。
• 定义如何处理电话号码与BSUID的关系。
• 评估修改现有系统所需的范围和工作量。
• 制定数据库调整和API兼容性计划。
• 开始技术研究和解决方案设计。
• 协调内部团队（产品、工程、市场）并规划业务用户名策略。

2. 实施阶段（功能发布前）

• 更新CRM和数据库以支持BSUID。
• 完成API集成层的兼容性改造。
• 实施电话号码授权请求流程。
• 确保验证码消息通过电话号码发送。
• 完成测试环境的验证。
• 制定分阶段发布（灰度发布）计划。

3. 测试

• 使用实际场景进行端到端测试。
• 验证：
  • 基于BSUID的用户创建
  • 电话号码收集流程
  • 标识符映射
  • 消息和自动化流程

4. 上线阶段（功能发布后）

• 分阶段推出（不要一次性切换所有内容）。
• 监控系统运行健康状况，例如档案创建准确性、OTP成功率和工作流性能。
• 处理用户反馈并处理异常情况。
• 优化客户识别逻辑。
• 持续提高数据关联的准确性。
• 监控电话号码授权率，并优化请求的时机和消息内容。
• 认领并设置您的业务用户名。

上线前检查清单

正式上线前请确保：

• BSUID已集成到您的所有系统中
• 无需手机号码仍可收发消息
• 所有工作流都经过两种标识符测试
• 聊天机器人和客户旅程能在需要时请求手机号码
• 现有工作流已审核更新以避免中断

优先级划分

• 高优先级 → CRM及数据库结构调整、API兼容性修改、验证码发送逻辑调整（影响核心功能）
• 中优先级 → 客服系统适配、营销系统更新（影响业务效率）
• 低优先级 → 数据报表优化、历史数据清理（可逐步完善）

这不是最后一刻才需要解决的问题
越早适配，过渡越顺利

更多资源获取渠道

实施时请勿依赖假设，应参考官方文档

以下是关键入门资源：

• BSUID指南
  https://docs.ycloud.com/reference/bsuid
  → 涵盖BSUID工作原理、格式及API中的用法
  
  

• Webhook更新（BSUID字段）
  https://docs.ycloud.com/reference/webhook-updates-bsuid
  → 了解BSUID在webhook负载中的呈现方式及集成变更
  
  

• Meta开发者文档（BSUID）
  https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
  → 关于BSUID在WhatsApp API中引入和使用的官方参考
  
  

这些应作为您更新系统时的首要参考资料。

总结！

术语表

以下是您将在webhook和API中看到的关键术语的简单解释：

• contacts (新数组)
  涉及消息的用户列表。可将其视为webhook中的"客户信息模块"。
  

• profile
  contacts中用户的基本信息。
  

• username
  新属性。用户的WhatsApp用户名（如果已设置）。
  如果用户未设置用户名，该字段不会出现。
  
  

• wa_id
  新属性。用户的电话号码。
  若电话号码可用，将在此处显示。
  如果用户使用用户名且未共享号码，该字段可能缺失。
  
  
  

• user_id (BSUID)
  新属性。未来最重要的字段。
  这就是 BSUID，一个代表您业务中用户的唯一ID。
  该ID始终存在，当电话号码不可用时应用作识别用户的依据。
  
  
  

• parent_user_id
  可跨多个业务组合使用的高级BSUID（如已启用）。
  除非管理多个业务组合，大多数企业不会使用此字段。
  
  

简单理解方式：

• wa_id → 电话号码（可能不可用）
• user_id → BSUID（始终可用，新的默认标识）
• username → 用户公开显示的名称