# WhatsApp用户名与BSUID：OTP、CRM和Webhook有哪些变化

> WhatsApp用户名意味着企业可能无法再看到客户的电话号码。Meta的解决方案是业务范围内的用户ID（BSUID）。本文将介绍其定义、哪些场景仍需电话号码，以及如何迁移Webhook、CRM和OTP流程。

- 规范网址: https://www.broadnet.me/zh/blog/whatsapp-usernames-bsuid-developer-guide
- 语言: zh
- 最后更新: 2026-09-26
- 发布方: BroadNet (https://www.broadnet.me)

- 发布日期: 2026-09-26
- 作者: BroadNet Engineering

业务范围内的用户ID（BSUID）是Meta现在放入每个WhatsApp Webhook中的标识符，以便企业在无需获知用户电话号码的情况下与其进行消息服务。引入该标识符是因为WhatsApp正在推出用户名功能：一旦用户开启了用户名，近期未与其联系的企业可能无法再收到其号码。这份来自BroadNet工程团队的指南将解释其格式、时间表、哪些场景仍需电话号码，以及如何迁移Webhook、CRM记录和OTP流程。

## 核心要点

- 自2026年4月初以来，无论用户是否使用用户名，WhatsApp的Webhook中都已出现了BSUID。
- 一个BSUID的格式类似于US.13491208655302741918：包含一个ISO 3166 alpha-2国家代码、一个句点，随后是最多128个字母数字字符。
- 该ID对于每个业务组合与用户的配对都是唯一的，如果用户更改了电话号码，该ID将重新生成。
- 自2026年7月起，您可以向BSUID发送消息，但一键式、零点击和复制验证码身份验证模板除外，这些模板仍需使用电话号码。
- Meta表示，合作伙伴和直接集成的企业必须支持BSUID，以避免失去处理来自用户名用户的消息的能力。
- 保留已验证的E.164电话号码，将其作为OTP、短信回退和欺诈检查的身份锚点。将BSUID视为WhatsApp通道密钥。

## 什么是业务范围内的用户ID？

Meta将BSUID定义为“当您不知道用户的电话号码时，可用于向WhatsApp用户发送消息的唯一用户标识符”([Meta，业务范围用户ID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/))。其格式为用户的国家/地区（采用ISO 3166 alpha-2代码）、一个点，以及最多128个字母数字字符，例如US.13491208655302741918。

系统设计涉及三个属性：

- 范围。一个BSUID对于一个业务组合和一个用户是唯一的。同一个人在与每个不同的业务组合沟通时都会拥有不同的BSUID，因此您无法使用它在不相关的业务组合之间匹配客户。
- 稳定性。当用户更改电话号码时，该ID会重新生成。发生这种情况时，Meta会发送一个类型为user_changed_user_id的系统消息Webhook，以及一个单独的user_id_update Webhook。
- 父级BSUID。拥有多个业务组合的管理型企业可以要求其Meta联系人加入父级BSUID，其中包含ENT（例如US.ENT.11815799212886844830），并适用于所有已加入的业务组合。

## 为什么WhatsApp要引入用户名？

为了保护隐私。Meta在2026年6月29日宣布，用户可以预订用户名并在“今年晚些时候”使用；一旦用户启用了用户名，其首次发送消息给个人或企业时，对方将不再看到其电话号码（[关于Meta](https://about.fb.com/news/2026/06/its-time-to-reserve-your-whatsapp-username/)）。Meta的开发者文档指出，用户名将在2026年逐步推出。

企业也可以拥有用户名。从2026年6月29日起，企业可以通过WhatsApp Manager、Meta Business Suite或Username API认领WhatsApp为其预留的用户名，获批的用户名将在功能上线时生效。企业用户名不会隐藏企业的电话号码。

## 时间线是怎样的？

| 日期 | 已发生或将发生的情况 | 开发者应采取的操作 |
|---|---|---|
| 2026年4月初 | BSUID开始出现在消息Webhook（user_id）中 | 在每个入站事件中，将BSUID与电话号码一同存储 |
| 2026年6月29日 | 面向用户和企业开放用户名预留 | 预留您的企业用户名；为无号码用户做好规划 |
| 2026年7月 | API支持向BSUID发送消息 | 在您的发送路径中添加接收者参数 |
| 2026年期间（逐步推出） | 用户名将向用户推出 | 预计收到的入站Webhook将包含BSUID且不包含电话号码 |

## 您会丢失客户的电话号码吗？

有时会。BSUID会出现在所有消息Webhook中。根据Meta的说法，只有在满足以下至少一个条件时，才会包含电话号码（wa_id以及入站消息中的from字段）：

- 在Webhook触发前的30天内，您曾向该用户的电话号码发送过消息或拨打过电话；
- 在上述30天内，您曾收到过来自该用户电话号码的消息或电话；或者
- 该用户已存在于您的联系人列表中。

30天的回溯期是按每个业务电话号码进行评估的，因此在您的销售线路中已知的客户，在您的支持线路中可能并不知晓。通讯录是Meta托管的功能，用于在首次交互后存储电话号码和BSUID，因此即使在用户采用了用户名之后，后续的Webhook仍可以持续携带该号码。该功能默认开启，您可以在Meta Business Suite的“业务设置 > 业务信息”中将其关闭。除非您有特殊理由，否则请保持开启状态。

## 还有哪些场景需要电话号码？

Meta的规定很明确：BSUID“可用于发送除一键式、零键式和复制验证码身份验证模板以外的任何类型的消息，这些模板需要用户的电话号码”。在WhatsApp之外，任何在移动网络上运行的服务也都需要电话号码。

| 任务 | 是否仅支持BSUID？ | 所需条件 |
|---|---|---|
| 自由回复、媒体文件、交互式消息 | 是 | 接收者参数中的BSUID |
| 营销和实用类模板 | 是 | 接收者参数中的BSUID |
| 一键、零点击及复制验证码认证模板（OTP） | 否 | 用户的电话号码 |
| 当WhatsApp失败时，自动回退至短信或RCS | 否 | E.164电话号码 |
| HLR查询、SIM交换检查、号码验证 | 否 | E.164电话号码 |
| 将客户与另一业务组合中的同一人进行匹配 | 否 | 您自己的客户ID或电话号码 |

## Webhook在变更前后有什么区别？

在BSUID之前，消息Webhook中的联系人区块（contacts block）在wa_id中携带电话号码，大多数集成方案将其作为客户键。Meta提供的全新联系人对象示例增加了用户名、BSUID以及在已启用时包含父级BSUID；只有当号码可以共享时，才会出现wa_id：

```
"contacts": [
  {
    "profile": {
      "name": "<USER_DISPLAY_NAME>",
      "username": "<USERNAME>"
    },
    "wa_id": "<USER_PHONE_NUMBER>",
    "user_id": "<BSUID>",
    "parent_user_id": "<PARENT_BSUID>"
  }
]
```

入站消息同样携带from_user_id（如果已启用，还包括from_parent_user_id），状态Webhook携带recipient_user_id，Meta指出这始终被设置为用户的BSUID。如需发送，请将BSUID放入新的接收者参数中。您可以设置to参数（电话号码）、接收者参数（BSUID）或两者同时设置；当两者同时存在时，电话号码具有优先权：

```
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "<BSUID>",
  "type": "text",
  "text": {
    "body": "<BODY_TEXT>"
  }
}
```

发送响应随后会在其联系人数组中包含user_id，且wa_id变为可选。如果您的解析器假设wa_id始终存在，那么在遇到第一个用户名用户时将会失败。您可以将真实的有效载荷粘贴到我们的[webhook有效载荷检查器](https://www.broadnet.me/tools/webhook-payload-inspector)中，以检查您的集成实际接收到了哪些字段。

## 对于OTP，哪些功能会失效？

带有“一键式”、“零点击”或“复制验证码”按钮的身份验证模板无法发送给BSUID。如果用户名用户通过WhatsApp联系您，而您没有他们的电话号码，则无法向其发送此类WhatsApp OTP。这对验证流程会产生两个后果：

- 在注册时以E.164格式收集并验证电话号码，并将其存储为账户的验证地址。不要依赖WhatsApp Webhook稍后向您提供该号码。请参阅[什么是E.164](https://www.broadnet.me/answers/what-is-e164)。
- 保留一个直接基于号码运行的通道。短信OTP、语音OTP和静默网络检查均基于电话号码运行，这也是为什么具备自动回退功能的多渠道设计在这一变更后仍能保持不变。我们的[多渠道OTP指南](https://www.broadnet.me/blog/multichannel-otp-verification-api-2026)和[BroadNet OTP产品](https://www.broadnet.me/products/otp)涵盖了这一模式。

## CRM和客户去重会遇到哪些问题？

大多数CRM将WhatsApp联系人与电话号码进行关联，因为过去短信、语音和WhatsApp都共用该号码。在用户名之后，新的入站联系人可能仅携带一个BSUID。如果您为此创建一个新的CRM记录，将会导致客户数据逐渐重复。以下四条规则可确保数据清洁：

1. 将BSUID建模为渠道身份，而非客户ID。一名客户可以拥有多个BSUID（每个业务组合一个），并在号码变更后拥有一个新的BSUID。
2. 维护一张包含BSUID、业务组合、已知电话号码、首次出现时间和最后出现时间的映射表，并在每次收到包括user_id_update在内的Webhook时进行更新。
3. 基于证据进行合并，而非凭空猜测：例如经过验证的电话号码、登录信息，或客户在聊天中提供的订单参考号。
4. 切勿将wa_id的缺失视为新客户。这仅意味着在该事件中无法共享该号码。

## 如何进行迁移？分步检查清单

1. 更新Webhook解析器以读取user_id、from_user_id、recipient_user_id和username，并将wa_id和from视为可选字段。
2. 在您存储WhatsApp联系人的任何地方，添加一个BSUID列（如果您是托管业务，请同时添加父级BSUID）。
3. 回填：针对2026年4月初以来的每一个入站事件，将BSUID与您已有的电话号码进行关联。
4. 通过将新的BSUID重新关联至客户，来处理user_changed_user_id系统消息和user_id_update Webhook。
5. 在您的发送路径中添加接收者参数，并在没有电话号码时改用该参数发送。
6. 将OTP路由至电话号码，切勿路由至BSUID，并保持短信或语音作为备选通道。
7. 通过WhatsApp Manager、Meta Business Suite或用户名API预留您的业务用户名。
8. 在用户名功能推送至您的客户之前，请先使用已启用用户名的账户进行测试。

如果BroadNet是您的WhatsApp提供商，在更改生产代码之前，请申请测试权限并确认BSUID字段在您账户的Webhook中是如何显示的。我们的[开发者中心](https://www.broadnet.me/developers)和[WhatsApp Business API页面](https://www.broadnet.me/products/whatsapp-business-api)提供了详细信息，而[全渠道路由](https://www.broadnet.me/products/omnichannel)可处理身份验证流程目前所依赖的短信自动回退。

## 常见问题

### 什么是WhatsApp BSUID？

一种业务范围内的用户ID：这是Meta为每个业务组合中的每个WhatsApp用户分配的标识符，因此企业可以在不知道用户电话号码的情况下向其发送消息。它在Webhook中显示为user_id。

### BSUID是什么样的？

一个ISO 3166 alpha-2国家代码、一个句点，然后是最多128个字母数字字符，例如US.13491208655302741918。托管业务的父级BSUID包括ENT，例如US.ENT.11815799212886844830。

### 当客户采用用户名时，我会丢失客户的电话号码吗？

仅在某些Webhook中会发生这种情况。如果您在过去30天内与该号码交换过消息或通话，或者该用户在您的联系人列表中，则号码仍会被包含在内。否则，wa_id将被省略，您只会收到BSUID。

### 我可以向BSUID发送消息吗？

是的，自2026年7月起，可以通过使用发送API的接收者参数来实现。除了需要用户手机号的一键式、零点击和复制验证码身份验证模板外，所有消息类型均可使用。

### 我可以向BSUID发送身份验证（OTP）模板吗？

不可以。一键式、零点击和复制验证码身份验证模板需要手机号码。请为每个账户保留一个已验证的手机号码，并使用短信或语音OTP作为备选方案。

### BSUID可以在不同的业务组合之间通用吗？

不可以。一个BSUID仅属于唯一的业务组合和用户对。受管业务可以向Meta咨询父级BSUID，父级BSUID可以在共同注册的业务组合之间通用。

### BSUID会发生变化吗？

是的。当用户更改手机号码时，BSUID会重新生成，Meta会通过user_changed_user_id系统消息和user_id_update webhook发出信号。

### 如何预留我的企业用户名？

自2026年6月29日起，可通过WhatsApp管理器、Meta商业套件或用户名API进行操作。一旦用户名功能上线，经批准的用户名即会生效，且该功能不会隐藏您的企业电话号码。

## 来源

- Meta开发者文档，[业务范围用户ID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/)（格式、时间线、Webhook字段、通讯录、发送参数、身份验证模板例外情况），访问日期：2026年9月26日。
- 关于Meta，[是时候预留您的WhatsApp用户名了](https://about.fb.com/news/2026/06/its-time-to-reserve-your-whatsapp-username/)，2026年6月29日，访问日期：2026年9月26日。