登录开始免费试用
Meta Tech Provider

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 回复所需的一切。

April 2026

BSUID 何时开始出现在 Cloud API Webhook 中,早于用户名向 WhatsApp 用户推出的时间。

July 2026

API 何时开始接受发送至 BSUID 的消息,此时在 recipient 中设置,而不是 to。

30 days

回溯期按每个业务电话号码计算:在此期间与该用户有过任何消息或通话,即可在 Webhook 中保留其号码。

128

BSUID 的两位国家代码与句点之后,大部分为字母数字字符。

131062

Messages API 错误:此消息类型不支持业务范围用户 ID(BSUID)收件人。

user_changed_user_id

系统消息类型,用于在未报告电话号码时报告 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 可在所有已注册组合之间通用:

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

电话号码何时被省略?

当用户设置了用户名,且 Meta 的三个条件均不成立时。若业务电话号码在过去 30 天内给该用户的号码发过消息或拨过电话、在此期间从该号码收到过消息或来电,或该用户在组合的通讯录中,号码就会保留在 Webhook 中。30 天回溯期按每个业务电话号码计算,因此同一组合中的第二个号码可能只会收到该用户的 BSUID。未设置用户名的用户仍会同时携带其电话号码和 BSUID。

现在收到的消息是什么样的?

与以前相似,BSUID 位于电话号码旁边或取代它。在 Meta 的示例中,对于设置了用户名且号码无法共享的用户,contacts 包含 profile.name、profile.username 和 user_id,消息中在原来 from 的位置出现 from_user_id:

messages webhook: a text from a user known only by BSUID
{
  "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 收件人。

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a 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,在应用中输入的回复会被漏掉。
使用 EasyCoexistence 完成这些操作

每个连接全天候 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,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间