從雲端 API 移轉至內部部署 API

我們即將停用內部部署 API。請參閱我們的內部部署 API 停用文件以取得詳細資訊，並瞭解如何轉移到我們的新一代雲端 API。

本文件說明如何將商家電話號碼從雲端 API 移轉至內部部署 API。若要從內部部署 API 移轉至雲端 API，請參閱從內部部署 API 移轉至雲端 API。

請注意，將商家電話號碼從一個 API 移轉至另一個 API，不同於將商家電話號碼從一個 WhatsApp Business 帳號（WABA）移轉至另一個帳號。

移轉不會影響：

商家電話號碼的顯示名稱、驗證狀態或品質評分
商家電話號碼使用的範本或範本狀態
所屬的 WABA、其官方商業帳號狀態或傳訊限制

然而，為了支援移轉，您必須瞭解任何 API 差異，並採取適當的措施來解決這些差異後，再執行本文件所述的移轉步驟。

最佳作法

確認您的應用程式能夠處理所有 API 差異後，建議您先移轉容量低的商家電話號碼，並驗證您打算透過內部部署 API 提供的所有功能運作正常。驗證一切正常後，再移轉其他號碼。

此外，也建議您在內部部署 API 部署的流量較低時執行移轉。

API 差異

在開始移轉程序之前，請確認您的應用程式能夠處理這些差異。

Webhooks

雲端 API 和 Business Management API Webhooks 承載結構與內部部署 API 承載結構不同。建議您建立一個新的 Webhook 端點，用於專門處理內部部署 API Webhooks。

請參閱以下文件，協助您瞭解承載差異：

配置：WhatsApp 的 Webhooks
雲端 API Webhook 承載：Webhooks 通知承載參考資料
Business Management API Webhook 承載：Webhooks 設定

完成移轉至內部部署 API 後，將不再傳送商家電話號碼的雲端 API Webhooks，並將開始傳送內部部署 API Webhooks。

影音素材

使用內部部署 API 傳送訊息時，無法使用上傳至雲端 API 之任何影音素材的影音素材編號，所以您必須使用內部部署 API 重新上傳影音素材以產生新的影音素材編號，或者如果影音素材託管在公開伺服器上，可使用影音素材網址。請參閱傳送媒體訊息。

錯誤代碼

雲端 API 和 Business Management API 錯誤代碼不同於內部部署 API 錯誤代碼。請參閱下列文件：

按住即可聊天訊息

內部部署是藉由將 messages.type 設為 voice 來識別 Webhooks 中的按住即可聊天（PTT）訊息，但雲端 API 是藉由將 messages.audio.voice 設為 true 來識別 PTT 訊息。

停機時間

在您執行註冊步驟（步驟 3）後，停機時間即開始，而且應該只會持續幾秒鐘。在此期間，WhatsApp 用戶傳送至該號碼的訊息會被默默捨棄。

強烈建議您將移轉作業安排在該號碼活動較少的時段進行，以儘量減少停機時間的影響。

步驟 1：整合內部部署 API

由於您要將商家電話號碼移轉至內部部署 API，因此請確認您的應用程式能夠成功使用內部部署 API 用戶端，而且與商家電話號碼相關聯的 WhatsApp Business 帳號已正確配置 Webhooks。

步驟 2：準備移轉

建議您在進行移轉時，停止傳送訊息。

WhatsApp Business API 內部部署用戶端必須符合特定網路需求，才能連線至 WhatsApp 伺服器。若要確認您是否已準備就緒，請查看網路設定與偵錯。

步驟 3：註冊 API 用戶端

在內部部署 API 用戶端上註冊商家電話號碼。若要執行此操作，請呼叫 /account 端點：

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

依據所收到的回應，您可以評估註冊程序是否已完成，或需要其他步驟才能完成。如果成功，您會收到下列其中一個 HTTP 狀態代碼。請視您收到的回應參閱相關說明：

201 Created - 帳號已存在。您已註冊過，因此不需執行任何步驟。
202 Accepted - 帳號不存在。根據您在申請中選擇的方法，查看您的簡訊或語音通話，取得註冊代碼。此回應將包括傳回的裝載，其中包含從 cert 參數解碼的 vname，以便您確認正在設定的顯示名稱正確無誤。如果正確，請繼續進行完成帳號註冊部分，以完成註冊。

您可以在這裡查看此端點可用的所有欄位。

註冊完成後，將會由內部部署 API 用戶端接收訊息。

步驟 4：設定分片

註冊用戶端後，您可以依需要設定分片。

步驟 5：開始傳送訊息

您已準備好傳送訊息給顧客。請參閱傳送訊息指南，取得相關指示。

WhatsApp Business 平台 | 雲端 API | 企業管理 API