管理 WhatsApp 模板

​

概述

​

准备工作

• 连接将拥有该模板的 WABA。
• 选择模板类别、支持的语言、名称和组件。
• 准备审核所需的代表性变量和媒体示例。
• 遵守 Meta 针对身份验证、公共事业和营销内容的政策。
• 配置一个能够接收 whatsapp.template.reviewed 事件的 Webhook 终端节点。

​

工作原理

1. 在 WABA 中创建模板。
2. 存储其名称、语言、类别以及当前的 status。
3. 在需要审核时等待批准。
4. 检索或列出模板以观察状态变更。
5. 仅发送适用于目标用例且处于可发送状态的模板。
6. 当模板内容或生命周期发生变更时，编辑或删除模板。

​

请求

curl --request POST https://api.ycloud.com/v2/whatsapp/templates \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "wabaId": "WABA_ID",
    "name": "order_ready",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Order {{0}} is ready for pickup.",
        "example": {
          "body_text": [["A-10001"]]
        }
      }
    ]
  }'

​

响应

{
  "wabaId": "WABA_ID",
  "name": "order_ready",
  "language": "en_US",
  "category": "UTILITY",
  "status": "PENDING",
  "components": [
    {
      "type": "BODY",
      "text": "Order {{0}} is ready for pickup."
    }
  ]
}

​

定义稳定的资产标识

• auth_login_otp_v1
• orders_pickup_ready_v2
• growth_summer_offer_v3

​

在编写内容前选择类别

​

冻结变量约定

• 为正文或文本标头的每个变量提供安全、具有代表性的示例。
• 验证媒体标头 URL、格式和文件大小。
• 将文本标头限制为最多一个变量，并包含其示例。
• 确认 URL 按钮变量仅出现在 API 允许的位置，并包含完整的示例 URL。
• 切勿在审核示例中使用凭据、一次性验证码、个人数据或私密媒体。

​

将各语言区域组织为单次发布

​

根据模板状态控制发送

​

同步状态

1. 验证每个 whatsapp.template.reviewed 事件的签名。
2. 通过事件 id 对交付进行去重。
3. 通过 wabaId、name 和 language 解析资产。
4. 同时存储更新事件和当前 status。
5. 当当前状态不是 APPROVED 时立即停止路由。
6. 当事件丢失、延迟或与更新的注册表状态冲突时，检索模板。
7. 运行计划的分页列表对账以检测偏差。

​

编辑与删除行为

• 仅编辑处于端点支持状态的模板。
• 在编辑请求中包含所需的完整组件集。
• 按名称删除会移除该名称下的所有语言版本。
• 按名称和语言删除仅移除该本地化模板。
• 归档的模板仍可能出现在列表和检索结果中。

​

发布、回滚和停用版本

1. 为每个所需语言区域创建带版本的新名称。保持当前已批准的版本不变。
2. 等待每个目标语言区域变为 APPROVED，然后验证其变量、媒体、按钮、类别和渲染内容。
3. 将受控比例的符合条件发送路由到新版本，并监控交付率、质量、回复和状态更新。
4. 仅在新版本符合发布标准后，再迁移剩余流量。

​

限制与问题排查

• 当消息模板未获批准或其组件与消息参数不匹配时，发送请求将失败。
• 身份验证模板使用受限的预设结构。
• 模板类别和内容必须符合 Meta 政策。
• 在重新创建相同内容之前，请查看拒绝详情。
• 当已删除或发生重大变更的模板无法安全恢复时，请使用新名称。

​

上线清单

• 已记录名称、用途、所有者、类别和版本。
• 每个变量都有明确的含义、格式、安全示例和回退规则。
• 媒体和按钮通过格式、目标和示例检查。
• 每个所需的语言区域均已独立 APPROVED。
• 发送路径会拒绝除 APPROVED 之外的所有状态。
• Webhook 处理已验证、具备幂等性，并与检索对账。
• 发布方案能够恢复到先前已批准的版本。
• 队列、营销活动、配置、测试和运维手册均使用目标版本。