WhatsApp Embedded Signup v4 的 Coexistence 迁移：2026 年 10 月 15 日前检查清单
如果你的集成通过 Coexistence 为现有 WhatsApp Business app 号码完成 onboarding，请在 2026 年 10 月 15 日前将 Embedded Signup v2 迁移到 v4。Meta 要求 v4 使用新的 Facebook Login for Business configuration；在配置中选择 Embedded Signup 和所需产品后，流程才会切换到 v4。不要把它当作一次界面更新：权限、callback、Coexistence 选项、webhook 和历史记录同步都需要重新测试。
关键结论
- Meta 表示 Embedded Signup v2 将于 2026 年 10 月 15 日弃用，并建议在此之前迁移到 v4，避免 onboarding 中断。
- V4 通过新的 Facebook Login for Business configuration 配置；所选产品决定流程包含哪些资产和权限。
- WhatsApp Business app 用户 onboarding，也就是通常所说的 Coexistence，在 v4 中仍受支持。
- “对话框能打开”并不代表迁移成功：还要验证 Coexistence 选项、finish callback、资产 ID、token exchange、webhook 投递和 24 小时历史记录同步窗口。
- 如果团队不需要官方 Business app 与 Cloud API 共用同一号码，应先判断是否真的需要 Coexistence，再决定是否投入迁移。
WhatsApp Embedded Signup v4 迁移会改变什么
Meta 的 v4 文档说明，v4 于 2025 年 10 月 8 日发布，并将取代 v2 成为当前的 Embedded Signup 路径。最重要的实现变化，是流程定义的位置发生了改变。
在 v2 中，关键流程选项位于集成传入的 extras 对象内。在 v4 中，Meta 要求开发者新建 Facebook Login for Business configuration，选择 Embedded Signup 作为 login variation，再选择流程需要包含的产品。所选产品会自动确定 v4，并预选对应的必要资产与权限。
因此，迁移需要检查以下范围：
| 迁移范围 | v4 中需要验证什么 | 为什么重要 |
|---|---|---|
| Login configuration | 新建的 Facebook Login for Business configuration 使用 Embedded Signup variation | 复用旧 v2 configuration 并不是文档要求的 v4 路径 |
| Products | 明确选择 Cloud API，以及确实需要的其他 messaging products | 产品选择决定 onboarding 体验和所需资产 |
| Permissions | 所有自动选中的权限都已获得 Advanced Access | 即使对话框看起来正确，缺少权限访问仍会导致流程失败 |
| Coexistence | 流程提供连接现有 WhatsApp Business app 账号和号码的选项 | 默认 Cloud API 流程不能证明 Business app onboarding 已在迁移后保留 |
| Session result | finish event、资产 ID 和可交换 token code 能回传到启动窗口 | 后端仍需这些结果完成 onboarding |
| Webhooks | 能接收历史记录、状态同步和 message echo payload | Coexistence 依赖注册后的同步，而不只是完成 signup |
V4 还整合了资产选择、企业信息和权限，并可包含 Click to WhatsApp Ads、Conversions API 等产品。对于只迁移 Coexistence 的项目，这些都是可选项。只选择集成真正支持的产品；对话框覆盖越广，需要处理的权限和测试工作就越多。
Embedded Signup v4 仍然支持 WhatsApp Coexistence 吗？
支持。Meta 更新后的 Business app onboarding 指南明确说明，WhatsApp Business app 用户 onboarding 仍受支持。该功能在支持与合作伙伴文档中通常称为 “Coexistence”。
这些官方页面需要结合阅读。通用 versions 指南为 v4 展示了一个有意留空的 extras 对象，而专门的 Coexistence 指南仍记录 whatsapp_business_app_onboarding feature selection 和 session-info version。不要假设从现有 launcher 中移除所有 Coexistence 专用设置后，流程仍会保持不变。应新建 v4 configuration，遵循当前 Business app onboarding 指南，并使用测试账号验证实际页面和 callback。
预期的用户路径很明确：企业选择连接现有 WhatsApp Business app 账号，输入当前号码，在 Business app 内确认连接，然后完成 Embedded Signup。完成后，Business app 可以继续处理一对一消息，同时 Cloud API 消息和受支持的历史记录保持同步。
如果团队还在判断是否需要这套双端流程，请先阅读现有的 WhatsApp Coexistence 决策指南。只有当用户确实需要 Business app 与官方 Cloud API 集成共用同一号码时，这次迁移才值得投入。
WhatsApp Coexistence 迁移检查清单
1. 盘点所有 v2 入口
找出生产环境和 staging 中所有能启动 Embedded Signup 的按钮、SDK call、configuration ID、callback handler 和 feature flag。记录哪些客户群体使用 Coexistence，哪些使用默认 Cloud API 流程。共用 launcher 可能会掩盖 Coexistence 回归问题，直到真实 Business app 用户进入流程才暴露。
2. 新建 v4 configuration
在 App Dashboard → Facebook Login for Business → Configurations 中新建 configuration，选择 Embedded Signup，选择所需产品，再把新的 configuration ID 写入集成。Meta 表示，选择产品后即可将体验设为 v4。
同时检查自动选中的资产和权限。对于 Cloud API，v4 表格列出的内容包括 WhatsApp Business accounts，以及 whatsapp_business_management 和 whatsapp_business_messaging；这两项权限都需要 Advanced Access。
3. 重新启用并测试 Coexistence 路径
专用流程应以 Meta 当前的 Business app onboarding 指南为准。测试时，确认旧的 WABA-only 选择页面已替换为连接现有 WhatsApp Business account 的选项。如果该选项缺失，应立即停止发布；当前测试的是另一种 onboarding 意图。
还要确认文档列出的前置条件：客户使用 WhatsApp Business app 2.24.17 或更高版本；你的组织是 Solution Partner 或 Tech Provider；callback 能处理所需 webhooks；并且 session logging 已启用。
4. 验证 finish callback 与 onboarding 状态
Coexistence 指南记录的 finish event 是 FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING。捕获返回的 WABA ID、资产 ID 和可交换 token code，再完成常规客户 onboarding 步骤；由于该号码已经注册，应跳过 phone-number registration。
不要把 session payload 中记录的 version: 3 与 Embedded Signup configuration version 混为一谈。它们是两个独立 contract，应在测试中分别断言，不能只根据一个数字字段决定路由。
Onboarding 完成后，查询 Meta 为该检查列出的 business phone number fields。预期状态是 is_on_biz_app: true，同时 platform_type: "CLOUD_API"。
5. 验证三条同步路径
发布前，为 app 订阅 Coexistence 额外要求的 WABA webhook fields：
history：接收客户选择共享的历史消息；smb_app_state_sync：接收当前联系人和联系人变更；smb_message_echoes：接收从 WhatsApp Business app 发出的新消息。
Meta 要求合作伙伴在 onboarding 后 24 小时内发起联系人与消息历史同步。每项同步只能发起一次；如需重试，客户必须先 offboard，再重新完成整个流程。保存返回的 request_id，快速接收大型 webhook batch，并采用异步方式处理。
6. 使用明确的回滚边界发布
在 Meta 仍同时允许 v2 和 v4 时，先让两个 configuration 面向受控 cohort 并行运行。按 configuration ID 分别跟踪 completion rate、callback receipt、token exchange、is_on_biz_app、同步完成情况和 webhook errors。如果 v4 未通过任一 gate，应回滚入口，而不是回退已经完成的客户状态。
距离 10 月截止日期还有时间，没有必要等到最后再一次性切换。先完成技术迁移，再查看独立的 WhatsApp service message 计量方案，避免 onboarding 与计费变化挤进同一个 release。
UnifyPort 在哪里发挥作用
UnifyPort 不会迁移 Meta configuration、授予 Cloud API 权限、同步官方 Business app 历史记录，也不会保留 Meta 的 Coexistence 状态。如果产品需要这些官方能力，v4 才是正确路径，且集成所有者必须完成迁移。
UnifyPort 解决的是另一类需求：连接普通 WhatsApp 账号，并通过标准 message.received webhook event 接收受支持的入站消息。其 WhatsApp authorization 支持 QR code 和 phone-number pairing；签名 webhook 投递使用 X-Device-Timestamp、X-Device-Signature 和 endpoint 的 signing_secret。
当真实目标是建立入站队列，而不是让 Business app 与 Cloud API 共用同一号码时，这条替代路径才有意义。在投入迁移前，可先通过 WhatsApp 入站路径对比指南比较三种方案，避免为并不需要的官方功能投入工程资源。
限制与取舍
对于需要将客户 onboarding 到官方 Cloud API 产品的 Solution Partner 和 Tech Provider，Embedded Signup v4 是正确答案。在此对比中，也只有这条路径能保留 Meta 支持的 Coexistence 行为、历史记录共享流程、官方资产模型与 Cloud API 产品权限。
非官方接口无法提供这些平台权限，也无法让企业获得 Meta 产品资格、替代 Meta 的 customer-service window，或把普通账号连接变成 Cloud API WABA。它的作用更窄：无需客户采用官方 Coexistence stack，也能提供标准入站接口。
V4 迁移也不会消除 Coexistence 当前的运行限制。Meta 目前列出的限制包括：Business app 与 Cloud API 共用号码时固定为每秒 20 条消息；API 发送的消息按 Cloud API 单独计费；不支持 group-history synchronization；companion device 也有特定限制。验收测试时应再次对照官方指南确认这些约束。
FAQ
Embedded Signup v2 何时弃用？
Meta 表示 Embedded Signup v2 将于 2026 年 10 月 15 日弃用。集成所有者应在此之前迁移到 v4，避免 onboarding 中断。
每位 WhatsApp Business app 用户都需要迁移吗？
不需要。迁移责任属于拥有 Embedded Signup v2 集成的合作伙伴或服务商。只使用独立 WhatsApp Business app 的企业并不维护 Embedded Signup configuration。
V4 会移除 WhatsApp Coexistence 吗？
不会。Meta 表示，WhatsApp Business app 用户 onboarding 在 v4 中继续受支持。迁移必须保留并测试专用 Coexistence 选项，不能假设默认 Cloud API 流程与它等价。
是否需要新的 Facebook Login for Business configuration？
需要。Meta 的 v4 指南要求开发者新建 configuration，选择 Embedded Signup 作为 login variation，并选择要包含的产品。
WhatsApp Coexistence 迁移测试至少要证明什么？
至少包括：连接现有 Business app 的选项正常出现；finish callback 和资产信息能够返回；token exchange 完成；is_on_biz_app 为 true 且 platform_type 为 CLOUD_API；history、smb_app_state_sync 和 smb_message_echoes 三条 webhook 路径都能工作。
下一步
如果你负责 Meta Embedded Signup 集成，请按照官方 v4 迁移指南新建 configuration，并在 staging 中执行以上检查清单。如果只需要普通账号的入站消息，可先通过 UnifyPort WhatsApp authorization 指南评估这条独立路径，再决定是否建设 Coexistence。
来源
官方 Meta 来源，核验日期 2026-07-16：