概覽

由 Meta 代管的雲端 API 幫助中型至大型企業與大量顧客溝通交流。商家可以使用此 API 來組建系統，將數以千計顧客與服務人員或 BOT（機械人程式）連結，以便在程式輔助下和以手動方式通訊。此外，企業也可以將此 API 與客戶關係管理系統和營銷平台等眾多後端系統整合。

HTTP 通訊協定

雲端 API 建基於 Graph 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/"
  }
}'

如果您不熟悉 Graph API，請參閱 Graph API 文件了解基本資訊。Graph API 和雲端 API 之間的主要分別，在於您通常會使用的存取憑證類型、資源權限、要求語法及 Webhooks 語法。雲端 API 文件集的相應部分會更詳細說明上述分別。

資源

使用 API 時，您主要會與以下資源互動。

商家資產管理組合

若要使用此 API，您必須擁有商家資產管理組合。如果您沒有商家資產管理組合，系統會在新手入門程序中提示您建立。商家資產管理組合會用作您 WhatsApp Business 帳戶和商家電話號碼的容器。

如要進一步了解商家資產管理組合，請參閱關於 Meta Business Suite 中的商家資產管理組合這篇幫助中心文章。

WhatsApp Business 帳戶

WhatsApp Business 帳戶在 WhatsApp Business 平台上代表商家，主要由關於特定商家的中繼資料組成。WhatsApp Business 電話號碼和 WhatsApp 訊息範本等其他大部分 WhatsApp 資源都與 WhatsApp Business 帳戶連結。

您可以按照新手入門文件中的步驟，建立 WhatsApp Business 帳戶。如要進一步了解 WhatsApp Business 帳戶及其限制，請參閱 WhatsApp Business 帳戶一文。

WhatsApp Business 電話號碼

WhatsApp Business 電話號碼（商家電話號碼）是真正的電話號碼，在雲端 API 註冊使用後，便可用於透過 API 與 WhatsApp 用戶收發訊息。

商家電話號碼主要由關於電話號碼本身及您企業的中繼資料組成。當用戶與您的商家電話號碼互動時，此中繼資料可在 WhatsApp 用戶端顯示。

您可以按照新手入門文件中的步驟，建立商家電話號碼。請注意，商家電話號碼及其用途受到限制，相關內容會在商家電話號碼文件中詳細說明。

WhatsApp 訊息範本

WhatsApp 訊息範本（範本）是可自訂的範本，您可以使用各種範本元件透過 API 構建這類範本。建立的範本會自動接受審查，經核准後便可用於範本訊息。

您可透過 API 傳送兩種基本類型的訊息：自由格式訊息和範本訊息。由於範本訊息規定要使用經核准的 WhatsApp 訊息範本，因此比起自由格式訊息受到更多限制。不過，範本須經過審查和核准方可使用，因此範本訊息收到傳送對象負面意見的可能性較低，避免您完全無法向顧客傳送訊息。

如要進一步了解範本，請參閱範本文件。

Webhooks

Webhooks 是使用 HTTP 通訊協定傳送至您伺服器公開端點的 JSON 裝載。由於 WhatsApp 用戶向您商家電話號碼傳送的任何訊息都會以 Webhook 形式傳送內容，而且所有送出訊息的傳送狀態更新均透過 Webhook 回報，因此雲端 API 會大量使用 Webhooks。

請注意，我們提供了 Webhook 應用程式範例讓您在 Glitch 複製並用作測試。此應用程式直接在主控台傾印 Webhooks 裝載，以便您查看相關內容。要注意的是，您最終都需要在自己的伺服器上自行構建端點，從而根據您的業務邏輯理解 Webhooks。

請參閱 Meta Webhooks 進一步了解 Webhooks 和理解 Webhooks 的方式，並查看 WhatsApp Business 帳戶的 Webhooks 文件。

測試資源

您首次完成新手入門文件中的步驟時，系統會自動為您建立測試用的 WhatsApp Business 帳戶和測試用的商家電話號碼。

兩者在測試中非常有用，因為這類帳戶和電話號碼能繞過大部分訊息限制，而且無需您提供付款方式即可傳送範本訊息。

您可在以下情況刪除商家資產管理組合及其測試資源：

• 您在與應用程式連結的商家資產管理組合擔任管理員
• 商家資產管理組合沒有與其他應用程式連結
• 商家資產管理組合沒有與任何其他 WhatsApp Business 帳戶連結
• WhatsApp Business 帳戶沒有與任何其他商家電話號碼連結

如要刪除商家資產管理組合及其測試資源，請按照下列步驟操作：

1. 前往應用程式管理中心 > WhatsApp > 配置面板。
2. 找出測試帳戶區塊。
3. 點擊刪除按鈕。

驗證和授權

存取憑證

API 支援 3 種類型的憑證：

• 系統用戶存取憑證
• 企業整合系統用戶存取憑證
• 用戶存取憑證

請參閱存取憑證，確定您應該使用哪類憑證。請注意，憑證應透過要求標題傳遞，而不是查詢字串參數。

權限

API 使用以下 Graph API 權限。您應用程式所需的確切權限組合，視乎應用程式將會存取哪些端點而定。

• business_management：與商家資產管理組合互動時需要用到。
• whatsapp_business_management：與 WhatsApp Business 帳戶及其分析工具，或者其任何範本或商家電話號碼互動時需要用到。
• whatsapp_business_messaging：與 WhatsApp 用戶收發訊息時需要用到。

這些權限一般會於在 Meta Business Suite 產生存取憑證時授予。請參閱存取憑證文件的產生憑證部分。

版本控制

版本控制使用的是 Graph API 的版本控制協定。這表示所有端點要求均包含版本編號，並且每個版本的可用時間約為 2 年，到期後才會被停用，而一經停用便無法再被呼叫。

輸送量

雲端 API 可預設為每個註冊商家電話號碼每秒最多支援 80 則訊息，亦可透過自動升級將最多支援訊息提升至每秒 1,000 則。

輸送量包含已接收和已發出的訊息，以及所有訊息類型。請注意，無論輸送量多少，商家電話號碼仍需遵守其 WhatsApp Business 帳戶的商家用例流量限速和範本訊息限制。

如果您嘗試傳送的訊息數量超出目前輸送量級別所允許的數量，API 將傳回錯誤代碼 130429，直至您回到允許級別為止。此外，輸送量級別旨在用於涉及不同 WhatsApp 用戶電話號碼的訊息宣傳活動。如果您嘗試向同一個 WhatsApp 用戶電話號碼傳送過多訊息，可能會遇到配對限速限制錯誤。

提升輸送量

如果您符合資格規定，我們會自動免費將您商家電話號碼的輸送量升級至每秒 1,000 則訊息。提升輸送量不會產生額外收費或影響定價。

升級過程本身最多需時 1 分鐘。在此期間，您無法在我們的平台上使用有關號碼。如果將號碼用於傳送 API 要求，API 將傳回錯誤代碼 131057。商家電話號碼一經升級，其輸送量會隨著未來出現提升而自動升級，而且不會受停機時間影響。

資格要求

• 商家電話號碼必須能夠在持續計算的 24 小時期限內與無限個不重複的顧客開啟對話。
• 商家電話號碼必須註冊，才能使用雲端 API。如果該號碼已經註冊使用內部部署 API，則必須轉移至雲端 API。
• 商家電話號碼的品質評級必須為中或以上。

Webhooks

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

我們會嘗試同時傳送多個 Webhooks，因此建議您對 Webhook 伺服器執行相應的配置和負載測試，以便根據下列延遲標準處理同時發出的要求：

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

我們將嘗試使用指數退避方式，在最多 7 天內重新傳送失敗的 Webhooks。

媒體訊息

如要充分發揮更高輸送量的優勢，建議將媒體素材上載至我們的伺服器，並在媒體訊息中使用伺服器傳回的媒體編號，而非將媒體素材託管到您的自有伺服器上並使用媒體素材網址。如果您想（或必須）在您的自有伺服器上託管媒體素材，建議使用媒體快取。

獲取輸送量級別

使用 WhatsApp Business 電話號碼端點，獲取電話號碼目前的輸送量級別：

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

轉移

如您要將以多點連線方式運行 2 個或更多分片的商業電話號碼從內部部署 API 轉移到雲端 API，系統會自動將其升級到更高輸送量。

限速規定

請見 WhatsApp Business 管理 API 限速規定。

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

• 測試訊息限速限制：適用於未經驗證的 WhatsApp Business 帳戶。
• 品質評級和訊息限制：適用於經驗證的 WhatsApp Business 帳戶。
• 負載量限速：適用於所有帳戶。
• 商家手機號碼限速：適用於所有帳戶，限制每個商家手機號碼的輸送量。

可用衡量數據

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

擴展

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

資料私隱和安全

詳情請參閱私隱與安全概覽。

加密

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

雲端 API 使用業界標準加密技術來保護傳輸中的資料和靜態資料。此 API 使用 Graph API 和 Webhooks，分別用來傳送訊息和接收事件；Graph API 和 Webhooks 都是透過業界標準 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 Business 帳戶、商家電話號碼及範本等 WhatsApp 資源，方便您輕鬆地查看洞察報告及品質評級，或這類資源所受到的限制。除了少數例外情況，WhatsApp 管理工具提供的大部分功能亦可經由 API 取用。

有幾種途徑可存取 WhatsApp 管理工具。在每種途徑的說明中，我們都假設您已經完成新手指南文件的所有步驟。

經由 Meta Business Suite

1. 登入 Meta Business Suite。
2. 如果您有多個商家資產管理組合，請經由左側的下拉式選單，在當中選擇一個帳戶；有關帳戶應擁有或能存取您希望在 WhatsApp 管理工具載入的 WhatsApp Business 帳戶。
3. 在左側選單中，前往帳戶 > WhatsApp 帳戶。
4. 選擇 WhatsApp Business 帳戶。
5. 在摘要分頁中，點擊 WhatsApp 管理工具按鈕。

經由應用程式管理中心

1. 前往我的應用程式。
2. 選擇與您想載入 WhatsApp 管理工具的 WhatsApp Business 帳戶所連結的應用程式。
3. 在左側選單中，前往 WhatsApp > 快速入門。
4. 點擊 WhatsApp Business 區塊中的帳戶資料功能鍵。

經由網址

您可以瀏覽以下網址，直接前往 WhatsApp 管理工具概覽，當中展示了所有由特定商家資產管理組合所擁有或共用的 WhatsApp Business 帳戶：

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

概覽預設會載入您最近建立或取得存取權限的 WhatsApp Business 帳戶，但您也可以經由左側下拉式選單，根據您嘗試存取的 WhatsApp Business 帳戶，選擇其所屬的商家資產管理組合。不過，這會令您跳出概覽頁面。您必須使用左側選單前往帳戶 > WhatsApp 帳戶 >（選擇所需 WhatsApp Business 帳戶）> 設定 > WhatsApp 管理工具（按鈕）。

此外，如果您有多個商家資產管理組合，您亦可以在網址結尾處加上帳戶編號，並將其加入書籤以便存取：

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

Postman

我們設有雲端 API Postman 收藏，當中包含 WhatsApp Business 平台工作空間中的常見查詢。