> ## 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.

# 模板组件与格式

> 配置模板组件、变量、按钮和专用格式。

使用正文、可选的页眉和页脚以及按钮构建模板。针对不同接收者变化的内容添加变量。身份验证和专用格式具有额外的约束。

## 标准模板结构

| 组件 | 包含内容 | 主要限制与检查项 |
| - | - | - |
| 页眉 | 可选的简短文本或支持的媒体/位置页眉。 | 文本页眉：最多 60 个字符，且最多包含一个变量。单个页眉只能使用一种格式，不能将多种媒体类型组合在一起。 |
| 正文 | 消息的主要说明内容。 | 必填；标准模板正文最多 1,024 个字符。保留足够的固定文本以明确消息目的。 |
| 页脚 | 可选的辅助文本。 | 标准页脚最多 60 个字符。请勿将其用作另一个包含丰富变量的正文。 |
| 按钮 | 可选的回复或操作。 | 支持的标准组合总计最多 10 个，按按钮类型分别有各自的限制。 |
| 示例 | 用于审核的变量值示例和媒体示例。 | 提供所选组件要求的示例。示例不等于针对特定接收者的发送数据。 |

这些限制并不保证每个专用模板都能接受所有组合。身份验证使用预设文本；轮播卡片、限时优惠、电商模板和通话组件有各自的结构。

实用的标准布局如下：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
HEADER: Appointment update
BODY: Your booking {{1}} is confirmed for {{2}} at {{3}}.
FOOTER: Reply if you need help.
BUTTON: View booking
```

该示例仅用于说明结构；未经 Meta 预先批准。

<Frame caption="Meta labels the standard components. This promotional example illustrates structure, not a utility-category decision.">
  <div style={{ position: "relative", width: "100%", maxWidth: "720px", margin: "0 auto" }}>
    <img src="https://mintcdn.com/lchnan/Q9LYCM-XEE-Z8muf/product-assets/whatsapp-platform-2026-09-22/meta-marketing-template-components.png?fit=max&auto=format&n=Q9LYCM-XEE-Z8muf&q=85&s=26b207935b6d6d53953bd583297490da" alt="带有标记的页眉、正文、页脚、URL、电话和快速回复按钮的 Meta 模板结构。" style={{ width: "100%", height: "auto", margin: 0 }} width="2321" height="1416" data-path="product-assets/whatsapp-platform-2026-09-22/meta-marketing-template-components.png" />
  </div>
</Frame>

来源：[Meta 官方示例](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/custom-marketing-templates/)。

## 选择正确的按钮操作

| 按钮 | 客户操作 | 标准约束或依赖项 |
| - | - | - |
| 快速回复 | 向商家发送预定义的回复。 | 最多 10 个；与其他按钮类型混用时，需将快速回复按钮集中归为一组。 |
| 网站 URL | 打开网页。 | 最多 2 个 URL 按钮。标签：25 个字符。URL：2,000 个字符，末尾最多包含一个变量。 |
| 电话号码 | 拨打配置的电话号码。 | 最多 1 个。标签：25 个字符；电话号码值：20 个字符。这不是 WhatsApp 语音通话。 |
| 复制优惠码 | 将优惠券代码复制到剪贴板。 | 1 个复制优惠码按钮；适用于对应的营销格式。按钮标签为预设文本。 |
| OTP | 复制或自动填充验证码。 | 仅限身份验证模板；使用身份验证专用的按钮配置。 |
| 目录或多商品 | 打开对应的目录或选定商品。 | 需要正确的目录和有效的商品标识符。 |
| Flow | 在 WhatsApp 中打开结构化表单。 | 生产环境需要正确的 Flow、入口操作以及可用的已发布版本。 |
| WhatsApp 通话 | 发起支持的 WhatsApp 通话互动。 | 需要具备通话（Calling）资格。不能替代电话号码按钮或呼出通话权限请求。 |

标签为 **Stop promotions** 的快速回复按钮并非自动退订实现。您的业务流程必须识别该回复并更新客户偏好设置。请参阅 [客户选择退出](/zh/documentation/whatsapp-business-platform/consent-policies-and-account-health/customer-opt-out)。

### 按钮顺序会影响可用性和兼容性

将最重要的操作排在前面。当按钮超过三个时，WhatsApp 会显示前两个按钮，其余按钮通过 **See all options** 控件展示。

<Frame caption="Meta's example of a template with additional actions behind See all options. Client appearance may vary.">
  <img src="https://mintcdn.com/lchnan/3gBf_HfRdWRqXdyx/images/whatsapp-platform/meta-template-buttons.png?fit=max&auto=format&n=3gBf_HfRdWRqXdyx&q=85&s=e1f6e7987450e79c5afe3fb1ace30b6f" alt="包含两个可见操作按钮和“查看所有选项”的 WhatsApp 模板，旁边展开的列表包含 URL、电话和快速回复操作。" width="800" height="660" data-path="images/whatsapp-platform/meta-template-buttons.png" />
</Frame>

来源：[Meta 模板组件](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/components)。

将快速回复和其他按钮类型分开放置在不同的分组中：

* 有效分组：URL → 电话 → 快速回复 → 快速回复。
* 无效分组：快速回复 → URL → 快速回复。

Meta 目前在文档中说明了桌面端对包含 4 个或更多按钮、或者将快速回复与其他按钮类型混用的模板的限制：接收者会被提示在手机上查看这些消息。如果桌面端使用对您的受众很重要，请测试此项。

## 变量：设计、审核和发送是不同的阶段

对于此正文：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Your booking {{1}} is confirmed for {{2}} at {{3}}.
```

使用您的团队和集成可以维护的映射关系：

| 位置 | 含义 | 审核示例 | 实际发送 |
| - | - | - | - |
| 正文 1 | 预订参考编号 | BOOKING-123 | 收件人的预订参考编号。 |
| 正文 2 | 日期 | 2026 年 10 月 12 日 | 已确认的预约日期。 |
| 正文 3 | 时间和时区 | 10:30 AM UTC | 包含充分本地上下文的已确认时间。 |

审核示例用于说明变量的含义。它们不会配置数据源，也不会自动填充未来的消息。

**页眉、正文和每个动态按钮具有独立的参数位置**。正文 `{{1}}` 与 URL 按钮 `{{1}}` 无需包含相同的值。按钮 `index` 标识该按钮在模板中的位置，从 `0` 开始；它不是正文变量编号。

### 示例：正文值与动态 URL

假设已审核的模板包含：

* 正文：`Your booking {{1}} is confirmed for {{2}}.`
* 索引为 `0` 的按钮：`https://example.com/bookings/{{1}}`

YCloud 消息的 template 对象可以按如下方式映射它们：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "booking_confirmation",
  "language": { "code": "en_US" },
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "BOOKING-123" },
        { "type": "text", "text": "12 October 2026, 10:30 AM UTC" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": 0,
      "parameters": [
        { "type": "text", "text": "BOOKING-123" }
      ]
    }
  ]
}
```

这是一个 **template 对象片段**，并非完整的发送请求。它假设指定的模板和确切的语言变体已在发送方的 WABA 中获得批准。按钮参数提供的是后缀，而非完整 URL。

在审核通过的模板中保持目标域名的稳定。对 URL 值进行正确编码，并避免在链接中放置私密信息或长期访问凭据。切勿使用变量来掩盖消息的真实类别。

## 媒体页眉：示例资源不是实际附件

对于图片、视频或文档页眉：

1. 在创建模板时选择所需的页眉格式。
2. 提供具有代表性的示例以供审核。
3. 在发送时，使用受支持的 YCloud 媒体 ID 或链接字段提供实际媒体。
4. 确认文件可正常检索，其格式与模板匹配，并且符合媒体限制要求。
5. 测试已送达的消息，包括文件在手机上的可读性。

切勿向视频页眉模板发送图片参数。仅在登录后才可访问的私有 URL 对于消息发送服务而言不是可靠的媒体链接。

GIF 页眉出现在当前的接口协议中，但 Meta 将该功能限制在适用的 **Marketing Messages API for WhatsApp** 路径中。不要仅仅因为字段存在，就认为它在每个常规模板工作流中都可用。

## 选择专用格式

| 您的需求... | 选择 | 创建前准备 |
| - | - | - |
| 展示多个带有独立操作的视觉选项 | [媒体轮播](/zh/documentation/whatsapp-business-platform/messaging/message-templates/carousel-templates) | 一致的卡片媒体和按钮结构；每张卡片的发送值。 |
| 让客户复制促销代码 | [优惠券代码模板](/zh/documentation/whatsapp-business-platform/messaging/message-templates/coupon-code-templates) | 实际可兑换的代码和明确的优惠条款。 |
| 展示限时促销 | [限时优惠](/zh/documentation/whatsapp-business-platform/messaging/message-templates/limited-time-offer-templates) | 过期时间值及匹配的结账规则。 |
| 打开整个产品系列 | [目录模板](/zh/documentation/whatsapp-business-platform/messaging/message-templates/catalog-templates) | 关联的目录以及有效的缩略图产品（如果指定）。 |
| 展示精选的目录产品组合 | [多产品模板](/zh/documentation/whatsapp-business-platform/messaging/message-templates/multi-product-templates) | 产品 ID、板块和当前的供货情况。 |
| 收集结构化回答 | [Flow](/zh/documentation/whatsapp-business-platform/more-whatsapp-features/whatsapp-flows/index) | Flow ID、屏幕、数据处理和完成工作流。 |
| 验证请求的登录或找回操作 | [身份验证模板](/zh/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index) | 代码生成、验证、有效期和回退处理。 |

## 诊断组件错误

| 症状 | 优先检查 |
| - | - |
| 参数数量或格式错误 | 对比每个组件所需的变量与发送载荷。切勿将所有变量统算为一个共享列表。 |
| 错误按钮打开或失败 | 检查按钮索引、子类型、URL 后缀和已审核的按钮顺序。 |
| 媒体无法送达 | 检查实际发送时的媒体、可访问性、MIME 类型、大小以及模板页眉格式。 |
| 找不到模板 | 检查 WABA、名称和确切的语言变体。 |
| 无效的按钮组合 | 检查总数、各类型数量以及快速回复分组。 |
| 仅在单台设备上有效 | 测试最新的 Android、iOS 和桌面客户端；检查特定格式的兼容性。 |

[YCloud 模板 API 指南](/zh/api-reference/guides/whatsapp-platform/manage-whatsapp-templates)与 [OpenAPI 规范](https://newdocs.ycloud.com/openapi/endpoints/ycloud-api-v2.yaml)定义了 YCloud 字段。Meta 的组件支持并不代表每个 YCloud 编辑器、收件箱、群发活动或 API 路由都会开放相同的功能。

继续阅读 [创建模板](/zh/documentation/channels/whatsapp-accounts-management/template-management/create-template/index) 和 [模板审核与生命周期](/zh/documentation/whatsapp-business-platform/messaging/message-templates/template-review-and-lifecycle)。


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