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

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

請注意，在不同 API 之間轉移商家電話號碼的操作，與在 WhatsApp Business 帳戶之間轉移商家電話號碼的操作不同。

如需從雲端 API 轉移至內部部署 API，請參閱從雲端 API 轉移至內部部署 API。

運作方式

轉移過程中會產生與商家電話號碼有關的中繼資料，而該資料會用於註冊的號碼，以在雲端 API 使用。這樣做會將號碼從內部部署 API 取消註冊，因為一個號碼每次只能在一個 API 註冊使用。

轉移操作不會影響以下項目：

商家電話號碼的顯示名稱、驗證狀態或品質評分
商家電話號碼所用的範本及其狀態
商家自有的 WhatsApp Business 帳戶、官方商業帳戶狀態，或其收發訊息限制

不過，為了支援轉移操作，您必須留意任何 API 之間的差異並針對這些差異採取措施，然後才執行本文件所述的轉移步驟。

必要條件

Meta 應用程式

您必須擁有一個 Meta 商業應用程式，而此應用程式應可透過已加入的顧客資料使用雲端 API 和企業管理 API，亦可獲取雲端 API 和企業管理 API 的 Webhooks 摘要。此應用程式亦必須與您已驗證的 Meta 商業帳戶連結，或由該帳戶所認領。

如果您沒有 Meta 商業應用程式，或您的 Meta 商業應用程式沒有配置 WhatsApp 商品，請完成雲端 API 新手入門指南中的步驟。完成這些步驟之後，將會產生測試雲端 API 和企業管理 API 所需的所有資源。

應用程式審查

您的 Meta 應用程式必須接受應用程式審查，並獲批准取得 whatsapp_business_messaging 和 whatsapp_business_management 權限（即取得相關進階存取權限）。

最佳操作實例

確保您的應用程式能夠處理所有 API 之間的差異後，建議您先轉移用量較低的商家電話號碼，然後再驗證您想透過雲端 API 提供的所有功能是否都能正常運作。驗證一切都能正常運作後，您可轉移其他號碼。

我們亦建議在通往內部部署 API 部署的流量較低時執行轉移操作。

API 之間的差異

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

Webhooks

雲端 API 和企業管理 API 的 Webhooks 裝載結構與內部部署 API 的裝載結構並不相同。建議建立新的 Webhook 端點，專門用來處理雲端 API 和企業管理 API。

請參閱以下文件，了解不同裝載的差別，以及如何使用應用程式管理中心配置應用程式 Webhooks：

配置：WhatsApp 的 Webhooks
雲端 API Webhook 裝載：Webhooks 通知裝載參考資料
企業管理 API Webhook 裝載：Webhooks 設定

請注意，將商家電話號碼轉移至雲端 API 之後，您必須使用 WhatsApp Business 帳戶 > 已訂閱的應用程式端點，為您的 Meta 應用程式訂閱與商家電話號碼相關的 WhatsApp Business 帳戶的 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 和企業管理 API 的錯誤代碼與內部部署 API 的錯誤代碼並不相同。請參閱下列文件：

屬性驗證

內部部署 API 可接受在訊息發佈正文裝載中使用未知屬性，但雲端 API 會拒絕這類要求，因此請確保您的訊息傳送要求僅使用支援的屬性。
內部部署 API 允許在傳送僅包含一個按鈕的訊息時忽略按鈕索引，但雲端 API 會拒絕這類要求，因此請確保包含按鈕的訊息傳送要求同樣包含索引和索引值。
內部部署 API 接受在傳送互動訊息時，操作和按鈕物件屬性的文字字串在開頭或結尾有空格（或僅空格），但雲端 API 會拒絕這類要求。

「按住即可聊天」訊息

內部部署 API 透過將 messages.type 設定為 voice 以在 Webhooks 中辨別「按住即可聊天」（PTT）訊息，而雲端 API 則透過將 messages.audio.voice 設定為 true 以辨別 PTT 訊息。

貼圖集

雲端 API 不支援貼圖集。

停機時間

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

強烈建議您將轉移時間安排在號碼活躍度較低的時段，以儘量減少停機時間的影響。

輸送量

如果內部部署 API 中的商家電話號碼為多點連線，可運行 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 商家電話號碼 > 註冊端點註冊在雲端 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 將以設定為 true 的 success 回應；如發生錯誤，API 則以 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