WhatsApp 用户名与业务范围用户 ID(BSUID):Cloud API Webhook 的变化
WhatsApp 用户名让用户可以显示名称,而不是电话号码,因此自 2026 年 4 月初起,Cloud API 消息的 Webhook 还会在 user_id 和 from_user_id 中携带业务范围用户 ID(BSUID),例如 US.13491208655302741918。对于设置了用户名、在过去 30 天内未与该号码有任何消息或通话往来、且不在通讯录中的用户,wa_id 和 from 会被省略。
easyCoexistence 通过 Coexistence 将 WhatsApp Business 应用号码连接到 Cloud API,并按 Meta 发送的原样将 messages 和 smb_message_echoes Webhook 路由至你的端点,包括 BSUID 字段;get_api_credentials 则为你的代码提供以 recipient 回复所需的一切。
BSUID 何时开始出现在 Cloud API Webhook 中,早于用户名向 WhatsApp 用户推出的时间。
API 何时开始接受发送至 BSUID 的消息,此时在 recipient 中设置,而不是 to。
回溯期按每个业务电话号码计算:在此期间与该用户有过任何消息或通话,即可在 Webhook 中保留其号码。
BSUID 的两位国家代码与句点之后,大部分为字母数字字符。
Messages API 错误:此消息类型不支持业务范围用户 ID(BSUID)收件人。
系统消息类型,用于在未报告电话号码时报告 BSUID 变更,旧 BSUID 位于 previous_user_id 中。
WhatsApp 用户名和 BSUID 是什么?
用户名是 WhatsApp 用户可以设置的可选唯一名称,显示在应用中,代替其电话号码;Meta 在 2026 年逐步推出用户名。BSUID 是 Meta 新增的后台标识符,使企业仍能区分用户:由系统自动生成,对每个业务组合与用户的组合都唯一,格式为用户的 ISO 3166 两位国家代码、句点,再加最多 128 个字母数字字符。Meta 要求合作伙伴和直接集成的企业支持 BSUID,因为没有任何企业能控制其用户是否采用用户名。
哪些字段携带新标识符?
在 messages、status、system 和 user_preferences Webhook 中,新属性与原先承载电话号码的字段并列。父级字段仅出现在 Meta 已为其启用父 BSUID 的业务组合中,这些父 BSUID 可在所有已注册组合之间通用:
电话号码何时被省略?
当用户设置了用户名,且 Meta 的三个条件均不成立时。若业务电话号码在过去 30 天内给该用户的号码发过消息或拨过电话、在此期间从该号码收到过消息或来电,或该用户在组合的通讯录中,号码就会保留在 Webhook 中。30 天回溯期按每个业务电话号码计算,因此同一组合中的第二个号码可能只会收到该用户的 BSUID。未设置用户名的用户仍会同时携带其电话号码和 BSUID。
现在收到的消息是什么样的?
与以前相似,BSUID 位于电话号码旁边或取代它。在 Meta 的示例中,对于设置了用户名且号码无法共享的用户,contacts 包含 profile.name、profile.username 和 user_id,消息中在原来 from 的位置出现 from_user_id:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "102290129340398",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
"contacts": [{
"profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
"user_id": "US.13491208655302741918"
}],
"messages": [{
"from_user_id": "US.13491208655302741918",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
"timestamp": "1749416383",
"type": "text",
"text": { "body": "Does it come in another color?" }
}]
}
}]
}]
}状态 Webhook 有哪些变化?
已发送、已送达和已读状态新增一个 contacts 数组,包含用户名称、user_id、号码可共享时的 wa_id,以及已送达和已读状态中的 username。在状态中,recipient_user_id 携带 BSUID;当你发送至 BSUID 且号码无法共享时,recipient_id 被省略。失败状态没有 contacts 数组,并且消息发送至电话号码时会省略 recipient_user_id,因此应通过消息 ID 将失败与消息对应起来。
应如何存储和匹配用户?
首先按 BSUID,电话号码在到达时作为第二个键。将完整的 BSUID 作为字符串存储,包括国家代码和句点,因为 Meta 会拒绝更改其中任何部分的请求;如果你的组合已注册,还应存储父 BSUID。在 wa_id 仍然到达时,将其与现有记录关联,并将 BSUID 保留在旁边,因为之后设置用户名的用户可能不带号码返回。Meta 的常见问题解答对 CRM 及与其对接的工具也要求相同的关联方式。
用户更换电话号码时会怎样?
其 BSUID 会重新生成,变更以系统消息的形式出现在 messages 字段中,因为 Meta 没有可订阅的 user_id_update 字段。当新号码可与你共享时,system.type 为 user_changed_number;当只能报告 BSUID 变更时,为 user_changed_user_id。system.user_id 保存新 BSUID,system.previous_user_id 保存旧 BSUID,记录正是借此得以延续。两种类型都需要处理。
如何回复只知道 BSUID 的用户?
发送至 /<BUSINESS_PHONE_NUMBER_ID>/messages,将 recipient 设为 BSUID,并省略 to;两者都存在时以 to 为准,回复会发送至电话号码。响应中的 contacts 条目随后会携带 input 和 user_id,而不是 wa_id。除一键、零点击和复制代码认证模板外,任何消息类型均可使用,这些模板需要电话号码;且只有同一业务组合中的号码才能触达 BSUID。错误 131062 表示该消息类型不接受 BSUID 收件人。
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"recipient": "US.13491208655302741918",
"type": "text",
"text": { "body": "Yes, it also comes in blue." }
}如何向用户索取电话号码?
使用 REQUEST_CONTACT_INFO 按钮,将其添加到实用或营销模板中,或作为 request_contact_info 类型的交互式消息发送。用户点击后会在对话中分享其号码,并收到 origin 为 contact_request、号码位于 phones[].wa_id 中的 contacts Webhook;手动分享的联系人则以 origin 为 other 和 vCard 的形式到达。Meta 于 2026 年 7 月初推出该按钮,其标签不可自定义。
什么是通讯录?
由 Meta 为每个业务组合托管的存储,无需集成工作:一旦业务电话号码与用户的电话号码发生消息、通话或来电往来,该号码和 BSUID 即被记录,并用于在之后的 Webhook 中以电话号码补全(无论用户是否设置用户名)。只有推出后的互动才会计入。可在 Meta Business Suite 的 Business settings、Business info 中关闭,这会删除其中保存的内容;GET 或 DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book 配合 bsuid 可检查或删除单条记录。
Coexistence 集成应作哪些修改?
需要修改其对三种只有 Coexistence 号码才会收到的 Webhook 的处理,这些 Webhook 本身也有所变化。在 history 中,每个会话新增一个 context 对象,包含 wa_id、user_id 和 username,其消息新增 from_user_id。在 smb_message_echoes 中,新增一个 contacts 数组,message_echoes[].to 可省略,而 to_user_id 携带 BSUID;在 WhatsApp Business 应用中进行的编辑和撤回以相同方式到达。在 smb_app_state_sync 中,联系人的 phone_number 可省略,旁边附有 user_id 和 username。匹配回显和导入的聊天时,除号码外还应匹配 user_id。
在用户采用用户名之前如何测试?
使用 App Dashboard 中 Meta 的测试工具:依次进入 Use cases、Connect with customers through WhatsApp、Customize、Configuration,messages Webhook 旁的 Test 链接会向你的端点发送示例。它涵盖收到的消息和状态,共四种场景:
- 未设置用户名的用户:包含 BSUID 和电话号码字段,无用户名。
- 设置了用户名且号码不可用的用户:包含用户名和 BSUID,无电话号码字段。
- 设置了用户名且号码可用的用户:包含用户名、BSUID 和电话号码。
- 已注册父 BSUID 的组合:父 BSUID 位于该组合自身 BSUID 旁边。
easyCoexistence 如何处理 BSUID?
按 Meta 发送的原样转发。通过 set_webhook_destination 路由至你的端点的号码,会直接从 Meta 接收 messages 和 smb_message_echoes Webhook,包括 user_id、from_user_id、to_user_id 和 username;若开启了自动化或转发,easyCoexistence 会原样转发 Meta 发送的值。若要回复 BSUID,你的代码需使用 get_api_credentials,它返回号码的电话号码 ID、其发送端点,以及可用时你自己的访问令牌;send_message 和 send_template 工具则接受国际格式的电话号码(仅数字)。
常见错误
- 仅以 wa_id 作为联系人键。设置了用户名、且 30 天内未与该号码有过联系的用户,只会带着 user_id 和 from_user_id 到达,要求 wa_id 的处理程序会漏掉这条消息。
- 截去 BSUID 的国家前缀。Meta 要求完整的值,包括国家代码和句点,任何部分被改动的请求都会失败。
- 等待 user_id_update 字段。Meta 没有此字段:BSUID 变更以 system 消息的形式在 messages 中到达,类型为 user_changed_number 或 user_changed_user_id。
- 仅以 to 匹配 Coexistence 回显。在 smb_message_echoes 中,to 字段可以省略,因此若不同时匹配 to_user_id,在应用中输入的回复会被漏掉。
每个连接全天候 24/7 监控。每个连接每月起价 US$ 9,连接越多越便宜,最低降至 US$ 0.75,首 3 天免费。
常见问题
没有用户名的用户也会获得 BSUID 吗?
会。无论用户是否设置用户名,Meta 都会在 messages Webhook 中设置 user_id,因此大多数用户会同时携带其电话号码和 BSUID。
Coexistence 号码可以拥有业务用户名吗?
可以。自 2026 年 6 月 29 日起,企业可在 Meta Business Suite、WhatsApp Manager、WhatsApp Business 应用或 Username API 中采用或更改用户名;这不会隐藏业务号码,business_username_updates 会报告每次状态变更。
BSUID 能否跨业务组合使用?
不能。BSUID 属于某一组合和用户,另一组合中的号码无法向其发送消息。Meta 注册的受管理企业会获得父 BSUID,其国家代码之后带有 ENT,可在其已注册的组合之间通用。
easyCoexistence 每个 WhatsApp 号码收费多少?
每个连接每月起价 US$ 9,具体取决于连接数量,最低降至 US$ 0.75,首 3 天免费。Meta 自身的消息费用仍从您的 WhatsApp Business 账户的付款方式中扣除。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间