> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理 WhatsApp 模板

> 安全地创建、版本化、审核、发布和废弃 WhatsApp 消息模板。

## 概述

WhatsApp 模板是预先批准的消息结构，用于在客户服务窗口之外发起或继续对话。模板由 WABA、名称和语言共同标识。

使用本指南管理 API 生命周期，并确保生产模板资产在不同团队、版本和语言区域之间保持稳定。

## 准备工作

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

## 工作原理

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

编辑会替换现有模板内容。请包含编辑后必须保留的每个组件。

## 请求

`POST /whatsapp/templates`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"]]
        }
      }
    ]
  }'
```

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

## 响应

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "wabaId": "WABA_ID",
  "name": "order_ready",
  "language": "en_US",
  "category": "UTILITY",
  "status": "PENDING",
  "components": [
    {
      "type": "BODY",
      "text": "Order {{0}} is ready for pickup."
    }
  ]
}
```

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

## 定义稳定的资产标识

将每个 WABA、模板名称和语言组合视为一个资产。维护一份资产登记表，其中包含所属 `wabaId`、稳定名称、确切的语言区域代码、用途、所有者、变量约定、当前 API 状态、推出状态以及替换版本。

使用可预测的名称，例如 `<domain>_<purpose>_v<major>`：

* `auth_login_otp_v1`
* `orders_pickup_ready_v2`
* `growth_summer_offer_v3`

当变更影响到变量位置、组件类型、按钮、类别或消息含义时，请递增主版本号。保持名称独立于团队名称和日期。

## 在编写内容前选择类别

根据客户接收消息的原因选择类别。

| 类别 | 适用场景 |
| - | - |
| `AUTHENTICATION` | 您使用一次性密码对用户进行身份验证，以进行验证、恢复或完整性质询。 |
| `UTILITY` | 您满足用户的特定请求，或提供有关已达成交易的更新。 |
| `MARKETING` | 您发送优惠、促销、邀请或其他不属于身份验证或公共事业的内容。 |

如果模板混合了交易信息与促销内容，请将其设计为营销类，或将不同用途拆分为单独的模板。

## 冻结变量约定

在文案人员或翻译人员开始工作之前，将变量定义为 API 约定。针对每个变量，记录其位置、语义含义、格式、来源、代表性示例和回退行为。

例如，`Order {{0}} is ready at {{1}}.` 可以使用以下约定：

| 位置 | 含义 | 格式 | 审核示例 |
| - | - | - | - |
| `{{0}}` | `order_reference` | 面向客户的简短字符串 | `A-10001` |
| `{{1}}` | `pickup_location` | 本地化门店名称 | `Central Store` |

保持每个位置的含义在不同版本和语言区域中始终一致。如果需要重新排序或更改变量用途，请创建新版本。

提交之前：

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

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

在同一次发布中为每个语言区域复用相同的带版本名称，但将每个 `name` 和 `language` 对作为独立资产进行管理。即使词序发生变化，也要保持变量含义和按钮操作一致。

独立批准并发布每个语言区域。切勿仅仅因为某个语言区域已获批准就将用户路由到其他语言。在创建、检索、编辑、删除和发送请求中，请使用确切且区分大小写的语言区域代码。

## 根据模板状态控制发送

使用检索或 `whatsapp.template.reviewed` Webhook 处理批准、拒绝、暂停、停用、归档等生命周期变更。保持消息请求中使用的确切名称和语言不变。

将 API `status` 与您的推出状态分开存储。仅将生产发送路由到当前状态为 `APPROVED` 且推出状态为活跃的模板。

| 状态 | 生产操作 |
| - | - |
| `PENDING` | 审核进行中时阻止发送。 |
| `APPROVED` | 在契约测试和发布审批通过后允许发送。 |
| `REJECTED` | 阻止发送，检查原因，并更正内容或契约。 |
| `PAUSED` 或 `DISABLED` | 停止新发送，并在可用时使用已批准的备用方案。 |
| `IN_APPEAL` | 保持阻止发送，直到状态变为 `APPROVED`。 |
| `ARCHIVED` 或 `DELETED` | 从路由中移除该模板。 |

成功的创建或编辑响应并不授权进行生产环境发送。

## 同步状态

使用 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 处理已验证、具备幂等性，并与检索对账。
* [ ] 发布方案能够恢复到先前已批准的版本。
* [ ] 队列、营销活动、配置、测试和运维手册均使用目标版本。

<CardGroup cols={2}>
  <Card title="支持的语言" icon="language" href="/zh/api-reference/guides/whatsapp-platform/supported-whatsapp-template-languages">
    为模板选择准确的语言和区域语言代码。
  </Card>

  <Card title="模板创建示例" icon="rectangle-list" href="/zh/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples">
    调整身份验证、营销、通用、商务、Flow 和通话模板。
  </Card>

  <Card title="创建模板 API" icon="code" href="/api-reference/whatsapp-templates/create-a-template">
    检查完整的组件 Schema。
  </Card>

  <Card title="模板审核 Webhook" icon="webhook" href="/zh/api-reference/guides/examples/webhook-examples/whatsapp-template-reviewed-webhook-examples">
    处理审核和生命周期状态变更。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.