waba-template-author

WhatsApp 模板编写指南

使用此技能将消息意图转化为适用于 POST /v3/templates 的有效正文，检查其是否存在违反 WhatsApp 政策的风险，并说明由此产生的生命周期。Sent 的模板请求格式并非 Meta Cloud API 的 components[] 格式。

来源优先级

官方来源存在冲突时：

1. 路径、请求字段和响应格式以 Sent v3 OpenAPI 为准。
2. 生命周期和政策语义以最具体的现行 Sent 指南为准。
3. 保留未知的提供方取值，不要强行归入封闭枚举。

权威参考资料包括 Sent 模板定义指南、v3 OpenAPI 和 webhook 事件参考。不要使用快照时期的 v2 示例。

编写工作流

1. 明确意图和类别

收集业务事件、收件人预期、所需操作、语言、渠道覆盖项和实际示例值。选择：

• UTILITY：用于特定的非促销类交易、账户或服务事件。
• MARKETING：用于促销、优惠、重新互动、产品发现或混合促销内容。
• AUTHENTICATION：用于一次性验证码和受支持的身份验证流程。

如果内容同时包含实用信息和促销内容，应归类为营销类，或拆分内容。请参阅 references/waba-template-categories.md。

2. 构建 Sent 创建请求

POST /v3/templates 接受以下顶层字段：

字段	要求
definition	必填。包含 header、body、footer、buttons，以及可选的 definitionVersion 和 authenticationConfig。
category	可选：UTILITY、MARKETING 或 AUTHENTICATION；仅在可以接受类别不确定时才省略以进行检测。
language	可选的区域设置，例如 en_US。
creation_source	可选的来源字符串；文档规定的默认值为 from-api。
submit_for_review	可选的布尔值；默认值为 false。提交审核前先保存草稿并进行验证。
sandbox	可选的布尔值，用于无副作用地进行验证。

不要将 name、channels、body、header、buttons 或 components 放在请求根级别。name 存在于更新和响应接口中，但不属于当前创建请求。

{
  "category": "UTILITY",
  "language": "en_US",
  "definition": {
    "header": null,
    "body": {
      "multiChannel": {
        "type": "body",
        "template": "Hi {{0:variable}}, order {{1:variable}} has shipped.",
        "variables": [
          {
            "id": 0,
            "name": "customerName",
            "type": "variable",
            "props": {"sample": "Avery"}
          },
          {
            "id": 1,
            "name": "orderNumber",
            "type": "variable",
            "props": {"sample": "A-1042"}
          }
        ]
      },
      "sms": null,
      "whatsapp": null,
      "rcs": null
    },
    "footer": null,
    "buttons": null,
    "definitionVersion": "1.0",
    "authenticationConfig": null
  },
  "creation_source": "from-api",
  "submit_for_review": false,
  "sandbox": true
}

使用 definition.body.multiChannel 作为不特定渠道的正文。sms、whatsapp 和 rcs 是完整的渠道覆盖项，而非片段。每个正文长度不得超过 1,024 个字符。

3. 准确定义变量

使用 {{0:variable}}、{{1:link}} 或 {{2:media}} 等占位符。每个占位符都需要一个匹配的定义，其中包含：

• 唯一的非负整数 id；
• 易读的 name；
• 匹配的 type；
• 包含实际审核和预览数据的 props.sample。

确保每个正文覆盖项中的占位符 ID 与变量 ID 保持一致。切勿在 Sent 请求中输出没有定义的 {{1}} 占位符。

4. 添加受支持的按钮

Sent 当前支持 QUICK_REPLY、URL、VOICE_CALL、PHONE_NUMBER 和 COPY_CODE。请遵守以下限制：

• 按钮总数最多为 10 个；
• URL 按钮最多为 2 个；
• 语音通话按钮最多为 1 个；
• 电话号码按钮最多为 1 个；
• 复制代码按钮最多为 1 个；
• 快速回复按钮可使用剩余名额，总数不超过 10 个。

按钮使用 id、type 和 props。标签最多为 25 个字符。必须提供特定类型所需的属性：quickReplyType；urlType 和 url；countryCode 和 phoneNumber；或 offerCode。快速回复和行动号召按钮可以同时存在——不要凭空设定互斥规则。

5. 处理身份验证模板

对于 AUTHENTICATION，请使用 definition.authenticationConfig：

{
  "addSecurityRecommendation": true,
  "codeExpirationMinutes": 10
}

有效期为 1–90 分钟。身份验证内容应仅用于验证目的，使用一个验证码变量和受支持的复制代码操作，不得添加营销用语、不相关链接、媒体或促销按钮。

6. 提交前进行验证

运行：

python scripts/lint_waba_template.py template.json

此检查器会验证 Sent 请求的结构、变量、1,024 个字符的限制、渠道覆盖项、当前所有按钮类型、各类型的限制以及身份验证配置。包含 components[] 的 Meta Cloud API 示例必须触发明确的转换错误。

集成期间请使用 sandbox: true 和 submit_for_review: false。当用户准备好提交以供提供商审核时，请先展示最终载荷，并说明提交会更改外部状态，然后再继续。

7. 跟踪正确的生命周期界面

Sent 模板资源使用已知状态：DRAFT、PENDING、APPROVED、REJECTED 和 PAUSED。不要声称这是 API 可能返回的所有值。

模板 Webhook 是 WhatsApp 审批事件。它们使用 field: "templates"，不包含 sub_type 和 event，并在 payload.status 中携带提供商状态：

{
  "field": "templates",
  "timestamp": "2026-08-09T12:00:00Z",
  "payload": {
    "account_id": "00000000-0000-0000-0000-000000000000",
    "template_id": "11111111-1111-1111-1111-111111111111",
    "template_name": "order_update",
    "whatsapp_template_id": "2222222222222222",
    "status": "APPROVED",
    "language": "en_US",
    "category": "UTILITY",
    "channel": "whatsapp",
    "reason": null
  }
}

常见的转发值包括 PENDING、APPROVED、REJECTED 和 CATEGORY_UPDATED。Meta 也可能发送 PAUSED 或 DISABLED 等值。请保留原始字符串，处理已知值，并安全地呈现未知值。请参阅 references/template-rejection-playbook.md。

边界

使用 template-builder-ui 实现编辑器架构和客户端验证体验。使用 sent-templates 通过连接的 Sent 工具列出、检查或删除现有模板。使用 waba-embedded-signup 连接 WABA。使用 rcs-agent-onboarding 了解当前 RCS 发布能力。

references/waba-template-examples.md 中可能会出现 Meta Cloud API 载荷，但每个此类示例都必须明确标注为非 Sent 示例，且绝不能作为有效请求传递给 Sent 检查器。