WhatsApp Business 管理 API

Webhooks 组件

Webhooks 有一个顶层数组字段，用以指明正在传递的内容。数组由 JSON 对象组成，其中包括与 Webhooks 相关的详细字段。

WhatsApp Business 管理 API Webhooks 包含以下对象：

参数描述

object

此为订阅对象。


对于嵌入式注册，此对象始终是 whatsapp_business_account。

entry

此对象包含触发 Webhooks 调用的更改的详细信息。

entry 对象

参数描述

id

相应 Webhooks 所属的 WhatsApp Business 商业帐号的编号。

time

entry 对象的创建时间。

changes

触发相应 Webhooks 调用的更改，详情请参阅 changes 对象。

changes

参数描述（点击左列中的箭头以获取支持的值。）

field

包含您将通过相应 Webhooks 接收的通知类型。

支持的值

  • account_alerts
  • account_review_update
  • account_update
  • business_capability_update
  • message_template_quality_update
  • message_template_status_update
  • phone_number_name_update
  • phone_number_quality_update
  • security
  • template_category_update

value

包含与指定 field 相关的更改的详细信息，详情请参阅 value 对象。

value

参数描述（点击左列中的箭头以获取支持的值。）

ban_info

帐号已被封号时添加到 Webhooks。该对象包含 2 个属性：

  • waba_ban_state：选项包括：
    • DISABLE
    • REINSTATE
    • SCHEDULE_FOR_DISABLE
  • waba_ban_date

current_limit

包含相应账户当前所处级别的限制。

支持的值

  • TIER_50
  • TIER_250
  • TIER_1K
  • TIER_10K
  • TIER_100K
  • TIER_UNLIMITED

decision

在已做出有关帐号或电话号码的决定时使用。

支持的值

  • APPROVED
  • REJECTED

display_phone_number

包括触发相应通知的商业帐号的显示电话号码。

event

事件在特定 WABA 中发生时使用。点击左列中的箭头即可查看所有可用选项。

显示名更新

  • APPROVED：已通过审核。如果企业之前无法下载证书，则现在应该能够通过下载证书使用其显示名。
  • DEFERRED：审核已推迟，企业可通过下载证书使用其显示名。
  • REJECTED：未通过审核，并给出未通过原因。如果企业之前无法下载证书，则需要重新申请显示名审核，才能获取证书。如果企业已在使用证书，则未通过显示名审核不会影响到其运作。但是，企业需要通过显示名审核才能提升消息数量上限和帐号限制级别。

消息模板质量更新

之前的质量评分：


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

新的质量评分：


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

消息模板状态更新

  • APPROVED
  • DISABLED
  • IN_APPEAL
  • PENDING
  • REINSTATED
  • REJECTED
  • FLAGGED

电话号码更新

  • DOWNGRADE
  • FLAGGED
  • ONBOARDING
  • UNFLAGGED
  • UPGRADE

模板类别更新

之前的类别：


  • MARKETING
  • OTP
  • TRANSACTIONAL

新的类别：


  • AUTHENTICATION
  • MARKETING
  • UTILITY

两步验证码

  • PIN_CHANGED: 两步验证码已更新（仅限云端 API）
  • PIN_RESET_REQUEST: 请求禁用两步验证码
  • PIN_RESET_SUCCESS: 两步验证码已禁用

WABA 更新

  • ACCOUNT_RESTRICTION：在 WABA 违反 WhatsApp Business 开放平台政策时，用于报告已对该帐号施加限制。
  • DISABLED_UPDATE
  • VERIFIED_ACCOUNT

max_daily_conversation_per_phone

field=business_capability_update 时固定显示。


表示您可以使用您 WhatsApp Business 商业帐号中显示名已获批的每个公司电话号码发送的模板消息数量。请参阅发消息限制。

max_phone_numbers_per_business

包括一个企业可拥有的电话号码数量上限。


field=business_capability_update 时，Webhooks 将显示 max_phone_numbers_per_business 或 max_phone_numbers_per_waba。

max_phone_numbers_per_waba

包括一个 WABA 可拥有的电话号码数量上限。


field=business_capability_update 时，Webhooks 将显示 max_phone_numbers_per_business 或 max_phone_numbers_per_waba。

reason

模板被拒原因。可能的值：


  • ABUSIVE_CONTENT — 经判定，内容违规。
  • INCORRECT_CATEGORY — 经判定，类别有误。请参阅模板类别。
  • INVALID_FORMAT — 内容重复或示例缺失。
  • NONE — 模板获批时设置的默认值。
  • SCAM — 经判定，内容为诈骗。

rejection_reason

如果请求未通过，则此字段显示未通过的原因。

requested_verified_name

此字段显示发送以供认证的名称。

restriction_info

枚举

在特定 WhatsApp Business 商业帐号违反 WhatsApp Business 开放平台政策时，用于报告对该 WhatsApp Business 商业帐号施加的限制。


此字段包括限制类型列表及其相应的到期日期。可能的限制类型包括：


  • RESTRICTED_ADD_PHONE_NUMBER_ACTION
  • RESTRICTED_BIZ_INITIATED_MESSAGING
  • RESTRICTED_CUSTOMER_INITIATED_MESSAGING

到期日期以 DateTime 格式提供。

requester

请求禁用，或者已禁用或更新两步验证码的用户的编号。

示例

消息模板状态更新

模板获批

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "APPROVED",
              "message_template_id": 1234567, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null 
         }
       }
      ]
    }
  ]
}

模板被拒

{
  "object": "whatsapp_business_account"
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "REJECTED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "<REJECTION_REASON>"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ]
}

已计划禁用模板

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "FLAGGED",
              "message_template_id": TEMPLATE-ID, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null,
              "disable_info": {
                  "disable_date": "DATE",
              }
         }
       }
      ]
    }
  ]
}

模板已暂停

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10908...",
      "time": 1661885238,
      "changes": [
        {
          "value": {
            "event": "PAUSED",
            "message_template_id": 6048...,
            "message_template_name": "welcome",
            "message_template_language": "en_US",
            "reason": "NONE",
            "other_info": {
              "title": "SECOND_PAUSE",
              "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

模板消息正在等待删除

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10310...",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "PENDING_DELETION",
            "message_template_id": 1137...,
            "message_template_name": "<MY_TEMPLATE_NAME>",
            "message_template_language": "en_US",
            "reason": "NONE"            
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

模板类别更新

模板类别已更改

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<ID>",
      "time": <TIME>,
      "changes": [
        {
          "field": "template_category_update",
          "value": {            
            "message_template_id": <MESSAGE_TEMPLATE_ID>,
            "message_template_name": "<MESSAGE_TEMPLATE_NAME>",
            "message_template_language": "<MESSAGE_TEMPLATE_LANGUAGE",
            "previous_category": "<PREVIOUS_CATEGORY>",
            "new_category": "<NEW_CATEGORY>"
          }
        }
      ]
    }
  ]
}

消息模板质量更新

模板质量评分已更改

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "field": "message_template_quality_update",
          "value": {
            "previous_quality_score": "<PREVIOUS_QUALITY_SCORE>",
            "new_quality_score": "<NEW_QUALITY_SCORE>",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>"
          }
        }
      ]
    }
  ]
}

电话号码更新

已收到名称更新

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

已收到质量更新

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243062,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "16505551111",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

WABA 更新

沙盒号码已升级到已认证的帐号

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505551111",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

WhatsApp Business 商业帐号已被封号

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "January 31, 2021"
            }
          }
        }
      ]
    }
  ]
}

WhatsApp Business 商业帐号违反政策

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "VIOLATION_TYPE"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 商业帐号在违反政策后已受限

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
               {"restriction_type": 
                 "RESTRICTED_BIZ_INITIATED_MESSAGING" | 
                 "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION" | 
                 "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", 
                 "expiration": TIMESTAMP}
                 ]
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 商业帐号已禁用

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "DISABLED_UPDATE",
            "ban_info": {
              "waba_ban_state": 
               "SCHEDULE_FOR_DISABLE" | 
               "DISABLE" | 
               "REINSTATE",
               "waba_ban_date": TIMESTAMP
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 商业帐号审核已完成

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

WhatsApp Business 商业帐号因违反政策而受限

{
  "field": "account_update",
  "value": {
    "phone_number": "PHONE_NUMBER",
    "event": "ACCOUNT_RESTRICTION",
    "restriction_info": [
      {
        "restriction_type": "RESTRICTION_ADD_PHONE_NUMBER_ACTION",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      }
    ]
  }
}

WhatsApp Business 商业帐号已被删除

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "ACCOUNT_DELETED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 商业帐号已从合作伙伴处移除

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "PARTNER_REMOVED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

企业功能更新

{
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
        "time": TIMESTAMP,
        "changes": [
          {
            "field": "business_capability_update",
            "value": {
              "max_daily_conversation_per_phone": NUMBER,
              "max_phone_numbers_per_business": NUMBER
            }
          }
        ]
      }
    ]
  }

帐号提醒

提高发消息数量上限的请求被拒绝

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "CRITICAL",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_FAILED",
            "alert_description": "Based on your activity, limits cannot be increased for your business <BUSINES_NAME>. Contact support for more information."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

提高发消息数量上限的请求被拒绝，需要提供更多使用情况

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
            "alert_description": "Limits cannot be increased for your business <BUSINES_NAME>. Use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

提高发消息数量上限的请求被拒绝，需要提供更多信息

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO",
            "alert_description": "Additional verification is required for your business <BUSINESS_NAME>. Go to Security Center in Meta for Business to complete identity verification. To continue without completing additional verification, your business can use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}