Meta Webhooks

WhatsApp Business 平台

Webhooks for WhatsApp Business Accounts

因為在 WhatsApp Business 帳號層級訂閱，而使 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

有功能更新時，會傳送通知給您。這可能包括 WABA 可擁有的電話號碼數量上限變更，或每個電話號碼的對話數量上限變更。

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