總覽

由 Meta 代管的雲端 API 可讓中型和大型商家與大量顧客通訊。商家可以使用此 API 來組建系統，將數以千計的顧客與服務人員或 Bot（機器人程式）連結，以便進行程序化和手動通訊。此外，商家也可以將此 API 與 CRM 和行銷平台等眾多後端系統整合。

HTTP 通訊協定

雲端 API 是以圖形 API 為基礎所建置，因此要求是透過使用 HTTP 通訊協定以及網址參數、標頭和要求內容的組合來表示。例如，從 UNIX 命令列對雲端 API 發出的指令呼叫如下所示：

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

如果您還不熟悉圖形 API，請參閱我們的圖形 API 說明文件以瞭解基本資訊。圖形 API 和雲端 API 之間的主要差異在於經常使用的存取權杖類型、資源權限、要求語法和 Webhooks 語法。這些差異在雲端 API 系列說明文件的相應章節中將會更詳細地介紹。

驗證和授權

存取權杖

API 支援三種類型的權杖：

系統用戶存取權杖
企業整合工具系統用戶存取權杖
用戶存取權杖

請參閱存取權杖，以決定應使用的權杖類型。請注意，您應透過要求標頭來傳遞權杖，而不是以查詢字串參數來傳遞。

權限

API 依賴下列圖形 API 權限。應用程式所需的確切權限組合取決於應用程式將存取的端點。

business_management - 與商家資產管理組合互動時需要此權限。
whatsapp_business_management - 與 WABA 及其分析資料，或是其任何範本或商家電話號碼互動時需要此權限。
whatsapp_business_messaging - 向 WhatsApp 用戶傳送和接收訊息時需要此權限。

系統通常會在 Meta Business Suite 中產生存取權杖時授予以上權限。請參閱存取權杖文件中的權杖產生章節。

版本控制

版本控制使用圖形 API 的版本控制通訊協定。這表示所有端點要求都可以包含版本號碼，每個版本將可使用約 2 年才停用，且無法再接受呼叫。

傳送量

對於每個註冊的商業電話號碼，預設情況下，雲端 API 每秒最多可收發的訊息量達 80 則（mps），用戶可視自動升級提出每秒最多達 1,000 mps 的要求。

傳送量包括傳入和傳出訊息以及所有訊息類型。請注意，不論傳送量為何，商業電話號碼仍須遵守其 WhatsApp Business 帳號之商業使用案例限速和範本訊息限制的規範。

如果您嘗試傳送的訊息數量超過目前傳送量層級允許的訊息數量，API 將傳回錯誤代碼 130429，直到您再次處於允許的層級內。此外，傳送量層級適用於涉及不同 WhatsApp 用戶電話號碼的發訊行銷活動。如果您嘗試向同一個 WhatsApp 用戶號碼傳送過多訊息，可能會發生配對速率限制錯誤。

更高傳送量

如果您符合我們的資格條件，我們會自動將您的商業電話號碼升級為 1,000 mps，您不需支付任何費用。更高傳送量不會產生額外費用或影響定價。

升級程序本身最多可能需要 1 分鐘。在此期間，該號碼將無法在我們的平台上使用。如果在 API 要求中使用，API 將傳回錯誤代碼 131057。升級商業電話號碼後，系統將自動升級該號碼以因應將來任何增加的傳送量（無停機時間）。

資格條件

商業電話號碼必須能夠在連續 24 小時內與不限數量的不重複顧客開始對話。
商業電話號碼必須經過註冊才能與雲端 API 搭配使用。如果該號碼已註冊用於內部部署 API，必須先將其移轉至雲端 API。
商業電話號碼必須具備中等以上的品質評比。

Webhooks

您的 Webhook 伺服器應能承受傳出訊息流量的 3 倍負載量，以及預期傳入訊息流量的 1 倍負載量。例如，如果每秒傳送 1,000 則訊息，並預期有 30% 的回應率，您的伺服器應該要能夠處理最多 3000 個訊息狀態 Webhooks，加上額外 300 個傳入訊息 Webhooks。

我們會嘗試以並行方式傳遞 Webhooks，因此建議您為 Webhook 伺服器進行配置和負載測試時，應確保 Webhook 伺服器能夠處理下列延遲標準的並行要求：

中位數延遲不超過 250 毫秒。
少於 1% 的延遲超過 1 秒。

我們會採用指數輪詢方式，嘗試重新投遞失敗的 Webhooks，最多持續 7 天。

多媒體訊息

為了充分利用更高的傳送量，建議您將多媒體素材上傳至我們的伺服器，並在多媒體訊息中使用所傳回的多媒體編號，而不是將素材託管在我們的伺服器上並使用多媒體網址。如果您希望（或必須）將素材託管在自己的伺服器上，建議您使用多媒體快取。

取得傳送量層級

使用 WhatsApp Business 電話號碼端點來取得電話號碼的目前傳送量層級：

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

移轉

如果您要將商家電話號碼從內部部署 API 移轉到雲端 API，而該商家電話號碼的多點連線執行 2 個以上的分片，則會自動升級至更高的傳送量。

速率限制

請參閱 WhatsApp Business Management API 限速。

除了這些限速，我們也對範本訊息和測試商家電話號碼等個別資源有更細微的限制：

測試訊息限速：適用於尚未驗證的 WABA。
品質評分和訊息限制：適用於已驗證的 WABA。
負載量限速：適用於所有帳號。
商業電話限速：適用於所有帳號，並限制每個商業電話號碼的輸送量。

可用的衡量指標

若為雲端 API 用戶，您可以查看已傳送和已送達的訊息數量，以及其他衡量指標。詳情請參閱取得帳號衡量指標。

擴展

在 Meta 的基礎架構中，雲端 API 會在您的限速（訊息量和 WABA 數量）內自動擴展並調整，以處理您的工作量。

資料隱私和帳號安全

如需相關資訊，請參閱資料隱私和帳號安全總覽。

加密

透過雲端 API，每則 WhatsApp 訊息在離開裝置之前，都會持續受到訊號通訊協定加密的保護。這表示使用 WABA 傳送的訊息，會安全送達每個商家選擇的目的地。

雲端 API 使用業界標準加密技術來保護傳輸中和待用的資料。此 API 使用圖形 API 來傳送訊息和 Webhooks，以接收事件，這兩種 API 都是透過業界標準 HTTPS 運作，受 TLS 保護。請參閱我們的「加密總覽」白皮書，以瞭解其他詳細資料。

請參閱我們的「加密總覽」白皮書，以瞭解其他詳細資料。

配對速率限制

商家電話號碼限制為每 6 秒向同一 WhatsApp 用戶電話號碼傳送 1 則訊息（每秒 0.17 則訊息），大致相當於每分鐘 10 則訊息，或每小時 600 則訊息。如果超過此限制，API 將傳回錯誤代碼 131056，直到您再次處於限制範圍內為止。

如有必要，您可以在 6 秒內傳送最多 45 則突發訊息。當您傳送突發訊息時，實際上是在借用配對速率限制的額度，因此您將無法向同一用戶傳送後續訊息，直到一般向用戶傳送如此多「非突發」訊息所需的時間過去為止。例如，向用戶傳送 20 則「非突發」訊息約需 2 分鐘，因此，如果您傳送 20 則突發訊息，必須等待約 2 分鐘才能向用戶傳送另一則訊息。

為了避免必須計算突發後訊息等待時間，我們建議，如果訊息傳送要求在傳送突發訊息後失敗，您可以在 4^X 秒後重試，其中 X = 0，並在每次嘗試失敗後增加 1，直到要求成功為止。

工具

WhatsApp 管理工具

WhatsApp 管理工具是我們的網路應用程式，可讓您手動管理 WhatsApp 資源（例如 WABA、商家電話號碼和範本），並提供簡單的方法查看這些資源的洞察報告和品質評分或限制。WhatsApp 管理工具提供的大多數功能也可以經由 API 獲得，但有少部分例外。

您可以透過數種方式使用 WhatsApp 管理工具。每種方式皆假設您已經完成立即開始文件中的所有步驟。

透過 Meta Business Suite

登入 Meta Business Suite。
如果您有多個商家資產管理組合，請使用左側下拉式功能表，選擇擁有或有權限存取您想要在 WhatsApp 管理工具中載入之 WABA 的帳號。
在左側功能表中，瀏覽至帳號 > WhatsApp 帳號。
選擇 WABA。
在「摘要」頁籤中，點擊「WhatsApp 管理工具」按鈕。

透過應用程式主控板

前往我的應用程式。
選擇與您想要在 WhatsApp 管理工具中載入之 WABA 相關的應用程式。
在左側功能表中，瀏覽至 WhatsApp > 快速入門。
點擊 WhatsApp Business 區塊中的「帳號資訊」功能鍵。

透過網址

您可以前往下列網址直接進入 WhatsApp 管理工具總覽，其中顯示給定的商家資產管理組合擁有或與之分享的所有 WABA：

https://business.facebook.com/wa/manage/home/

總覽預設會載入您最近建立或經授予存取權限的 WABA，但您可以使用左側下拉式功能表選擇包含您嘗試存取之 WABA 的商家資產管理組合。不過，這樣會讓您退出總覽，而您必須使用左側功能表並瀏覽至帳號 > WhatsApp 帳號 >（選擇想要的 WABA）> 設定 > WhatsApp 管理工具（按鈕）。

或者，如果您有多個商家資產管理組合，可以將帳號的編號附加至網址的結尾，並新增為書籤以方便存取：

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

我們在 WhatsApp Business 平台工作區提供一個包含常見查詢的雲端 API Postman 集合。

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

總覽

HTTP 通訊協定

相關資源

商家資產管理組合

WhatsApp Business 帳號

WhatsApp Business 電話號碼

WhatsApp 訊息範本

Webhooks

測試資源

驗證和授權

存取權杖

權限

版本控制

傳送量

更高傳送量

資格條件

Webhooks

多媒體訊息

取得傳送量層級

移轉

速率限制

可用的衡量指標

擴展

資料隱私和帳號安全

加密

配對速率限制

工具

WhatsApp 管理工具

透過 Meta Business Suite

透過應用程式主控板

透過網址

Postman