Meta Webhooks

WhatsApp Business 平台

Webhooks for WhatsApp Business Accounts

在 WhatsApp Business 帳戶 (WABA) 級別訂閱後，您便可以在 WhatsApp Business 帳戶有所變更時收到即時通知。如要設定 WhatsApp Business 帳戶的 Webhooks，請按以下步驟操作：

  1. 設定端點並配置 Webhooks。這些步驟與設定 Facebook 專頁的 Webhooks 相同。
  2. 在 WhatsApp Business 應用程式下訂閱應用程式。您必須訂閱由您企業所擁有的應用程式，因為與您企業共用的應用程式無法接收 Webhook 通知。
  3. 確保您的應用程式已完成應用程式審查且已要求 whatsapp_business_management 權限。

GET, POST, and DELETE calls to /{whats-app-business-account-id}/subscribed_apps are now subject to Business Use Case Rate Limits.

Set up Your Endpoint and Webhooks

Follow our Webhooks Getting Started guide to create your endpoint and configure your webhook endpoint. When you configure your endpoint, make sure to choose WhatsApp Business Account and subscribe to individual WhatsApp Business Account (WABA) fields.

Available Subscription Fields

可用訂閱欄位

欄位名稱 描述

account_review_update

當 WhatsApp Business 帳戶接受審查時，您會收到通知。

account_update

當 WhatsApp Business 帳戶有所變動時，您會收到通知。這些變動可能包括電話號碼更新、違反政策行為發生，以及 WhatsApp Business 帳戶被停權等。

business_capability_update

當功能有所更新時，您會收到通知。這些更新可能包括變更每個 WhatsApp Business 帳戶可關聯的電話號碼數量上限，或者變更每個電話號碼可發起的對話數量上限。

message_template_status_update

當訊息範本獲批、被拒或被停用時，您會收到通知。

messages

當您的商家收到來自顧客的訊息、您向顧客傳送訊息、訊息已送達至顧客，以及顧客已讀取您的訊息時，您會收到通知。

phone_number_name_update

當與電話號碼關聯的名稱獲批或被拒時，您會收到通知。

phone_number_quality_update

當電話號碼的品質相關狀態有所更新時，您會收到通知。

security

發生以下情況時，您會收到通知：

  • 您要求停用雙重認證驗證碼
  • 雙重認證驗證碼遭停用
  • 雙重認證驗證碼有更新

    • 請參閱 WhatsApp Business 帳戶 Webhooks 參考資料 ，進一步了解各個裝載欄位；以及參閱 WhatsApp 雲端 API Webhooks 參考資料 ，進一步了解您會收到的不同類型 messages 通知。

    Subscribe Your App

    You need to subscribe your app to webhooks on a given WABA. We only send notifications if your webhooks-configured app is subscribed to webhooks on a given WABA, and only if the app has permission to edit that WABA.

    Create a Subscription

    Request

    To subscribe your app to webhooks on a WABA, send a POST request to the WABA > Subscribed Apps endpoint.

    curl -X POST 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

    Response

    Upon success:

    {
  "success": "true"
}

    Get Subscribed Apps

    To get a list of apps subscribed to webhooks on a WABA, send a GET request to the WABA > Subscribed Apps endpoint.

    Request

    curl 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

    Response

    A successful response will list the subscribed apps:

    {
  "data": [
    {
      "whatsapp_business_api_data": {
        "link": "<APP_1_URL>",
        "name": "<APP_1_NAME>",
        "id": "<APP_1_ID>"
      }
    },
    {
      "whatsapp_business_api_data": {
        "link": "<APP_2_URL>",
        "name": "<APP_2_NAME>",
        "id": "<APP_2_ID>"
      }
    },
    ...
  ]
}

    Delete a subscription

    To unsubscribe your app from webhooks on a WABA, send a DELETE request to the subscribed_apps endpoint.

    Request

    curl -X DELETE 'https://graph.facebook.com/<AP_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

    Response

    A successful response will read:

    {
  "success": "true"
}

    Subscribe with Graph API Explorer

    If you don't want to subscribe your app with direct API calls, you can easily do it with Graph API Explorer.

    Replace the me?fields=id,name query with <WHATSAPP_BUSINESS_ACCT_ID>/subscribed_apps. It will subscribe the app you use to send the POST request in Graph Explorer.

    Your app must have permission to edit the WhatsApp business account in order to successfully subscribe.

    Example Webhook payload:

    [
  {
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "0",
        "time": 1602782939,
        "changes": [
          {
            "field": "phone_number_name_update",
            "value": {
              "display_phone_number": "16505551111",
              "decision": "APPROVED",
              "requested_verified_name": "WhatsApp",
              "rejection_reason": null
            }
          }
        ]
      }
    ]
  }
]

    Enabling mTLS on a WhatsApp Business Account

    Enabling and disabling mTLS is not supported at the Business Phone Number or WABA level. It is only available for object Webhook subscriptions.

    You can enable Mutual TLS (mTLS) on the webhooks you receive from WhatsApp for added security.

    You must verify the callback URL before enabling mTLS. If you have more than one application accessing WhatsApp Cloud API, you will need to enable mTLS for each application.

    mTLS toggle for WhatsApp Business accounts