---
title: "WhatsApp模板变量：{{1}}与命名参数的区别"
description: "讲解WhatsApp模板变量的工作方式：位置参数{{1}}与命名参数、变量可用的位置、示例值、Meta的驳回规则，以及发送请求的完整示例。"
canonical: "https://omnichannels.ai/zh/blog/whatsapp-template-variables-parameters/"
language: "zh"
updated: "2026-11-08"
publisher: "BroadNet Technologies"
brand: "OmniChannels.ai"
category: "whatsapp"
primaryQuery: "WhatsApp模板变量"
keywords: ["WhatsApp模板变量", "WhatsApp模板参数", "WhatsApp模板{{1}}", "WhatsApp命名参数", "parameter_format WhatsApp", "WhatsApp模板示例值", "WhatsApp模板变量被驳回", "WhatsApp个性化模板CSV"]
published: "2026-11-08"
author: "OmniChannels.ai Editorial Team"
reviewer: "BroadNet Messaging Solutions Team"
readingMinutes: 9
answer: "WhatsApp模板变量是每次发送时填入的占位符，位置格式写作{{1}}，命名格式写作{{first_name}}。创建模板时用parameter_format选择格式，默认为位置格式。每个变量都需要示例值供审核。变量可用于正文、文本标题（一个）和URL按钮后缀（一个）；以变量开头或结尾的模板会被Meta驳回。"
takeaways: ["位置变量编号为{{1}}、{{2}}，必须按顺序填写；命名变量使用带下划线的小写名称，可按任意顺序填写。", "创建模板时必须为每个变量提供示例值；Meta在审核时会用到这些示例。", "文本标题支持一个变量，正文可以有多个，URL按钮支持一个附加在URL末尾的变量。", "Meta文档列出的驳回原因包括：变量格式错误或不连续、模板以变量开头或结尾、相对文本长度变量过多，以及含有#、$或%等特殊字符。", "用CSV实现个性化，意味着每位收件人一行，并为每个变量提供干净的值。"]
faq: 
  - q: "位置参数和命名参数有什么区别？"
    a: "位置模板使用{{1}}这样的编号占位符，发送时的值必须按相同顺序提供。命名模板使用带下划线的小写名称，如{{order_number}}，发送请求中的值可以按任意顺序出现。如果创建模板时没有设置parameter_format，Meta会使用位置格式。"
  - q: "WhatsApp模板中哪些位置可以使用变量？"
    a: "Meta的文档列出：正文可接受多个参数，文本标题支持一个参数，URL按钮支持一个附加在URL末尾的变量。媒体标题携带的是素材而不是变量。页脚、快速回复按钮和电话号码按钮未被列为支持变量。"
  - q: "为什么我的模板因变量被驳回？"
    a: "Meta的审核指南列出了几类与变量有关的原因：花括号缺失或不匹配、变量不连续、消息以变量开头或结尾、相对消息长度变量过多，以及含有#、$或%等特殊字符。请修改文本，补充真实可信的示例，然后重新提交。"
  - q: "我需要示例值吗？"
    a: "需要。Meta称，如果模板使用变量，创建时必须提供示例值，每个参数一个。请使用真实可信的值，而不是test之类的占位文字，让审核人员能看到最终消息的样子。示例只用于审核；真实的值在发送时提供。"
  - q: "变量里可以包含换行或链接吗？"
    a: "本指南只涵盖我们在Meta文档中核实过的内容，我们查阅的页面没有说明变量值内换行的规则。请向您自己的号码实际发送一次来测试；如果打算传入较长或带格式的值，请咨询我们的团队。URL按钮的值会附加在按钮URL的末尾。"
  - q: "如何用电子表格实现模板个性化？"
    a: "每位收件人一行，每个变量一列，并保证值干净：姓名没有多余空格，日期格式统一，号码使用国际格式。发送个性化活动时上传文件并检查预览。首次活动之前，请与我们的团队确认具体的列布局。"
sources: 
  - title: "Template fundamentals — WhatsApp Business Platform, Meta for Developers"
    url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview"
  - title: "Template components — WhatsApp Business Platform, Meta for Developers"
    url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/components"
  - title: "Template review — WhatsApp Business Platform, Meta for Developers"
    url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-review"
---

# WhatsApp模板变量：{{1}}与命名参数的区别

Canonical: https://omnichannels.ai/zh/blog/whatsapp-template-variables-parameters/
Language: zh
Publisher: OmniChannels.ai by BroadNet Technologies

本指南面向创建个性化WhatsApp模板的开发者和营销人员。内容说明两种变量格式、变量可以放在哪里、Meta关于审核的说法，以及如何通过API或电子表格发送这些值。

## 什么是WhatsApp模板变量？

变量是模板文本中的占位符，发送时用真实的值替换。Meta称之为参数（parameters），WhatsApp Manager称之为变量（variables）。模板文本和示例值只审核一次；真实的值则在每条消息发送时提供。

例如，模板正文为`Hi {{1}}! Your order number is {{2}}. Thank you.`，您向一位客户发送`Hi Layla! Your order number is OM-4821. Thank you.`，向下一位客户则发送另一组值。

Meta不会翻译模板文本或变量值。您需要为模板的每个语言版本提供对应语言的内容。

## 位置参数和命名参数有什么区别？

创建模板时通过`parameter_format`字段选择格式。如果省略，Meta使用`positional`。

| | 位置参数 | 命名参数 |
|---|---|---|
| 占位符 | `{{1}}`、`{{2}}` | `{{first_name}}`、`{{order_number}}` |
| 命名规则 | 从1开始按顺序编号 | 唯一，由小写字母和下划线组成 |
| 发送时的值 | 必须按占位符顺序 | 可按任意顺序 |
| 示例值 | `body_text`数组 | 带`param_name`的`body_text_named_params` |
| 最适合 | 只有一两个变量的短模板 | 变量较多、需要他人维护的模板 |

命名参数在模板库中更易读，顺序弄反也不会悄悄把订单号放到姓名的位置。位置模板写起来更短，并且仍是默认格式。

## 哪些位置允许使用变量？

Meta的组件文档列出了以下位置：

| 组件 | 变量 |
|---|---|
| 文本标题 | 一个参数 |
| 正文 | 多个参数 |
| URL按钮 | 一个变量，附加在URL末尾 |
| 媒体标题（图片、视频、文档） | 无；创建时提供示例素材，发送时提供素材 |
| 页脚、快速回复和电话号码按钮 | 未被列为支持变量 |

文档记载的长度限制：文本标题最多60个字符，正文最多1,024个，页脚最多60个，按钮标签最多25个，按钮URL最多2,000个字符。如果URL按钮的值含有特殊字符，Meta要求进行百分号编码。

## 如何提供示例值？

Meta的规则是：如果模板使用变量，创建时必须提供示例值，每个参数一个。带变量的标题也需要一个`example`。

带示例的位置式正文：

```json
{
  "type": "BODY",
  "text": "Hi {{1}}! Your order {{2}} ships on {{3}}.",
  "example": { "body_text": [["Layla", "OM-4821", "12 November"]] }
}
```

带示例的命名式正文：

```json
{
  "type": "BODY",
  "text": "Hi {{first_name}}! Your order {{order_number}} ships on {{ship_date}}.",
  "example": {
    "body_text_named_params": [
      { "param_name": "first_name", "example": "Layla" },
      { "param_name": "order_number", "example": "OM-4821" },
      { "param_name": "ship_date", "example": "12 November" }
    ]
  }
}
```

第二种形式要求模板本身设置`"parameter_format": "named"`。请使用真实可信的示例，让审核人员能看到真实消息的内容。

## Meta对变量规则和驳回是怎么说的？

Meta的模板审核指南列出了以下与变量相关的驳回原因：

- 变量缺失，或花括号不匹配。正确的位置格式是`{{1}}`。
- 变量不连续，例如`{{1}}`、`{{2}}`、`{{5}}`、`{{4}}`。
- 模板以变量开头或结尾。Meta称之为悬空参数（dangling parameters）。
- 相对消息长度，模板的变量过多。Meta没有给出比例，所以请在每个变量周围加入固定文字。
- 变量含有`#`、`$`或`%`等特殊字符。

我们没有找到关于两个变量紧挨着放置的官方说法，因此不给出相关规则。请用文字把它们隔开，这样读起来也更顺畅。

关于类别规则以及导致驳回的其他原因，请参阅[WhatsApp模板类别与审批](/zh/blog/whatsapp-template-categories-approval/)。现成的措辞可参阅[WhatsApp消息模板示例](/zh/blog/whatsapp-message-template-examples/)。

## 如何在API调用中发送参数？

您发送模板名称、语言，以及带有这些值的`components`数组。位置模板的结构如下：

```json
{
  "messaging_product": "whatsapp",
  "to": "971500000000",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": { "code": "en" },
    "components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "Layla" },
        { "type": "text", "text": "OM-4821" },
        { "type": "text", "text": "12 November" }
      ] }
    ]
  }
}
```

对于命名模板，每一项还要带上`parameter_name`，它必须与占位符一致：

```json
{ "type": "text", "parameter_name": "order_number", "text": "OM-4821" }
```

### 标题媒体参数如何工作？

媒体标题没有文本变量。创建时，标题中放的是通过Meta上传流程获得的示例素材句柄，该示例会随模板一起审核。发送时您传入素材，例如按媒体ID传入图片：

```json
{ "type": "header", "parameters": [ { "type": "image", "image": { "id": "1558081531584829" } } ] }
```

上面的ID是Meta文档中的示例，不是真实素材。

### 通过OmniChannels.ai API如何实现？

我们的`sendbulk`端点按[WhatsApp API文档](/developers/whatsapp/)以表单字段接收模板：

| 模板功能 | 字段 |
|---|---|
| 正文变量 | `bodyTemplateVariables` |
| 命名参数 | `bodyTemplateVariables={"parameter_name":"order_id","text":"ORD-12345"}` |
| 标题文本变量 | `headerTemplateVariables` |
| 标题图片、视频或文档 | `mediaUrl`（覆盖标题媒体） |
| 动态URL按钮 | `buttonsTemplateVariable` |

## 实例：发货通知模板

“Souq Rafiq”（虚构）是一家阿联酋零售商，想发送一条带商品图片和物流跟踪按钮的发货通知。

1. **撰写模板**，使其既不以变量开头也不以变量结尾：“Hi {{1}}, your order {{2}} has shipped and should arrive on {{3}}. Tap the button to follow it.”
2. **添加标题**为图片，页脚为纯文本，再添加URL按钮`https://shop.example/track/{{1}}`，示例值如`OM-4821`。
3. **提交**时为每个变量提供真实可信的示例，然后等待审批状态。
4. **发送**时提供三个正文值、物流跟踪后缀，以及（如果要覆盖的话）标题图片。

```bash
curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-shipped \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=order_shipped \
  -F templateLanguage=en \
  -F bodyTemplateVariables=Layla \
  -F buttonsTemplateVariable=OM-4821
```

此代码片段展示的是单个值的字段名。如果每位收件人有多个正文变量，请使用个性化上传，而不是重复执行该命令。首次活动前，请与我们的团队确认编码方式。

## 如何用CSV实现模板个性化？

每位收件人一行，每个变量一列，然后在个性化发送中上传。

1. 在第一列填写收件人的国际格式号码。请参阅[E.164电话号码格式](/zh/blog/e164-phone-number-format/)。
2. 每个变量增加一列，并在首次活动前与我们的团队确认列布局。
3. 先清理数据：去掉空格、统一大小写、使用同一种日期格式、删除空值，因为空变量会导致消息错乱或发送失败。
4. 预览多行数据，并先发给您自己的号码。

数据清理的步骤见[用Excel或CSV群发短信](/zh/blog/send-bulk-sms-from-excel-csv/)；这些方法同样适用于WhatsApp。

## 如何在位置参数和命名参数之间做选择？

根据有多少人会改动模板、模板有多少变量来选择。

1. 一两个变量、由一人负责：位置参数即可，也是默认格式。
2. 三个或更多变量，或多个团队编辑模板：使用命名参数，让每个占位符自带说明。
3. 同样的文案有多个语言版本：各版本保持相同的名称或编号，这样一套发送流程就能填充所有语言。
4. 始终记录哪一列来源数据对应哪个变量，这样以后修改模板时数据不会错位。

提交之前，带着示例值把成品消息朗读一遍。如果听起来不自然，审核人员和客户也会这样觉得。

## 常见错误有哪些？

- **以变量开头或结尾，** Meta将其列为驳回原因。
- **跳号**，或在位置模板中乱序重复使用同一编号。
- **占位式示例**，例如“test”，对审核人员没有任何信息量。
- **变量中含有特殊字符**，如`#`、`$`或`%`。
- **位置模板发送时顺序错误**，会把正确的数据放到错误的位置。
- **命名模板中`parameter_name`不匹配。**
- **用变量掩盖消息的真实用途。** 类别与内容不符的模板可能被驳回或被重新归类；请参阅[类别指南](/zh/blog/whatsapp-template-categories-approval/)。
- **局限：** 本指南反映的是撰写时Meta文档的说明。审核决定权在Meta，规则也会变化，请查阅所附页面。

## OmniChannels.ai如何提供帮助

BroadNet是Meta官方的商业解决方案提供商（Business Solution Provider）。在OmniChannels.ai中，您可以创建带变量、媒体和按钮的WhatsApp模板，预览并跟踪审批状态，然后通过API，或在活动中上传Excel或CSV，以个性化的值发送。系统包含重复号码过滤和送达报告。请参阅[WhatsApp Business API页面](/zh/channels/whatsapp-business-api/)和[活动平台](/zh/platform/campaigns/)。