WhatsApp Business 管理 API
返回中文(香港)
這份文件已更新。
中文(香港) 的翻譯尚未完成。
英文更新時間：9月10日

概覽

您可以使用企業管理 API，來建立和管理 WhatsApp Business 帳戶和訊息範本等與 WhatsApp 相關的商家資產。此 API 建於推廣 API 的基礎之上，並且會使用其部分的端點，因此本文件可能會在適當時加入此推廣 API 文件的連結。

必要條件

存取憑證

此平台支援以下存取憑證類型。您使用的類型取決於您的應用程式將供哪些用戶使用，以及您是否為解決方案供應商。

系統用戶存取憑證

系統用戶存取憑證代表您、您的企業或機構，或您企業或機構內的用戶。這類憑證的主要優點是不會過期，並且可以在您企業中代表自動化服務，而無需用戶輸入任何資料。

解決方案合作夥伴如要與新加入的顧客共用信用額度，只可使用系統用戶存取憑證。

在產生系統用戶存取憑證之前，您必須建立系統用戶。大多數端點都會檢查以此憑證所識別出的用戶是否有權限存取所查詢的資源。如果用戶無權存取相關資源，系統就會拒絕要求，並傳回錯誤代碼 200。

系統用戶可以是員工或管理員。

員工系統用戶

員工系統用戶必須獲得由 Meta 商家擁有或與之分享的個別 WhatsApp Business 帳戶之存取權。如果您的應用程式只需要就您擁有的幾個 WhatsApp Business 帳戶取得存取權，員工系統用戶就已能滿足需要。

建立後，您必須對向系統用戶所需存取的每個 WhatsApp Business 帳戶授予部分或完整商家資產存取權。

管理員系統用戶

管理員系統用戶預設在所有 WhatsApp Business 帳戶中，以及由您或您企業擁有或有份共用的資產中擁有完整管理權限。

如果您的應用程式需要存取最近與您企業共用的 WhatsApp Business 帳戶，管理員系統用戶便相當實用；如果您是使用員工系統用戶，就必須手動向與您共用的每個 WhatsApp Business 帳戶授予商家資產存取權。

請注意，您可以按不同 WhatsApp Business 帳戶授予部分存取權，以覆寫管理員系統用戶的預設商家資產存取權。請查看商家資產存取權，了解如何設定和覆寫存取權。

建立系統用戶

如要建立系統用戶，請按照下列步驟操作：

  1. 登入 Meta Business Suite。
  2. 在左上角的下拉式選單中，找出您的商業帳戶，然後點擊其以齒輪圖案顯示的設定圖示。
  3. 點擊企業管理平台設定。
  4. 前往用戶 > 系統用戶。
  5. 點擊新增按鈕，以建立管理員或員工系統用戶。

產生系統用戶存取憑證

如要在建立系統用戶後產生系統用戶存取憑證，請按照下列步驟操作：

  1. 登入 Meta Business Suite。
  2. 在左上角的下拉式選單中，找出您的商業帳戶，然後點擊其以齒輪圖案顯示的設定圖示。
  3. 點擊企業管理平台設定。
  4. 前往用戶 > 系統用戶。
  5. 從系統用戶清單中選擇相應的系統用戶。
  6. 點擊產生新存取代碼按鈕。
  7. 選擇此憑證將由哪個應用程式使用。
  8. 選擇應用程式正常運作所需的任何 Graph API 權限，然後產生憑證。

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

企業整合工具系統用戶存取憑證分別專屬於各個已加入的顧客，技術供應商和解決方案合作夥伴在存取已加入顧客資料時應使用此憑證。

應用程式如果會在顧客 WhatsApp Business 帳戶上執行自動程序化操作，這類憑證便非常實用，無需依賴應用程式用戶輸入資料，之後也無需重新驗證。

如要產生企業整合工具系統用戶存取憑證，您必須執行以商家專用 Facebook 登入設定的內嵌註冊流程，並交換顧客完成流程時傳回給您的代碼。

請參閱內嵌註冊文件企業整合工具系統用戶存取憑證文件，進一步了解這些憑證及其產生方式。

用戶存取憑證

儘管我們支援所有應用程式開發人員使用用戶存取憑證，但您可能只會在首次使用應用程式管理中心傳送第一則測試訊息時才會用到用戶存取憑證。但是，在開發應用程式時，您很可能會改用系統用戶存取憑證；而如果您是技術供應商或解決方案供應商，則可能最終會改用企業系統用戶存取憑證。這是因為用戶存取憑證很快就會過期，每隔幾小時就需要產生新憑證。

有幾種方法可以產生用戶存取憑證：

  • 存取應用程式管理中心 > WhatsApp > API 設定面板。您每次存取此面板時，系統都會產生新的用戶存取憑證。由於您在存取面板時已登入開發人員帳戶，因此憑證的使用範圍會自動限定為您的用戶。
  • 使用 Graph API 測試工具。
  • 執行 Facebook 登入。

在要求中使用憑證

發出 API 要求時，請在授權要求標題中加入您的憑證，並且注意憑證前應加上前綴 Bearer。例如：

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

商家資產存取權

建立系統用戶後，您必須設定商家資產存取權級別。許多端點也會要求憑證包含在 API 要求內的系統用戶，需擁有所查詢 WhatsApp Business 帳戶或其資產的部分或完整商家資產存取權。如果系統用戶沒有相應的存取權，這些端點就會傳回錯誤代碼 200。

請注意，如果您將系統用戶在 WhatsApp Business 帳戶上的商家資產存取權設定為授予部分存取權，則可以進一步限制用戶對 WhatsApp Business 帳戶特定資產或操作的存取權。舉例來說，如果您擁有一間大型企業，並希望特定部門對 WhatsApp Business 帳戶的範本和企業電話號碼資料只有讀取權限，便可以為相關部門建立系統用戶，並將細項存取權設為僅限查看相關資料。

如要設定 WhatsApp Business 帳戶的商家資產存取權，請按照下列步驟操作：

  1. 登入 Meta Business Suite。
  2. 在左上角的下拉式選單中，找出您的商業帳戶，然後點擊其以齒輪圖案顯示的設定圖示。
  3. 前往帳戶 > WhatsApp 帳戶。
  4. 選擇適當的 WhatsApp Business 帳戶。
  5. 選擇 WhatsApp 帳戶存取權分頁。
  6. 點擊 +新增用戶按鈕。
  7. 在 WhatsApp Business 帳戶選擇適當的系統用戶並分配適當的存取級別。

測試端點

我們建議使用 Postman 收藏或 cURL 來測試端點。雖然您可以使用 Graph API 測試工具，但此工具會將憑證作為查詢字串參數傳遞，我們並不建議這種傳遞方式；請改為在要求標題中傳遞憑證。

獲取商家相關資訊

如要取得特定商家的相關資訊，請向 WhatsAppBusinessAccount 端點傳送 GET 要求，其中 <WHATSAPP_BUSINESS_ACCOUNT_ID> 是您的 WhatsApp Business 帳戶編號。

要求範例

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

回應範例

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

如要取得特定商家的特定資訊（例如名稱、訊息範本和手機號碼），請向 WhatsAppBusinessAccount 端點傳送 GET 要求（其中 <WHATSAPP_BUSINESS_ACCOUNT_ID> 是您的 WhatsApp Business 帳戶編號），並將 fields 參數設定為要被傳回的項目清單。

要求範例

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

回應範例

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

限速限制

系統會根據您應用程式的呼叫次數，計算該應用程式向 WhatsApp Business Management API 發出多少項要求。應用程式的呼叫次數是指該應用程式在連續一小時內可以執行多少次呼叫。對於以下 WhatsApp Business Management API，您的每個應用程式每小時預設可以向每個 WhatsApp Business 帳戶（WABA）執行 200 次呼叫。對於正常使用中且至少擁有 1 個已註冊手機號碼的 WABA，您的每個應用程式每小時可以向每個正常使用中的 WABA 執行 5,000 次呼叫。
呼叫類型 端點

GET

/{whatsapp-business-account-id}

GET、POST 和 DELETE

/{whatsapp-business-account-id}/assigned_users

GET

/{whatsapp-business-account-id}/phone_numbers

GET、POST 和 DELETE

/{whatsapp-business-account-id}/message_templates

GET、POST 和 DELETE

/{whatsapp-business-account-id}/subscribed_apps

GET

/{whatsapp-business-account-to-number-current-status-id}

對於以下帳戶額度 API，您的每個應用程式每小時可以執行 5,000 次呼叫。
呼叫類型 端點

GET

/{business-id}/extendedcredits

POST

/{extended-credit-id}/whatsapp_credit_sharing_and_attach

GET 和 DELETE

/{allocation-config-id}

GET

/{extended-credit-id}/owning_credit_allocation_configs

為免達到傳輸率限制，我們建議使用 Webhooks 來追蹤訊息範本、手機號碼和 WABA 的狀態更新。

若要進一步了解如何查看您目前的傳輸率使用情況，請參閱頁首。

了解詳情

後續步驟