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

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

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

若要從雲端 API 移轉至內部部署 API，請參閱從雲端 API 移轉至內部部署 API。

運作方式

移轉程序包括產生商家電話號碼的相關中繼資料，然後使用該資料來註冊號碼，以用於雲端 API。這樣會從內部部署 API 註銷號碼，因為一個號碼一次只能註冊用於一個 API。

移轉不會影響：

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

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

必備條件

Meta 應用程式

您必須要有一個 Meta 商業應用程式，能夠將雲端 API 和 Business Management API 用於已加入的顧客資料，並且能夠接收雲端 API 和 Business Management API Webhooks。該應用程式也必須與經過驗證的 Meta 商業帳號相關聯或由該帳號認領。

如果您沒有 Meta 商業應用程式，或是您有 Meta 商業應用程式但尚未配置 WhatsApp 產品，請完成雲端 API 開始使用指南中的步驟。完成這些步驟後，會產生測試雲端 API 和 Business Management API 需要的所有資產。

應用程式審查

您的 Meta 應用程式必須進行應用程式審查，並獲准取得 whatsapp_business_messaging 和 whatsapp_business_management 權限（即具備進階存取權限）。

最佳作法

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

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

API 差異

以下是雲端 API 不支援或處理方式不同的內部部署 API 功能。在開始移轉程序之前，請確認您的應用程式能夠處理這些差異。

Webhooks

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

請參閱下列文件，以幫助您瞭解承載差異，以及如何使用應用程式主控板在應用程式上配置 Webhooks：

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

請注意，將商家電話號碼移轉到雲端 API 後，您必須使用 WhatsApp Business 帳號 > 訂閱的應用程式端點，為您的 Meta 應用程式訂閱與該商家號碼相關聯之 WABA 的 Webhooks：

要求語法

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

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

影音素材

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

請注意，為了確保訊息完整性，雲端 API 不允許使用內部部署 API 所允許的某些影音素材託管網域。如果您為影音素材使用託管服務，建議您在移轉之前，先在自由格式訊息和範本訊息中測試影音素材網址。如果您認為主機誤被封鎖，請聯絡支援團隊。

錯誤代碼

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

屬性驗證

內部部署 API 可以接受訊息張貼內容承載中的不明屬性，但雲端 API 會拒絕這些要求，因此請使您的訊息傳送要求僅使用受支援的屬性。
內部部署 API 允許在僅使用一個按鈕傳送訊息時省略按鈕索引，但雲端 API 會拒絕這些要求，因此請確認包含按鈕的訊息傳送要求也包含索引及其值。
傳送互動式訊息時，內部部署 API 接受在動作和按鈕物件屬性中包含前後有空格（或只有空格）的字串，但雲端 API 會拒絕這些要求。

按住即可聊天訊息

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

貼圖包

雲端 API 不支援貼圖包。

停機時間

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

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

傳送量

如果內部部署商家電話號碼有執行 2 個以上分片的多重連線，在雲端 API 上會自動升級為高傳送量。

官方商業帳號

如果要移轉具有官方商業帳號（OBA）狀態的商家電話號碼，當您在註冊號碼（步驟 3）時若包含其中繼資料（在步驟 2 中產生），系統將保留其狀態。如果省略此資料，該號碼將失去其 OBA 狀態。

移轉支援

如果您有任何疑問或需要有關移轉的協助，請提交直接支援票證：

主題：WABiz：雲端 API
要求類型：內部部署 API -> 雲端 API 移轉問題

步驟 1：停用雙步驟驗證

如果您知道商家電話號碼的 PIN 碼，可以略過此步驟。

執行步驟 3 時，您會需要商家電話號碼的 PIN 碼，所以如果您不知道 PIN 碼，則必須先為商家電話號碼停用雙步驟驗證。如果您不是商家電話號碼的擁有者，則請擁有者為您停用。

步驟 2：產生電話號碼中繼資料

使用備份和還原 API 來產生商家電話號碼的中繼資料。

要求語法

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> 可以是任何字串。此值會用來將中繼資料編碼，所以請記下此值，下一個步驟會需要它。

回應

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

此 API 會傳回指派給 data 屬性的編碼字串，其中描述您的商家電話號碼及其設定。請擷取此值，下一個步驟會需要它。

<METADATA> — 這是描述商家電話號碼及其設定的編碼字串。請擷取此值，下一個步驟會需要它。
<API_STATUS> — 內部部署 API 部署的狀態。
<API_VERSION> — 您目前執行的內部部署 API 版本號碼。

要求範例

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

回應範例

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

步驟 3：註冊號碼

使用雲端 API WhatsApp Business 電話號碼 > 註冊端點來註冊用於雲端 API 的號碼。

請加入上一個步驟中編碼的商家電話號碼中繼資料和密碼。雖然沒有此資料也可以註冊號碼，但是如果未加入此資料，商家電話號碼的個人檔案資料將會遺失，進而影響 WhatsApp Business 帳號做為官方商業帳號的狀態。

要求語法

POST /<BUSINESS_PHONE_NUMBER_ID>/register

張貼內容

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> — 現有 PIN 碼或您想要在商家電話號碼上設定的 PIN 碼。
<PASSWORD> — 您在上一個步驟中用來產生商家電話號碼中繼資料的密碼。
<METADATA> — 在上一個步驟中產生，描述商家電話號碼及其設定的編碼字串。

回應

{
  "success": <SUCCESS>
}

如果註冊成功，API 回應的 success 會設為 true，如果發生錯誤，則設為 false。

要求範例

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

回應範例

{
  "success": true
}

步驟 4：檢查訊息傳送健康狀態（選用）

要求商家電話號碼的 health_status 欄位，並驗證其可搭配雲端 API 用來傳送訊息。請參閱訊息傳送健康狀態。

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