WhatsApp Embedded Signup v4 Coexistence 遷移：2026 年 10 月 15 日前檢查清單
如果你嘅 integration 透過 Coexistence，將現有 WhatsApp Business App 號碼接入 onboarding 流程，就要喺 2026 年 10 月 15 日前由 Embedded Signup v2 遷移到 v4。Meta 要求 v4 使用全新 Facebook Login for Business configuration；揀選 Embedded Signup 同所需產品後，流程就會切換到 v4。呢次係 onboarding 遷移，唔只係介面更新：permissions、callbacks、Coexistence 選項、webhooks 同訊息記錄同步都要重新測試。
重點
- Meta 表示 Embedded Signup v2 將於 2026 年 10 月 15 日停用，並建議喺限期前轉到 v4，以免 onboarding 中斷。
- V4 要透過新 Facebook Login for Business configuration 設定；所選產品會決定流程包含嘅 assets 同 permissions。
- WhatsApp Business App 用戶 onboarding，即通常所講嘅 Coexistence，喺 v4 仍然支援。
- 遷移成功唔可以只證明「對話框開到」：仲要驗證 Coexistence 選項、finish callback、asset IDs、token exchange、webhook delivery 同 24 小時訊息記錄同步時限。
- 如果團隊唔需要官方 Business App 同 Cloud API 共用同一個號碼，就應該喺投入遷移之前，先決定係咪真係需要 Coexistence。
WhatsApp Embedded Signup v4 遷移有咩改變
Meta 嘅 v4 文件表示，v4 於 2025 年 10 月 8 日推出，而家已經取代 v2，成為目前 Embedded Signup 使用嘅版本。最重要嘅實作改變，係流程改由邊度定義。
喺 v2，重要流程選項放喺 integration 傳入嘅 extras object。到 v4，Meta 要開發者建立新 Facebook Login for Business configuration，將 login variation 揀做 Embedded Signup，再選擇流程要包含嘅產品。所選產品會自動決定使用 v4，並預先選取所需 assets 同 permissions。
遷移時要檢查以下範圍：
| 遷移範圍 | v4 要驗證嘅項目 | 點解重要 |
|---|---|---|
| Login configuration | 全新 Facebook Login for Business configuration 使用 Embedded Signup variation | 重用舊 v2 configuration 唔係文件指定嘅 v4 做法 |
| Products | 有意識咁揀選 Cloud API 同其他所需 messaging products | 所選產品會決定 onboarding 體驗同所需 assets |
| Permissions | 每項自動選取嘅 permission 都有 Advanced Access | 對話框睇落正常，app 仍可能因為無 permission access 而失敗 |
| Coexistence | 流程提供連接現有 WhatsApp Business App account 同號碼嘅選項 | 預設 Cloud API 流程唔足以證明 Business App onboarding 已經保留 |
| Session result | Finish event、asset IDs 同可交換嘅 token code 傳返啟動流程嘅 window | Backend 仍然需要呢啲結果先可以完成 onboarding |
| Webhooks | 可以接收 history、state-sync 同 message-echo payloads | Coexistence 依賴 signup 後嘅同步，唔係完成 signup 就足夠 |
V4 亦整合咗 asset selection、business information 同 permissions，並可以加入 Click to WhatsApp Ads、Conversions API 等產品。對只需要遷移 Coexistence 嘅團隊，呢啲都係選配。只揀 integration 真正支援嘅產品；對話框範圍愈大，permissions 同測試工作亦愈多。
Embedded Signup v4 仲支唔支援 WhatsApp Coexistence？
支援。Meta 更新後嘅 Business App onboarding 指南清楚表示，WhatsApp Business App 用戶 onboarding 仍然獲得支援。支援同 partner 文件一般將呢項功能稱為「Coexistence」。
相關官方頁面要一齊睇。通用 versions 指南為 v4 顯示刻意留空嘅 extras object，但專門嘅 Coexistence 指南仍然記載 whatsapp_business_app_onboarding feature selection 同 session-info version。唔好假設由現有 launcher 移除所有 Coexistence-specific settings，流程就一定會保持不變。應該建立新 v4 configuration，跟從目前 Business App onboarding 說明，再用測試 account 驗證實際畫面同 callback。
預期用戶流程好明確：商戶選擇連接現有 WhatsApp Business App account，輸入目前號碼，喺 Business App 內確認連接，再完成 Embedded Signup。之後，Business App 可以繼續處理一對一訊息，而 Cloud API 訊息同獲支援嘅歷史記錄就會同步。
如果團隊仍然未決定係咪需要呢個雙介面流程，可以先睇現有嘅 WhatsApp Coexistence 決策指南。只有當團隊真係需要 Business App 同官方 Cloud API integration 共用同一號碼，呢次遷移先值得投入。
Coexistence 遷移檢查清單
1. 盤點所有 v2 入口
搵出每個 production 同 staging button、SDK call、configuration ID、callback handler 同可以啟動 Embedded Signup 嘅 feature flag。記錄邊類客戶會使用 Coexistence，邊類會使用預設 Cloud API 流程。共用 launcher 可能會將 Coexistence regression 隱藏到真正 Business App 用戶遇到先發現。
2. 建立新 v4 configuration
喺 App Dashboard → Facebook Login for Business → Configurations 建立 configuration，揀選 Embedded Signup 同所需產品，再將新 configuration ID 寫入 integration。Meta 表示，揀選產品後，體驗就會設定為 v4。
檢查自動選取嘅 assets 同 permissions。Cloud API 嘅 v4 表格列出 WhatsApp Business accounts，以及 whatsapp_business_management 同 whatsapp_business_messaging；兩項 permission 都需要 Advanced Access。
3. 重新啟用並測試 Coexistence 流程
專門流程要跟從 Meta 最新 Business App onboarding 指示。測試時，確認舊有只揀 WABA 嘅畫面，已經由「連接現有 WhatsApp Business account」選項取代。如果睇唔到呢個選項，就要停止 rollout；你而家測試緊嘅係另一種 onboarding intent。
同時確認文件列明嘅 prerequisites：客戶使用 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、asset IDs 同可交換 token code，再完成一般 customer-onboarding 步驟；由於號碼已經註冊，所以要略過 phone-number registration。
唔好將 session payload 文件入面嘅 version: 3，同 Embedded Signup configuration version 混為一談。兩者係獨立 contract，測試亦應該分別 assert，唔好只靠一個數值分流。
完成 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：接收現有同之後變更嘅 contacts；smb_message_echoes：接收由 WhatsApp Business App 新發出嘅訊息。
Meta 畀 partner 喺 onboarding 後 24 小時內啟動 contacts 同 message-history synchronization。每種 initiation 只可以執行一次；如果要再做，客戶必須先 offboard，再重新完成整個流程。保存回傳嘅 request_id，快速接收大型 webhook batches，並以 asynchronous 方式處理。
6. Rollout 要有真正 rollback 界線
Meta 仲容許 v2 同 v4 並行期間，先畀受控 cohort 同時使用兩套 configuration。按 configuration ID 分開追蹤完成率、callback receipt、token exchange、is_on_biz_app、同步完成情況同 webhook errors。如果 v4 未能通過 gate，rollback 嘅應該係入口，而唔係已經完成嘅客戶狀態。
距離 10 月限期已經唔算遠，無必要等到最後一刻先一次過 cutover。先完成技術遷移，再睇獨立嘅 WhatsApp service-message 計量方案，避免將 onboarding 同定價變更塞入同一次 release。
UnifyPort 適用喺邊度
UnifyPort 唔會遷移 Meta configurations、授予 Cloud API permissions、同步官方 Business App 訊息記錄，亦唔會保留 Meta Coexistence 狀態。如果產品需要呢啲官方能力，v4 先係正確路徑，而 integration owner 必須完成遷移。
UnifyPort 處理嘅係另一種需要：連接普通 WhatsApp account，並將獲支援嘅 inbound messages 以標準 message.received webhook event 送到你嘅系統。WhatsApp authorization 支援 QR code 同 phone-number pairing；signed webhook delivery 會使用 X-Device-Timestamp、X-Device-Signature 同 endpoint 嘅 signing_secret。
如果真正目標係建立 inbound queue，而唔係畀 Business App 同 Cloud API 共用一個號碼，呢個替代方案先有關。投入工程資源做遷移之前，可以先喺 WhatsApp inbound paths 指南比較三種做法，確認你係咪真係需要當中嘅官方功能。
限制同取捨
對於要將客戶 onboard 到官方 Cloud API 產品嘅 Solution Partners 同 Tech Providers，Embedded Signup v4 係正確答案。喺今次比較入面，只有呢條路徑可以保留 Meta 支援嘅 Coexistence 行為、history-sharing 流程、官方 asset model 同 Cloud API product permissions。
非官方接口無法提供呢啲權限，亦唔可以令商戶符合 Meta 產品資格、取代 Meta 客戶服務時段，或者將普通 account connection 變成 Cloud API WABA。佢較窄嘅作用，係提供標準 inbound interface，而唔要求客戶使用整套官方 Coexistence stack。
V4 遷移亦唔會移除 Coexistence 文件列出嘅操作限制。Meta 目前為同時使用 Business App 同 Cloud API 嘅號碼列出固定每秒 20 條訊息 throughput、API 發送訊息另按 Cloud API 定價、唔支援 group-history synchronization，以及特定 companion-device 限制。Acceptance testing 期間，要按官方指南重新核對呢啲約束。
FAQ
Embedded Signup v2 幾時停用？
Meta 表示 Embedded Signup v2 將於 2026 年 10 月 15 日停用。Integration owner 應該喺限期前轉到 v4，避免 onboarding 中斷。
每個 WhatsApp Business App 用戶都要遷移嗎？
唔需要。遷移責任屬於擁有 Embedded Signup v2 integration 嘅 partner 或 provider。只使用獨立 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，將 login variation 揀做 Embedded Signup，再選擇要包含嘅產品。
遷移測試要證明啲咩？
最低限度要證明：連接現有 Business App 嘅選項有顯示；finish callback 同 assets 有回傳；token exchange 完成；is_on_biz_app 係 true，而且 platform_type 設為 CLOUD_API；history、smb_app_state_sync 同 smb_message_echoes 三條 webhook 路徑都正常。
下一步
如果你負責 Meta Embedded Signup integration，就按官方 v4 遷移指南建立新 configuration，再喺 staging 執行以上清單。如果你只需要普通 account inbound messaging，可以先睇 UnifyPort WhatsApp authorization 指南，評估呢條獨立路徑，再決定係咪建立 Coexistence。
Sources
以下 Meta 官方來源於 2026-07-16 核對：