WhatsApp Business Management API

總覽

Business Management API 允許您建立及管理 WhatsApp 相關的商家資產，例如 WhatsApp Business 帳號和訊息範本。此 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. 選擇應用程式正常運作所需的任何權限並產生權杖。

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

企業整合工具系統用戶存取權杖的範圍限定為個別已設置顧客，應由技術供應商和解決方案合作夥伴在存取已設置顧客資料時使用。

這些權杖對於在顧客 WhatsApp Business 帳號執行程式設計、自動化操作的應用程式非常有用，因為不需要應用程式用戶輸入，後續也無需重新驗證。

若要產生企業整合工具系統用戶存取權杖，您必須實作已配置「商家專用 Facebook 登入」的內嵌註冊，並在顧客完成流程時交換傳回給您的代碼。

請參閱內嵌註冊文件和企業整合工具系統用戶存取權杖文件，瞭解有關這些權杖及其產生方式的詳細資訊。

用戶存取權杖

雖然我們支援用戶存取權杖，且所有應用程式開發人員都可以使用，但您可能只會在首次使用應用程式主控板傳送第一則測試訊息時使用。但是，在開發應用程式時，您很可能會切換至系統用戶存取權杖（如果您是技術供應商或解決方案供應商，最終會切換至企業系統用戶存取權杖）。這是因為用戶存取權杖很快就會過期，因此您必須每隔幾小時產生一個新權杖。

產生用戶存取權杖的方法有以下幾種：

  • 存取「應用程式主控板」>「WhatsApp」>「API 設定」面板。每當您前往此面板時，一律會產生新的用戶存取權杖。權杖的範圍會自動限定為您的用戶，因為您在存取面板時已登入開發人員帳號。
  • 使用圖形 API 測試工具。
  • 實作「Facebook 登入」。

在要求中使用權杖

發出 API 要求時，將權杖包含在授權要求標頭中，前面為 Bearer。例如：

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

WhatsApp Business 帳號存取權限

許多端點要求權杖包含在 API 要求中的用戶，也需獲得權限以部分或完整存取查詢中的 WhatsApp Business 帳號（或其資產）。如果用戶不具存取權限，API 將傳回錯誤代碼 200。

您可以為任何用戶（包括系統用戶）設定細項存取權限。若要限制用戶群組存取特定資產的權限，系統用戶的細項存取權限會很有用。例如，如果您經營一家大型企業，希望某個部門只能擁有讀取 WhatsApp Business 帳號的範本和商家電話號碼資料的存取權限，則可以為該部門建立系統用戶，並將細項存取權限設為僅查看。

若要在 WhatsApp Business 帳號或其資產中指定用戶存取權限：

  1. 登入 Meta Business Suite。
  2. 在左上角的下拉式功能表中找到您的商業帳號，然後點擊其「設定」（齒輪）圖示。
  3. 點擊「企業管理平台設定」。
  4. 導覽至「帳號」>「WhatsApp 帳號」。
  5. 選擇適當的 WhatsApp Business 帳號。
  6. 選擇「WhatsApp 帳號存取權限」頁籤。
  7. 點擊「+新增用戶」按鈕。
  8. 選擇適當的系統用戶，並在 WhatsApp Business 帳號中指派適當的存取層級。

測試端點

測試端點時，建議使用我們的 Postman 集合 或 cURL。雖然您可以使用圖形 API 測試工具，但它會將權杖作為查詢字串參數傳遞，我們建議不要這樣做（而是在要求標頭中傳遞權杖）。

取得商家相關資訊

若要取得商家相關資訊，請發送 GET 要求至 WhatsAppBusinessAccount 端點，其中 <WHATSAPP_BUSINESS_ACCOUNT_ID> 是您的 WhatsApp Business 帳號編號。

要求範例

curl -i -X GET 'https://graph.facebook.com/v19.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"
}

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

要求範例

curl -i -X GET 'https://graph.facebook.com/v19.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 次呼叫。對於至少註冊一個電話號碼的活躍 WABA，您的應用程式針對每個活躍 WABA 的每個應用程式，每小時可以發出 5000 次呼叫。
呼叫類型 端點

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 而言，您的應用程式針對每個應用程式每小時可以發出 5000 次呼叫。
呼叫類型 端點

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 的狀態更新。

若要進一步瞭解如何取得目前的速率使用情況，請參閱「標頭」。

瞭解詳情

後續步驟