Meta Webhooks

WhatsApp Business 开放平台

Webhooks for WhatsApp Business Accounts

在 WhatsApp Business 商业帐号 (WABA) 级别订阅后，即可在 WABA 发生变更时收到实时通知。要设置适用于 WABA 的 Webhooks，请按以下步骤操作：

  1. 设置端点并配置 Webhooks。步骤与设置适用于 Facebook 公共主页的 Webhooks 相同。
  2. 在 WABA 下订阅应用。您必须订阅自家企业拥有的应用，与自家企业共享的应用无法接收 Webhooks 通知。
  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