跳转到主要内容

功能简介

WhatsApp 模板是预先批准的消息结构,用于在客服窗口之外发起或继续对话。模板由 WABA、名称和语言唯一确定。 使用本指南来管理 API 生命周期,并保持跨团队、版本和语言区域的生产模板资产的稳定性。

准备工作

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

工作原理

  1. 在 WABA 中创建模板。
  2. 保存其名称、语言、类别以及当前的 status。
  3. 当需要审核时,等待审批通过。
  4. 检索或列出模板以观察状态变化。
  5. 仅发送适用于目标用例且处于可发送状态的模板。
  6. 当内容或生命周期发生变化时,编辑或删除模板。
编辑会替换现有的模板内容。请包含在编辑后必须保留的所有组件。 对于 MARKETING 模板,您可以通过 bidSpec 添加或更新最高限价(Max Price)。编辑时,省略 bidSpec 或发送 null 可保留定价,发送 {} 则可清除定价。有关金额、国家/地区乘数和完整编辑示例,请参阅 最高限价集成指南。

请求

POST /whatsapp/templates
模板名称应作为稳定的应用程序标识符。仅在所选组件支持的位置使用变量。

响应

响应确认模板创建及其当前状态。PENDING 并不意味着模板已可以发送。

定义稳定的资产标识

将每个 WABA、模板名称和语言的组合视为一个独立的资产。维护一个资产登记表,其中包含所属的 wabaId、稳定名称、确切的语言区域代码、用途、负责人、变量约定、当前 API 状态、发布状态以及替换版本。 使用可预测的名称,例如 <domain>_<purpose>_v<major>:
  • auth_login_otp_v1
  • orders_pickup_ready_v2
  • growth_summer_offer_v3
当更改影响变量位置、组件类型、按钮、类别或消息含义时,递增主版本号。保持名称独立于团队名称和日期。

在编写内容前选择类别

根据客户接收消息的原因来选择类别。 如果模板将交易信息与促销内容混合在一起,请将其设计为营销类别,或将不同用途拆分为独立的模板。

锁定变量约定

在文案人员或翻译人员开始工作前,将变量定义为 API 约定。对于每个变量,记录其位置、语义含义、格式、来源、代表性示例和回退机制。 例如,Order {{0}} is ready at {{1}}. 可以使用以下约定: 保持每个位置的含义在不同版本和语言区域中保持稳定。如果需要对变量重新排序或改变用途,请创建一个新版本。 提交审核前:
  • 为正文或文本标头的每个变量提供安全且具代表性的样本。
  • 验证媒体标头的 URL、格式和文件大小。
  • 文本标头最多保留一个变量,并附带其样本。
  • 确认 URL 按钮变量仅出现在 API 允许的位置,并提供完整的示例 URL。
  • 切勿在审核示例中使用凭据、一次性验证码、个人数据或私密媒体。

将各语言区域作为一个发布版本进行组织

在一个发布版本中,对所有语言区域复用相同的带版本名称,但将每个 name 和 language 配对作为单独的资产进行管理。即使词序发生变化,也要保持变量含义和按钮操作一致。 独立审批和发布每个语言区域。切勿仅仅因为某个语言区域已获批准就将用户转到其他语言。在创建、检索、编辑、删除和发送请求中,必须使用完全一致且区分大小写的语言区域代码。

根据模板状态控制发送

使用检索接口或 whatsapp.template.reviewed Webhook 来处理批准、拒绝、暂停、禁用、归档以及其他生命周期变化。在消息请求中保留完全一致的名称和语言。 将 API status 与您的发布状态分开存储。仅将生产发送路由到当前状态为 APPROVED 且发布状态为 active 的模板。 成功的创建或编辑响应并不授权生产发送。

同步状态

使用 Webhook 获取及时更新,并使用查询或列表 API 进行对账:
  1. 验证每个 whatsapp.template.reviewed 事件的签名。
  2. 按事件 id 进行推送去重。
  3. 按 wabaId、name 和 language 解析资产。
  4. 同时存储更新事件和当前 status。
  5. 当前状态不是 APPROVED 时立即停止路由。
  6. 当事件缺失、延迟或与较新的注册状态冲突时,检索模板。
  7. 运行定时分页列表对账以检测状态漂移。
不要将 Webhook 作为唯一的清单来源,也不要在每次发消息前都进行轮询。

编辑和删除行为

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

发布、回滚和停用版本

发生重大变更时,建议使用并行版本:
  1. 为每个所需语言区域创建带有版本标识的新名称。保持当前已获批准的版本不变。
  2. 等待每个目标语言区域变为 APPROVED,然后验证其变量、媒体、按钮、类别和渲染后的内容。
  3. 将受控比例的符合条件的发送流量路由到新版本,并监控送达率、质量、回复和状态更新。
  4. 仅在新版本符合您的发布标准后,才迁移剩余流量。
通过将路由切换到先前批准的名称和语言来执行回滚。切勿将紧急编辑用作回滚手段。仅在队列、活动、配置、测试和回滚窗口不再引用先前版本后,才将其停用。

限制与问题排查

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

上线前检查清单

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

支持的语言

为模板选择确切的语言和地区语言代码。

模板创建示例

调整身份验证、营销、通用(Utility)、商业、Flow 和通话模板。

创建模板 API

检查完整的组件架构。

模板审核 Webhook

处理审核和生命周期状态变更。