# 业务范围用户 ID

**业务范围用户 ID**（BSUID）是 Meta 为 WhatsApp 用户分配的标识符，作用域为一个业务组合。无论联系人是否使用 WhatsApp 用户名，入站消息都会携带该标识符，它可以在你没有联系人电话号码的情况下定位该联系人。

Bird 将其作为消息的 `from` 和 `to` 上的 `bsuid` 呈现，接受它作为发送的 `to`，并按它筛选消息列表。Meta 的[业务范围用户 ID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids)参考文档是上线本身以及其他 Meta 界面如何使用该标识符的权威来源。

## 为什么联系人到达时没有电话号码

WhatsApp 正在推出用户名功能。采用用户名的用户在应用中显示用户名而非电话号码，Meta 随后会从企业收到的载荷中隐去该号码。BSUID 是始终存在的身份标识，因此入站消息可以只携带 BSUID 而完全没有 `phone_number`。

当你与联系人已有关系时，Meta 仍会包含电话号码：当该特定商业电话号码在过去 30 天内向其发送过消息或拨打过电话、或收到过其消息或来电时，或者当对方在你的 Meta 通讯录中时。30 天条件按商业电话号码逐一评估，因此，曾向你的某个号码发送消息的联系人，在另一个号码上仍可能没有电话号码。

来自 WhatsApp 用户的消息还会携带其公开的个人资料，位于 `from` 上的 `username` 和 `display_name` 中。当联系人未采用用户名或消息不携带个人资料时，两者都不存在，且都不能用于寻址消息。

## BSUID 的格式

```json
{
  "from": {
    "bsuid": "US.13491208655302741918",
    "username": "alexr",
    "display_name": "Alex Rivera"
  }
}
```

一个 ISO 3166 alpha-2 国家代码，一个句点，然后最多 128 个字母数字字符。**父级 BSUID** 允许托管企业注册后在一组业务组合中使用同一标识符，它在国家代码之后插入 `ENT`：`US.ENT.11815799212886844830`。Bird 接受这两种形式作为收件人。

三个特性决定了你如何存储和使用 BSUID：

- **原样传递完整值，不要修改。** Meta 会拒绝被修改的 BSUID，因此其中没有任何部分是可选的：国家代码、句点和标识符的每个字符必须一起传递。Bird 在接受发送之前会验证格式，国家代码必须是大写的、真实的 ISO 3166 alpha-2 代码；小写或未知前缀会被拒绝而非自动纠正。128 字符上限适用于国家代码之后的标识符部分，以及父级 BSUID 上 `ENT.` 段之后的部分。
- **作用域为业务组合。** 同一业务组合中的任何商业电话号码都可以向该 BSUID 发送消息；不同业务组合中的号码则不行，发送会失败。
- **非永久性。** Meta 记录了联系人更换电话号码时其 BSUID 会被重新生成，因此它标识的是会话对象，而非可作为你自己持久客户键使用的标识。

## 一次对话的典型流程

一个你此前未交流过的联系人通过 BSUID 联系到你，获取其号码的交互分三步完成：

1. **联系人向你发消息。** 入站消息携带 `from.bsuid`，`from.phone_number` 可能缺失。该消息会打开[客服窗口](/docs/knowledge-base/whatsapp/customer-service-window)，你可以在接下来的 24 小时内自由回复。
2. **您请求号码。** 发送[联系信息请求](/docs/guides/whatsapp/message-types/interactive/contact-info-requests)，这是一个让联系人分享电话号码的按钮。同样的请求也可以通过模板的 `request_contact_info` 按钮发送，适用于对话窗口已关闭的联系人。
3. **联系人点击按钮。** 披露的号码以入站[联系人名片](/docs/guides/whatsapp/receiving-whatsapp/contact-cards)的形式到达，其中 `origin` 设为 `contact_request`，号码位于 `phone_numbers` 中。披露的联系人名片可以描述另一个人或另一个号码。将该披露内容与发送者的 WhatsApp 身份分开存储；在后续消息中使用实际提供的身份，而不是仅凭名片覆盖客户记录。

联系人可以拒绝。关闭分享面板不会产生任何消息或 webhook，因此需要号码的流程必须自行设置超时，而不是等待拒绝事件到达，并且必须在联系人始终不分享号码的情况下仍能正常运行。

## 向 BSUID 发送消息

`to` 在所有接受电话号码的位置同样接受 BSUID：

```json
{
  "to": "US.13491208655302741918",
  "from": "+13124495648",
  "text": { "body": "Your order shipped." }
}
```

与按电话号码寻址的发送相比，有四点不同：

- **`from` 必须位于 BSUID 所属的业务组合中。** 这与 Meta 施加的业务组合要求相同，不匹配时在 WhatsApp 阶段而非接受阶段失败。
- **一次性验证码模板需要电话号码。** Bird 管理的、属于 `authentication` 类别的模板，或携带一次性验证码按钮的模板，会在接受阶段被拒绝，返回 `422` [`E15014`](/docs/api/errors/E15014) `WhatsAppRecipientNotSupportedForTemplate`。你的工作区自行创建的模板不会在接受阶段被检查：Meta 要求一键、免点击和复制验证码的身份验证模板必须使用电话号码，因此此类发送会被接受但随后失败。
- **既非电话号码也非格式正确的 BSUID 的值会在接受阶段被拒绝**，返回 `422` [`E15001`](/docs/api/errors/E15001) `WhatsAppInvalidRecipient`。
- **价格取决于 BSUID 的国家前缀。** 电话号码提供消息计价所依据的国家，对于 BSUID 发送则由两字母前缀提供。

发送的其他一切保持不变：[客服窗口](/docs/guides/whatsapp/message-types#the-customer-service-window)仍然控制自由格式内容的发送，`202` 仍然表示已接受而非已送达。

**使用联系人联系你时所用的身份来寻址。** Bird 会为入站消息携带的每个身份记录一个打开的窗口，发送时根据寻址身份查找对应窗口。仅通过 BSUID 联系你的联系人不会留下基于电话号码的窗口，因此向你从其他渠道获得的电话号码发送自由格式消息，可能会被拒绝并返回 `422` [`E15044`](/docs/api/errors/E15044) `WhatsAppServiceWindowClosed`，即使 Meta 仍认为该对话处于打开状态。回复其消息的 `from` 可以避免这种不匹配。

## 按 BSUID 读取和筛选

每次读取都会携带消息所包含的所有身份标识：

- **在消息上**，`from` 和 `to` 各自携带 `phone_number`、`bsuid`，或两者兼有。入站消息在 `from` 上标注联系人；出站消息在 `to` 上标注联系人。
- **在 webhook 上**，相同的地址信息位于事件载荷中。参阅[WhatsApp 事件](/docs/guides/whatsapp/events#the-event-envelope)了解信封结构。
- **在消息列表上**，`to` 和 `from` 各自接受 BSUID 和电话号码，每个匹配消息的一端。`bsuid` 筛选器在两个方向上匹配联系人。旧的 `phone_number` 筛选器已弃用：`to` 和 `from` 取代了它，并匹配两种身份标识。

将两种身份标识都存储在你自己的联系人记录中，并以你自己的标识符而非 Meta 的任一标识符作为记录的键。联系人可能初始只有 BSUID，在分享号码后获得电话号码，又在更换号码时获得新的 BSUID。

## 后续步骤

- [接收联系人名片](/docs/guides/whatsapp/receiving-whatsapp/contact-cards)：分享的号码到达的路径
- [WhatsApp 联系信息请求](/docs/guides/whatsapp/message-types/interactive/contact-info-requests)：请求号码的按钮
- [发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)：请求信封、`202` 模型和安全重试
- [Meta 业务范围用户 ID 参考文档](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids)：上线计划、父级 BSUID 以及 Meta 的其他相关界面

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)