← 所有文章
指南

WhatsApp BSUID 迁移 7 月 7 日启动 — 接收消息的团队必须检查的五件事 — UnifyPort

Meta 正在改变 WhatsApp API 中识别用户的方式。从 2026 年 7 月 7 日（第一批）起，每一条 Webhook 消息都会多出一个叫做 Business-Scoped User ID（BSUID）的新字段——而一旦用户启用了 WhatsApp 用户名，手机号可能直接从消息体中消失。

如果你的客服系统、CRM 对接或 AI Agent 管线正在接收 WhatsApp 消息，这次改动和你有关。具体影响多大，取决于消息在到达你后端之前走的是哪条路。

这篇文章就是一份清单：五个需要排查的环节、一张决策矩阵，以及大多数小团队真正想问的那个问题的明确答案——“7 月 7 号之前我到底要不要改代码？“

BSUID 到底是什么

每个 WhatsApp 用户都会获得一个新标识符：Business-Scoped User ID。格式是两位国家代码 + 一个点 + 最多 128 位字母数字，例如 SG.3K7mN9pQ2rT5vW8x。关键特性：同一个人在不同商家那里有不同的 BSUID。你系统里客户 Alice 的 BSUID，和另一家公司看到的 Alice 的 BSUID 完全不一样。

Meta 的推进时间表：

批次日期范围
第一批2026 年 7 月 7 日首批市场
第二批2026 年 7 月 20 日扩大范围
全球2026 年 9 月所有剩余市场

实际上从 2026 年 3 月 31 日起，BSUID 就已经以 user_id 字段的形式出现在 Webhook 中了。但真正的破坏性变更发生在第一批上线之后：一旦用户启用了 WhatsApp 用户名，wa_id 和 from 字段里的手机号可能不再出现。

排查清单：五个必须检查的环节

1. Webhook 消息体解析

变了什么： 每条消息的 Webhook 中新增了一个 user_id 字段。对于启用用户名的用户，原来放手机号的 wa_id 和 from 字段可能变成 BSUID——甚至直接为空。

查什么： 你的 Webhook 处理代码是否默认 from 一定是手机号？是否用正则匹配纯数字、把它当数据库主键、或者传给号码校验库？当 from 变成 SG.3K7mN9pQ2r... 而不是 6591234567 时，这些逻辑都会报错。

2. CRM 和客户匹配

变了什么： 如果你的 CRM 以手机号为主键存储客户记录，那启用了用户名的客户发来的消息里可能根本没有手机号。客户记录匹配不上。

查什么： 你的客户数据库能不能在手机号之外，同时存储和匹配 BSUID？Meta 提供了一个 Contact Book API，可以保留历史对话中手机号到 BSUID 的映射——但你必须在手机号从新 Webhook 中消失之前就调用它。

3. 对话历史和会话线程

变了什么： 如果你用手机号来串联会话记录（比如”显示 +6591234567 的所有消息”），同一个人的消息会开始以 BSUID 标识到达。除非你把旧的手机号记录和新的 BSUID 关联起来，否则对话历史会断成两段。

查什么： 你的消息存储是否用手机号做会话线程的主键？如果是，尽快做一次回填：在第一批上线之前，用 Contact Book 映射把已有的手机号记录和 BSUID 关联起来。

4. 模板消息和主动触达的寻址方式

变了什么： 发送模板消息（主动外发）时，最终你需要用 BSUID 而非手机号来寻址收件人——尤其是那些启用了用户名、手机号不再暴露的用户。

查什么： 如果你会主动发送消息（订单确认、物流通知、预约提醒），你的发送逻辑是否按手机号找收件人？你需要在每次收到入站消息时保存其中的 BSUID，留作后续外发使用。对于做东南亚跨境电商的团队来说，这一点尤其重要——你的客户散布在多个国家，手机号格式本身就容易出错，BSUID 反而让寻址更可靠，前提是你提前存好了它。

5. 数据存储和合规

变了什么： BSUID 是一种新的个人可识别信息。虽然它按商家隔离（不能用来跨公司关联同一用户），但在大多数隐私法律框架下仍属于 PII。

查什么： 你的数据留存策略是否覆盖了新增的标识符类型？如果你有 GDPR 或东南亚 PDPA 的删除流程要遍历用户的所有已存标识符，BSUID 也需要纳入其中。

你走的是哪条路？

并不是所有团队都需要处理以上五个环节。这取决于 WhatsApp 消息是怎么到达你后端的。

接入方式需要处理的环节迁移工作量
Cloud API（直连）全部五项高——你直接解析 Meta 的原始 Webhook，每个字段变动都直接影响你的代码
BSP（Wati、360dialog 等）第 2、3、4、5 项中——BSP 可能会屏蔽 Webhook 格式变化，但 CRM 匹配和发送逻辑仍需改动
非官方接口无零——往下看

非官方接口为什么不受影响

如果你的 WhatsApp 消息是通过 UnifyPort 的非官方接口到达的，BSUID 迁移和你的管线完全无关。原因很简单：UnifyPort 不走 Meta 的 Cloud API。非官方路径直接连接 WhatsApp——和一台手机上运行 WhatsApp 的方式一样——所以你的 Webhook 收到的消息，从一开始就不是 Cloud API 的 payload 格式。

你的 Webhook 收到的仍然是同样的 message.received 事件：

{
  "event": "message.received",
  "account_id": "acct_3qPmRz",
  "provider": "whatsapp",
  "from": "user_88c1ae",
  "text": "你好，订单 #2241 发货了吗？",
  "timestamp": 1751875200,
  "message_id": "wa_msg_f4e29a"
}

from 字段是 UnifyPort 自有的归一化用户标识——不是手机号，也不是 BSUID。它从来就不是手机号，所以 Meta 改变标识体系时，你这边不需要做任何迁移。CRM 匹配、会话串联、Webhook 解析，全部照常工作。

Webhook 端点上的 HMAC-SHA256 签名验证也不受影响——签名密钥和签名格式都是 UnifyPort 的，不是 Meta 的。

这周该做什么

如果你用的是 Cloud API 或 BSP：从第 1 项（Webhook 解析）开始。记录一批收到的 Webhook，检查 user_id 字段是否已经出现——它从 3 月 31 日起就在逐步灰度了。如果已经有了，说明你的消息体已经在变了。在 7 月 7 日之前把第 2 到第 5 项逐一处理完。

如果你走的是非官方接口：什么都不用改。BSUID 迁移是 Cloud API 层面的事，你的消息不经过 Cloud API。继续做你的产品就好。