whatsapp.template.reviewed

在您的 Webhook 端点中使用 whatsapp.template.reviewed 来处理此事件。

触发条件

当 WhatsApp 消息模板收到审核或生命周期更新（包括批准、拒绝、暂停、禁用、归档和取消归档）时触发。在您配置 Webhook 端点时订阅 whatsapp.template.reviewed。使用 wabaId、name 和 language 识别该模板。statusUpdateEvent 描述触发该事件的变更；status 描述当前状态。例如，UNARCHIVED 可以携带 status: APPROVED，而无需经过新的审批审核。

语法

YCloud 会向您配置的 Webhook URL 发送 HTTP POST 请求。以下结构展示了一种负载变体。尖括号内的值为占位符；其类型列于参数下。可选字段和其他变体详见下文。

{
  "id": "<ID>",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappTemplate": {
    "officialTemplateId": "<OFFICIAL_TEMPLATE_ID>",
    "wabaId": "<WABA_ID>",
    "name": "<NAME>",
    "language": "<LANGUAGE>",
    "category": "<CATEGORY>",
    "status": "<STATUS>",
    "statusUpdateEvent": "<STATUS_UPDATE_EVENT>",
    "createTime": "<CREATE_TIME>",
    "updateTime": "<UPDATE_TIME>"
  }
}

参数

在处理 JSON 请求体之前，请验证 YCloud-Signature HTTP 请求头。参见签名验证。

事件外层封装

参数	类型	必填	描述
`id`	string	是	事件的唯一 ID。最小长度：`6`。最大长度：`128`。
`type`	string	是	固定为 `whatsapp.template.reviewed`。
`apiVersion`	string	是	用于呈现此事件的 API 版本。
`createTime`	string (date-time)	是	创建此事件的时间，按 RFC 3339 格式化。例如 `2022-06-01T12:00:00.000Z`。

事件负载

参数	类型	必填	描述
`whatsappTemplate`	object	否	事件专属的 `whatsappTemplate` 负载。

四个通用外层封装字段为必填项。负载字段取决于具体的事件变体。在每个对象表中，必填仅在其父对象存在时适用。可选字段可以省略；示例中出现并不意味着该字段是必填的。

whatsappTemplate

参数	类型	必填	描述
`officialTemplateId`	string	否	由 WhatsApp 分配的官方模板 ID。此 ID 用于在 WhatsApp 系统中标识该模板。
`wabaId`	string	是	WhatsApp 商业账户 ID。
`name`	string	是	模板名称。最大长度：`512`。模式：`[a-z0-9]{1,512}`。
`language`	string	是	模板的语言代码。所有代码请参见支持的语言。
`category`	string	否	WhatsApp 模板类别。 `AUTHENTICATION`：使企业能够使用一次性密码对用户进行身份验证，可能涉及登录流程中的多个步骤（例如账户验证、账户找回、安全挑战）。 `MARKETING`：包括促销或优惠、资讯更新，或邀请客户回应/采取行动。任何不属于效用或身份验证的对话均属于营销对话。 `UTILITY`：促成特定的、双方同意的请求或交易，或向客户更新有关进行中交易的信息，包括购买后通知和定期账单明细。
`status`	string	否	WhatsApp 消息模板的状态。 `PENDING`：模板仍在审核中。审核最多可能需要 24 小时。 `REJECTED`：模板在审核过程中被拒绝。 `APPROVED`：模板已获批准，你可以开始向客户发送该模板。 `PAUSED`：由于客户反复给出负面反馈，该模板已被暂停。处于此状态的消息模板无法发送给客户。参见模板暂停。 `DISABLED`：由于客户反复给出负面反馈或违反了一项或多项政策，该模板已被停用。处于此状态的消息模板无法发送给客户。你可以编辑已被停用的消息模板并申请申诉。参见申诉。 `ARCHIVED`：模板已被归档。归档的模板无法发送或编辑。 `IN_APPEAL`：模板正在申诉中。另请参见模板申诉。 `DELETED`：模板已被删除。
`reason`	string	否	模板被拒绝的原因。
`createTime`	string (date-time)	否	创建此对象的时间，格式遵循 RFC 3339。例如 `2022-06-01T12:00:00.000Z`。
`updateTime`	string (date-time)	否	更新此对象的时间，格式遵循 RFC 3339。例如 `2022-06-01T12:00:00.000Z`。
`statusUpdateEvent`	string	否	触发此 Webhook 的 WhatsApp 模板状态更新事件。对于 `ARCHIVED`，模板 `status` 为 `ARCHIVED`。对于 `UNARCHIVED`，模板 `status` 为 Meta 返回的当前状态，例如 `APPROVED`；这并不代表重新进行了审核批准。可用值：`PENDING`、`APPROVED`、`REJECTED`、`IN_APPEAL`、`PAUSED`、`FLAGGED`、`DISABLED`、`ARCHIVED`、`UNARCHIVED`、`REINSTATED`、`PENDING_DELETION`。
`disableDate`	string	否	模板被停用的日期。当收到 WhatsApp 模板 `FLAGGED` 事件时，会设置此字段。
`whatsappApiError`	object	否	WhatsApp 返回的原始错误对象。参见错误处理、Cloud API 错误代码。

whatsappTemplate.whatsappApiError

参数	类型	必填	说明
`message`	string	是	人类可读的错误描述。
`code`	string	是	错误代码。
`type`	string	否	错误类型。
`error_subcode`	string	否	关于错误的附加代码。
`error_user_msg`	string	否	向用户显示的消息。消息的语言取决于 API 请求的语言区域（locale）。
`error_user_title`	string	否	对话框标题（若显示）。消息的语言取决于 API 请求的语言区域（locale）。
`fbtrace_id`	string	否	内部支持标识符。报告与 Graph API 调用相关的错误时，请附上 fbtrace_id，以帮助我们查找用于调试的日志数据。
`error_data`	字符串或对象	否	关于错误的附加数据。字符串或映射（map）。对于模板 API，此字段为描述错误原因的字符串。对于消息 API，此字段为包含属性 `details` 的映射（map），用于描述错误原因。

示例

以下 JSON 是发送至接收端的请求体。ID、电话号码和其他账户值仅用于说明。

WhatsApp 模板归档事件

WhatsApp 模板归档时的示例有效负载

{
  "id": "evt_template_archived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "statusUpdateEvent": "ARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

WhatsApp 模板取消归档事件

WhatsApp 模板取消归档时的示例有效负载。模板状态是 Meta 返回的当前状态，并不代表进行了新的审批审核。

{
  "id": "evt_template_unarchived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "statusUpdateEvent": "UNARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

模板已批准

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "NONE",
    "statusUpdateEvent": "APPROVED"
  }
}

模板已拒绝

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "REJECTED",
    "reason": "SCAM",
    "statusUpdateEvent": "REJECTED"
  }
}

模板已暂停

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "PAUSED",
    "reason": "NONE",
    "statusUpdateEvent": "PAUSED"
  }
}

模板已被标记

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "Your WhatsApp message template has been paused for 3 hours until Feb 23 at 5:28 AM UTC because it had issues.",
    "statusUpdateEvent": "FLAGGED",
    "disableDate": "February 28, 2023"
  }
}

模板已禁用

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "DISABLED",
    "reason": "NONE",
    "statusUpdateEvent": "DISABLED"
  }
}

模板待删除

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "DELETED",
    "reason": "NONE",
    "statusUpdateEvent": "PENDING_DELETION"
  }
}

模板已归档

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "reason": "NONE",
    "statusUpdateEvent": "ARCHIVED"
  }
}

模板已取消归档

{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "NONE",
    "statusUpdateEvent": "UNARCHIVED"
  }
}

验证签名并持久接收事件后，返回 2xx 响应。耗时任务请异步处理。

HTTP/1.1 200 OK

有关场景演练，请参阅带批注的示例。

开始使用

指南

接口

Webhook reference

whatsapp.template.reviewed

触发条件

语法

参数

事件外层封装

事件负载

whatsappTemplate

示例

​触发条件

​语法

​参数

​事件外层封装

​事件负载

​whatsappTemplate

​示例

触发条件

语法

参数

事件外层封装

事件负载

whatsappTemplate

示例