WhatsApp 消息模板组件说明

本文介绍了通过 API 创建/编辑 WhatsApp 群发活动或发送 WhatsApp 模板消息时，请求中所需的 WhatsApp 消息模板组件，详细说明了每个组件的结构和参数，以帮助你构建合规且有效的消息。

介绍

WhatsApp 消息模板由四个主要组件组成：标头 (Header)、正文 (Body)、页脚 (Footer) 和按钮 (Button)。其中，标头、正文和 按钮 组件支持动态变量的占位符。当通过 Yeastar P 系列云 PBX API 创建/编辑 WhatsApp 群发活动或发送 WhatsApp 模板消息时，你需要为模板中的占位符提供对应变量的值，并填写必要的按钮信息 (如按钮类型及按钮变量值)。模板中的固定文本内容则会自动从模板本身获取。

在构建消息对象时，应将所有占位符替换为实际的变量值。然后将该消息对象转义为 JSON 字符串，并将转义后的 JSON 字符串通过 msg_param (用于 WhatsApp 群发活动) 或 whatsapp_msg_param (用于 WhatsApp 会话) 参数在请求中传递。

消息模板对象结构

PBX API 使用 msg_param 或 whatsapp_msg_param 参数来传递消息模板所需的信息。该参数是一个字符串，内容为经过 JSON 编码的消息对象，用于定义消息模板的结构、组件以及动态变量值。

以下是 msg_param 或 whatsapp_msg_param 参数的 JSON 结构示例：

{
    "id": 579,
    "template_id": "1617698099069106",
    "name": "demo-template",
    "language": {
        "code": "en"
    },
    "parameter_format": "POSITIONAL",
    "components": [
        {
            "type": "HEADER",                           //模板标头
            "parameters": [
                {
                   ...
                }
            ]
        },
        {
            "type": "BODY",                             //模板正文
            "parameters": [
                {
                    ...
                }
            ]
        },
        {
            "type": "BUTTONS",                           //模板按钮
            "parameters": [
                {
                    ...
                }
            ]
        }
    ]
}

结构中的每个参数的具体说明如下表所示。

参数 是否必填 类型 说明
id 是 Integer PBX 中的消息模板 ID。
template_id 是 String 来自 WhatsApp 平台的原始模板 ID。
name 是 String 模板名称。
language 是 Object<Template_Lang> 模板语言。
parameter_format 是 String 模板中占位符的引用方式。

取值范围：

  • POSITIONAL：占位符按位置引用。例如，{{1}}、{{2}}。
  • NAMED：占位符按变量名引用。例如，{{name}}、{{code}}。
components 否 Array<Components> WhatsApp 消息模板的组件列表 (包括标头、正文和按钮)。
注：
  • 如果模板中带有变量或按钮，此参数必填。
  • 如果模板仅包含静态文本 (无变量或按钮)，此参数可为空。
Template_Lang
参数 是否必填 类型 说明
code 是 String 模板所使用语言的代码。
Components
注： components 参数中的必填字段取决于所选 WhatsApp 消息模板的具体要求。
参数 类型 说明
type String 组件类型。
取值范围：
  • HEADER
  • BODY
  • BUTTONS
parameters Array <Object> 组件中占位符 (变量) 值的列表。

在发送消息时，模板中的每个占位符都需要提供具体的值。你可以通过该参数指定用于替换模板中占位符的实际值。

关于各组件参数的具体信息，请参见以下章节：

标头 (Header) 组件对象

Header 组件对象用于定义当 组件类型 设置为 HEADER 时所使用的参数。该组件支持以下类型：

文本标头
参数 类型 说明
type String 元素类型。

取值范围：TEXT。
text String 用于替换元素中对应占位符 (变量) 的文本内容。
parameter_name String 占位符 (变量) 的名称。
注：
示例如下：
  • 命名参数示例
     {
      "type": "HEADER",
      "parameters": [
            {
                 "type": "TEXT",
                 "text": "Gold",
                 "parameter_name": "membershiptype"
            }
          ]
  }
  • 位置参数示例
     {
      "type": "HEADER",
      "parameters": [
            {                             //标头中的变量 {{1}}
                 "type": "TEXT",
                 "text": "Gold"
            }
          ]
  }
媒体标头
参数 类型 说明
type String 元素类型。
取值范围：
  • IMAGE
  • VIDEO
  • DOCUMENT
file_list Array 媒体文件的信息。
注： 你需要先使用 上传消息文件 接口上传所需文件，然后从响应中获取文件信息。
示例如下：
  • 图片对象
     {
      "type": "HEADER",
      "parameters": 
      [
         {
            "type": "IMAGE",
            "file_list": [
                        {
                            "id": "993d9780ec2c4a3f81f59fa78a40ecb6",
                            "name": "demo.png",
                            "uri": "20250805/993d9780ec2c4a3f81f59fa78a40ecb6",
                            "type": "image/png",
                            "size": 5651
                        }
                    ]
          }
      ]
 }
  • 视频对象
     {
      "type": "HEADER",
      "parameters": 
      [
         {
            "type": "VIDEO",
                    "file_list": [
                        {
                            "id": "dfb5077f93e040b381da8d9a597c4743",
                            "name": "demo.mp4",
                            "uri": "20250805/dfb5077f93e040b381da8d9a597c4743",
                            "type": "video/mp4",
                            "size": 1745551
                        }
                    ]
          }
      ]
  }
  • 文件对象
     {
      "type": "HEADER",
      "parameters": 
      [
         {
            "type": "DOCUMENT",
                    "file_list": [
                       {
                          "id": "d71a2a146a5146fcb0b1464e293ea38e",
                          "name": "demo.csv",
                          "uri": "20250801/d71a2a146a5146fcb0b1464e293ea38e",
                          "type": "text/csv",
                          "size": 56890
                      }
                    ]
          }
      ]
 }
位置标头
参数 类型 说明
type String 元素类型。

取值范围：LOCATION。
location Object<Location_Info> 位置详细信息。
Location_Info
参数 类型 说明
name String 位置的名称。
address String 位置的详细地址。
latitude String 位置的维度。
longitude String 位置的精度。
示例如下：
 {
       "type": "HEADER",
       "parameters": [
            {
               "type": "LOCATION",
               "location": {
                    "name": "Madison Square Garden",
                    "address": "4 Pennsylvania Plaza, Suite 105, New York, NY 10001",
                    "latitude": "40.7505045",
                    "longitude": "-73.9934387"
                   }
              }
         ]
}

正文 (Body) 组件对象

Body 组件对象定义了当 组件类型 设置为 BODY 时所使用的参数。
注： 该组件仅支持文本参数。
参数 类型 说明
type String 元素类型。

取值范围：TEXT。
text String 用于替换元素中对应占位符 (变量) 的文本内容。
parameter_name String 占位符 (变量) 的名称。
注：
示例如下：
  • 命名参数示例
     {
      "type": "BODY",
      "parameters": [
            {
                 "type": "TEXT",
                 "text": "Gold",
                 "parameter_name": "membershiptype"
             },
             {
                 "type": "TEXT",
                 "text": "2025-08-30",
                 "parameter_name": "expirydate"
             },
             {
                  "type": "TEXT",
                  "text": "2025-09-30",
                  "parameter_name": "renewdeadline"
             }
          ]
  }
  • 位置参数示例
     {
      "type": "BODY",
      "parameters": [
            {                             //正文中的变量 {{1}}
                 "type": "TEXT",
                 "text": "Gold"
             },
             {                            //正文中的变量 {{2}} 
                 "type": "TEXT",
                 "text": "2025-08-30"
             },
             {                            //正文中的变量 {{3}}                   
                  "type": "TEXT",
                  "text": "2025-09-30"
             }
          ]
  }

按钮 (Button) 组件对象

按钮 (Button) 组件对象定义了当 组件类型 设置为 BUTTON 时所使用的参数。

参数 类型 说明
type String 按钮元素的类型。
取值范围：
  • URL
  • FLOW
  • COPY_CODE
  • QUICK_REPLY
text String
用于替换模板中相应占位符 (变量) 的文本内容。
注：
  • 以下类型的按钮必须填写此参数：
    • 包含变量的 URL 按钮
    • 复制验证码 (COPY CODE) 按钮
  • 对于其他类型的按钮，此参数可留空。
示例如下：
  {
            "type": "BUTTONS",
            "parameters": [                      // 按顺序构建一个包含多个按钮的数组。
               {
                    "type": "URL",
                    "text": "summer2024"
                },
                {
                    "type": "FLOW",
                    "text": ""
                },
                {
                    "type": "COPY_CODE",
                    "text": "codeA"
                },
                {
                    "type": "QUICK_REPLY",
                    "text": ""
                }
            ]
        }

完整模板参数示例

以下示例展示了如何构建并传递模板消息所需的全部参数。

组件 模板内容
标头 (Header) 位置标头。
正文 (Body) 正文文本包含活动详情：
You are invited to our {{campaign}}!
Show this code at the entrance to get your exclusive gift: {{code}}
Event time: {{date}}
页脚 (Footer) 纯文本：
Remember to bring your code!
注： Footer 无需包含在参数中，系统会自动从模板中获取该内容。
按钮 (Button) 该模板包含以下按钮：
  • 一个快速回复按钮 Interest
  • 一个 URL 按钮，URL 末尾会拼接变量
    https://www.example.com/sales?promo={{1}}
在此场景中，msg_param / whatsapp_msg_param 参数的内容应为：
{
"id":1781,
"template_id":"1713250439356384",
"name":"summer_sale_event",
"language":{"code":"en"},
"components":
  [
    {                                             //位置标头
	  "type":"HEADER",
	  "parameters":
	    [
		 {
		   
		  "type":"LOCATION",
		  "location":
		    {
			  "name":"Madison Square Garden",
			  "address":"4 Pennsylvania Plaza, Suite 105, New York, NY 10001",
			  "latitude":"40.7505045",
			  "longitude":"-73.9934387"
			},
		 }
		]
    },
	{                                           //正文 - 命名参数
	  "type":"BODY",
	  "parameters":
	    [
		  {"type":"TEXT","text":"Summer Sale Event","parameter_name": "campaign"},
		  {"type":"TEXT","text":"AD8J398","parameter_name": "code"},
		  {"type":"TEXT","text":"2025-8-5","parameter_name": "date"}
		]
    },
	{                                            //按钮
	  "type":"BUTTONS",
	  "parameters":
	    [
		  {"type":"QUICK_REPLY","text":""},
		  {"type":"URL","text":"summer_2025"}
		]
    }
  ],
"parameter_format":"NAMED"
}

你需要将上述对象转换为转义后的 JSON 字符串，再作为 msg_param 或 whatsapp_msg_param 的值传递。

"msg_param":"{\"id\":1781,\"template_id\":\"1713250439356384\",\"name\":\"summer_sale_event\",\"language\":{\"code\":\"en\"},\"components\":[{\"type\":\"HEADER\",\"parameters\":[{\"type\":\"LOCATION\",\"location\":{\"name\":\"Madison Square Garden\",\"address\":\"4 Pennsylvania Plaza, Suite 105, New York, NY 10001\",\"latitude\":\"40.7505045\",\"longitude\":\"-73.9934387\"}}]},{\"type\":\"BODY\",\"parameters\":[{\"type\":\"TEXT\",\"text\":\"Summer Sale Event\",\"parameter_name\":\"campaign\"},{\"type\":\"TEXT\",\"text\":\"AD8J398\",\"parameter_name\":\"code\"},{\"type\":\"TEXT\",\"text\":\"2025-8-5\",\"parameter_name\":\"date\"}]},{\"type\":\"BUTTONS\",\"parameters\":[{\"type\":\"QUICK_REPLY\",\"text\":\"\"},{\"type\":\"URL\",\"text\":\"summer_2025\"}]}],\"parameter_format\":\"NAMED\"}"