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 完成後的同步，而不只是完成 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 入口
找出 production 與 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：