WhatsApp 账户和电话号码 Webhook 示例

如需查看基于架构生成的完整目录，请参阅所有示例。

功能介绍

处理商业账户审核、更新和删除事件，以及电话号码删除、显示名称审核、质量和商业用户名更新。根据各有效载荷的确切事件 type 进行路由：账户事件使用 whatsappBusinessAccount，而电话号码事件使用 whatsappPhoneNumber。

准备工作

在您的应用程序中创建一个公共 HTTPS 端点。
为您需要的事件类型配置 YCloud Webhook 端点。
安全存储端点签名密钥。
使事件处理具备幂等性。

工作原理

当事件发生时，YCloud 会发送 HTTP POST 请求。验证签名，持久记录该事件，返回 2xx 响应，并异步处理耗时任务。

请求

以下场景展示了发送到您的 Webhook URL 的请求。将事件 id 视为投递标识符，并使用 type 路由有效载荷。

响应

接收事件后返回 2xx 状态。

HTTP/1.1 200 OK

有关端点设置、签名验证和重试行为，请参阅配置 Webhook。

账户删除

使用 whatsapp.business_account.deleted 处理 WhatsApp 商业账户删除事件。读取 whatsappBusinessAccount.id 以识别受影响的 WABA。

请求

{
  "id": "evt_business_account_deleted_123",
  "type": "whatsapp.business_account.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "removedReason": "ACCOUNT_DISCONNECTED",
    "removedInitiatedBy": "USER",
    "removedTime": "2026-05-26T12:00:00.000Z"
  }
}

响应

持久接收事件后确认投递。

HTTP/1.1 200 OK

说明

删除字段在可用时直接显示在 whatsappBusinessAccount 内。

字段	含义
`id`	受影响的 WhatsApp 商业账户 ID。
`removedReason`	原始删除原因。请参阅下方的已知值。
`removedInitiatedBy`	由 WhatsApp 用户发起的删除为 `USER`，由 Meta 发起的删除为 `SYSTEM`。
`removedTime`	YCloud 接收到删除事件的时间，采用 RFC 3339 格式。

已知的 removedReason 值包括：

值	含义
`ACCOUNT_DISCONNECTED`	账户因违规处置断开连接，或因为 WhatsApp 账户被显式删除。
`BUSINESS_DOWNGRADE`	电话号码已在个人版 WhatsApp 应用中注册。
`CHANGE_NUMBER`	WhatsApp 电话号码已更改。
`COMPANION_INACTIVITY`	配套设备处于非活动状态约 30 天。
`PRIMARY_INACTIVITY`	主设备处于非活动状态约 30 天。
`USER_RE_REGISTERED`	WhatsApp 已在新设备上重新注册。

保留未知的原因和发起方值。按事件 id 对投递进行去重，并容忍缺失的删除字段。

Authentication-International 费率资格

自 2024 年 6 月 1 日起，我们将引入新的 authentication-international 费率。此费率将适用于以下国家/地区：

2024 年 6 月 1 日 – 印度尼西亚（国家呼叫代码 +62，国家/地区代码 ID）
2024 年 7 月 1 日 – 印度（国家呼叫代码 +91，国家/地区代码 IN）

有关详细信息，请参阅 Authentication-International Rate Eligibility。如果您的企业被视为符合国际费率资格，将触发 whatsapp.business_account.updated Webhook。该 Webhook 将包含实行 authentication-international 费率的每个国家/地区的开始时间。

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

响应

持久接收事件后确认投递。

HTTP/1.1 200 OK

如果消息按 authentication-international 费率计费，whatsapp.message.updated Webhook 中的 whatsappMessage.pricingCategory 将设置为 authentication_international。示例如下：

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或容易失败的任务移至异步处理器。

主要营业地点更新

您的主要营业地点是您企业所在的国家/地区。自 2024 年 5 月 1 日起，它将显示在商务管理平台（Business Manager）中的“主要营业地点”（Primary Business Location）字段下。如果 Meta 能够确定您的企业所在的国家/地区，我们将触发包含该国家/地区两位代码的 whatsapp.business_account.updated Webhook。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

响应

持久接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或容易失败的任务移至异步处理器。

电话号码注册上限更新

当对应的业务资产组合（Business Portfolio）或 WABA 电话号码注册上限发生变更时，Meta 会为该 WABA 发送业务功能更新。YCloud 将其作为带有 updateEvent=BUSINESS_CAPABILITY_UPDATE 的 whatsapp.business_account.updated 投递。该 Webhook 属于 WABA 级别：whatsappBusinessAccount.id 是来自 Meta Webhook 条目的 WABA ID。Meta 当前在不同的更新中分别报告 maxPhoneNumbersPerBusiness 和 maxPhoneNumbersPerWaba。请勿将它们视为互斥项：应独立处理每个字段，并且如果将来的更新同时包含这两个字段，应一并接受。值为 0 是有效的。以下是 WABA 电话号码数量上限更新的示例：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

按 type 路由事件，按 id 去重，并仅更新有效载荷中包含的上限字段。

账户违规

当您收到 whatsappBusinessAccount.updateEvent 设置为 ACCOUNT_VIOLATION 的 whatsapp.business_account.updated 事件时，检查 whatsappBusinessAccount.violationType 以识别所报告的政策违规行为。有关违规类型和说明，请参阅 Meta 的政策执行违规行为。Meta 可能会随着时间推移更新此列表。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SCAM"
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

按 type 路由事件，按 id 去重，并将耗时较长或易失败的工作转移到异步处理器。

账户限制

如果商业账户反复违反 WhatsApp 商业服务条款或高风险政策类别（例如发送垃圾消息、成人内容、销售烟酒、毒品、赌博和不安全补充剂），其可能会开始受到消息发送限制，且限制持续时间会逐渐增加。关于服务类直接发送（Utility Direct Send），请参阅 Direct Send 通知获取 YCloud ACCOUNT_RESTRICTION 有效载荷。有关 Direct Send 特定的违规类型和限制详情，请参阅 Meta 的账户限制 Webhook。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      }
    ]
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

按 type 路由事件，按 id 去重，并将耗时较长或易失败的工作转移到异步处理器。

服务类直接发送限制

当 Meta 因屡次误用类别而限制服务类直接发送（Utility Direct Send）时，您会收到 whatsapp.business_account.updated。此示例展示了一个为期七天的限制。

请求

{
  "id": "evt_direct_send_restriction_123",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
        "expiration": "2026-09-24T08:00:00.000Z"
      }
    ]
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

使用 whatsappBusinessAccount.id 识别受影响的 WABA 并暂停其服务类直接发送（Utility Direct Send）工作流。读取 violationType 获取原因，读取 restrictions[].restrictionType 获取受影响的功能，若提供 restrictions[].expiration 则读取该字段获取到期时间。单个模板审核通过不会自动解除账户级别的限制。请参阅 Direct Send 限制与通知。

账户停用

如果商家在多次收到警告以及功能受限或被封禁后仍不进行整改，WhatsApp 商业账户可能会被停用。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

按 type 路由事件，按 id 去重，并将耗时较长或易失败的工作转移到异步处理器。

账户恢复

您可以对 WhatsApp 商业账户封禁决定提出申诉以恢复账户。申诉获得批准后，账户审核状态将变为 APPROVED。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

按 type 路由事件，按 id 去重，并将耗时较长或易失败的工作转移到异步处理器。

商业账户审核

在 WhatsApp 商业账户完成审核时使用 whatsapp.business_account.reviewed。

请求

{
  "id": "evt_example_whatsapp_business_account_reviewed",
  "type": "whatsapp.business_account.reviewed",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "decision": "APPROVED",
    "accountReviewStatus": "APPROVED"
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

通过 id 识别 WABA。读取 decision 获取审核决定（APPROVED 或 REJECTED），若提供 accountReviewStatus 则读取该字段获取账户审核状态。请勿将此事件路由为 whatsapp.business_account.updated。

电话号码删除

在 WhatsApp 商业电话号码被删除时使用 whatsapp.phone_number.deleted。

请求

{
  "id": "evt_example_whatsapp_phone_number_deleted",
  "type": "whatsapp.phone_number.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id"
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

使用 whatsappPhoneNumber.id 识别已删除的电话号码，并使用 wabaId 将其与其账户关联。这是一个电话号码事件；请勿将其视为删除整个 WABA。

电话号码显示名称审核

当商业电话号码显示名称获得批准或被拒绝时使用 whatsapp.phone_number.name_updated。

请求

{
  "id": "evt_example_whatsapp_phone_number_name_updated",
  "type": "whatsapp.phone_number.name_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id",
    "verifiedName": "Example business",
    "requestedVerifiedName": "Example business",
    "decision": "APPROVED",
    "nameStatus": "APPROVED",
    "newNameStatus": "APPROVED"
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

读取 decision 及所提供的名称状态字段。newNameStatus 说明新的显示名称申请，requestedVerifiedName 标识上次申请的名称，存在拒绝情况时 rejectionReason 用于说明拒绝原因。显示名称审核与商业用户名（Business Username）更新是相互独立的。

电话号码质量更新

当商业电话号码的质量相关状态发生变更时使用 whatsapp.phone_number.quality_updated。

请求

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

响应

在持久化接收事件后再确认送达。

HTTP/1.1 200 OK

说明

读取 qualityRating（GREEN、YELLOW 或 RED）和 qualityUpdateEvent 以了解更新。messagingLimit 是电话号码层级；whatsappBusinessManagerMessagingLimit 是所属商业资产组合的限制。请区分这些字段，并仅更新事件中提供的值。

商业用户名已激活

使用 whatsapp.phone_number.business_username_updated 同步电话号码的商业用户名。

请求

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

businessUsername 是不带前导 @ 的有效用户名。请结合电话号码 id 一起读取 businessUsernameStatus 和 businessUsernameUpdatedAt。请勿将该值与已验证的显示名称混淆。

商业用户名请求已预留

在预留更换请求期间，当前处于活动状态的商业用户名可继续使用。

请求

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

在此示例中，businessUsername 仍为 acme.support，而 requestedBusinessUsername 为 acme.help。reserved 状态描述的是待处理的请求，而不是更换名称的激活。读取较旧的事件时可接收旧版 pending_review 值；新写入则使用 reserved。

​功能介绍

​准备工作

​工作原理

​请求

​响应

​账户删除

​请求

​响应

​说明

​Authentication-International 费率资格

​请求

​响应

​说明

​主要营业地点更新

​请求

​响应

​说明

​电话号码注册上限更新

​请求

​响应

​说明

​账户违规

​请求

​响应

​说明

​账户限制

​请求

​响应

​说明

​服务类直接发送限制

​请求

​响应

​说明

​账户停用

​请求

​响应

​说明

​账户恢复

​请求

​响应

​说明

​商业账户审核

​请求

​响应

​说明

​电话号码删除

​请求

​响应

​说明

​电话号码显示名称审核

​请求

​响应

​说明

​电话号码质量更新

​请求

​响应

​说明

​商业用户名已激活

​请求

​响应

​说明

​商业用户名请求已预留

​请求

​响应

​说明

功能介绍

准备工作

工作原理

请求

响应

账户删除

请求

响应

说明

Authentication-International 费率资格

请求

响应

说明

主要营业地点更新

请求

响应

说明

电话号码注册上限更新

请求

响应

说明

账户违规

请求

响应

说明

账户限制

请求

响应

说明

服务类直接发送限制

请求

响应

说明

账户停用

请求

响应

说明

账户恢复

请求

响应

说明

商业账户审核

请求

响应

说明

电话号码删除

请求

响应

说明

电话号码显示名称审核

请求

响应

说明

电话号码质量更新

请求

响应

说明

商业用户名已激活

请求

响应

说明

商业用户名请求已预留

请求

响应

说明