模板管理 API

概述

使用模板管理 API 可以对 WABA 的模板进行增删改查操作，并通过自定义标签对模板分组。本文档包含两类接口：

模板接口：获取模板列表、查询模板信息、上传示例媒体文件、创建模板、更新模板、删除模板。
标签接口：获取模板标签列表、创建模板标签、修改模板标签、删除模板标签、设置模板标签。标签在当前 API 密钥所属的 WABA 内生效，仅用于 EngageLab 侧的模板管理，不修改 WhatsApp 模板内容，不触发 Meta 重新审核。

调用验证

EngageLab REST API 采用 HTTP 基本认证的验证方式：HTTP Header（头）里加 Authorization：

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

此代码块在浮窗中显示

上述 base64_auth_string 的生成算法为：base64(dev_key:dev_secret)

Header 名称是 "Authorization"，值是 base64 转换过的 "username:password" 对（中间有个冒号）。
在 WhatsApp API 的场景里，username 是 DevKey，password 是 DevSecret。请在控制台-配置管理- API 密钥页面获取。

获取模板列表

调用地址

GET https://wa.api.engagelab.cc/v1/templates

请求参数

参数	类型	选项	说明
name	String	选填	模板名字，注意该字段使用的是模糊匹配
language_code	String	选填	模板语言，参见语言代码
category	String	选填	模板类别。 ● AUTHENTICATION：验证码 ● MARKETING：市场营销 ● UTILITY：实用通知
status	String	选填	模板状态： APPROVED - 审核通过 PENDING - 审核中 REJECTED - 审核拒绝 PENDING_DELETION - 删除中 DELETED - 已删除 DISABLED - 停用（被封禁） IN_APPEAL - 申诉中 PAUSED - 暂停使用开发者需要关注的主要是 APPROVED/PENDING/REJECTED/DISABLED
tag_id	String	选填	标签 ID，用于按标签筛选模板。取值规则：不传或传空字符串 - 不按标签筛选传标签 ID - 只返回设置了该标签的模板传 `ungrouped` - 只返回未设置任何标签的模板，不区分大小写

tag_id 与 name、language_code、category、status 等查询条件为 AND 关系，当前不支持一次传入多个标签。tag_id 格式不合法时返回错误码 3002，标签不存在或不属于当前 WABA 时返回错误码 4001。

注意：若 WABA 内存在名称为「未分组」或 ungrouped 的标签，按该标签筛选时须传入其数字标签 ID；直接传 ungrouped 一律按「筛选未设置标签的模板」处理。

请求示例

按标签筛选：

GET https://wa.api.engagelab.cc/v1/templates?tag_id=101

              
              GET https://wa.api.engagelab.cc/v1/templates?tag_id=101

此代码块在浮窗中显示

筛选未设置标签的模板：

GET https://wa.api.engagelab.cc/v1/templates?tag_id=ungrouped

              
              GET https://wa.api.engagelab.cc/v1/templates?tag_id=ungrouped

此代码块在浮窗中显示

返回参数

参数	类型	选项	说明
id	String	必填	模板 ID
name	String	必填	模板名字
language	String	必填	模板语言，参见语言代码。
category	String	必填	模板类别。 AUTHENTICATION MARKETING UTILITY
components	Object Array	必填	模板内容的组件，参考创建模板中的 components 对象
status	String	必填	模板状态： APPROVED - 审核通过 PENDING - 审核中 REJECTED - 审核拒绝 PENDING_DELETION - 删除中 DELETED - 已删除 DISABLED - 停用（被封禁） IN_APPEAL - 申诉中 PAUSED - 暂停使用开发者需要关注的主要是 APPROVED/PENDING/REJECTED/DISABLED
tags	Object Array	必填	当前模板设置的标签，未设置标签时返回空数组。 tags[].id - String，标签 ID tags[].name - String，标签名称

返回示例

// 一个 json 数组，数组中每一个对象都是模板信息 [ { "id": "406979728071589", // 模板id "name": "code", // 模板名称 "language": "zh_CN", // 模板语言 "status": "APPROVED", // 状态，APPROVED为审核通过可用 "category": "OTP", // 类别，目前支持 OTP/TRANSACTIONAL/MARKETING "components": [ // 模板具体内容，可包含 HEADER/BODY/FOOTER/BUTTON { "type": "HEADER", "format": "text", // 类型，支持 text/image/location/video/document，默认TEXT "text": "注册验证码" // 文本内容，当format为text时，为必选项 }, { "type": "BODY", "text": "您的验证码是 {{1}}，请于 5 分钟内输入。" // 两个大括号{{}}括起来的表示模板变量 } ], "tags": [ // 该模板设置的标签，未设置标签时为空数组 { "id": "101", "name": "物流通知" } ] }, ...... ]

              
              // 一个 json 数组，数组中每一个对象都是模板信息
[
    {
        "id": "406979728071589", // 模板id
        "name": "code", // 模板名称
        "language": "zh_CN", // 模板语言
        "status": "APPROVED", // 状态，APPROVED为审核通过可用
        "category": "OTP", // 类别，目前支持 OTP/TRANSACTIONAL/MARKETING
        "components": [ // 模板具体内容，可包含 HEADER/BODY/FOOTER/BUTTON
            {
                "type": "HEADER",
                "format": "text", // 类型，支持 text/image/location/video/document，默认TEXT
                "text": "注册验证码" // 文本内容，当format为text时，为必选项
            },
            {
                "type": "BODY",
                "text": "您的验证码是 {{1}}，请于 5 分钟内输入。" // 两个大括号{{}}括起来的表示模板变量
            }
        ],
        "tags": [ // 该模板设置的标签，未设置标签时为空数组
            {
                "id": "101",
                "name": "物流通知"
            }
        ]
    },
    ......
]

此代码块在浮窗中显示

查询模板信息

调用地址

GET https://wa.api.engagelab.cc/v1/templates/{template_id}

其中 {template_id} 为需要查询模板ID。

请求参数

NULL

请求示例

GET https://wa.api.engagelab.cc/v1/templates/406979728071589

              
              GET https://wa.api.engagelab.cc/v1/templates/406979728071589

此代码块在浮窗中显示

返回参数

参数	类型	选项	说明
id	String	必填	模板 ID
name	String	必填	模板名字
language	String	必填	模板语言，参见语言代码。
category	String	必填	模板类别。 OTP：一次性密码 MARKETING：市场营销 TRANSACTIONAL：交易事务注意：模板类别最晚在 2023 年 5 月 1 日更新为： AUTHENTICATION MARKETING UTILITY
components	Object Array	必填	模板内容的组件，参考创建模板中的 components 对象
status	String	必填	模板状态： APPROVED, IN_APPEAL, PENDING, REJECTED, PENDING_DELETION, DELETED, DISABLED, PAUSED, LIMIT_EXCEEDED
tags	Object Array	必填	当前模板设置的标签，未设置标签时返回空数组。 tags[].id - String，标签 ID tags[].name - String，标签名称

返回示例

{ "id": "406979728071589", // 模板id "name": "code", // 模板名称 "language": "zh_CN", // 模板语言 "status": "APPROVED", // 状态，APPROVED为审核通过可用 "category": "OTP", // 类别，目前支持 OTP/TRANSACTIONAL/MARKETING "components": [ // 模板具体内容，可包含 HEADER/BODY/FOOTER/BUTTON { "type": "HEADER", "format": "text", // 类型，支持 text/image/location/video/document，默认TEXT "text": "注册验证码" // 文本内容，当format为text时，为必选项 }, { "type": "BODY", "text": "您的验证码是 {{1}}，请于 5 分钟内输入。" // 两个大括号{{}}括起来的表示模板变量 } ], "tags": [ // 该模板设置的标签，未设置标签时为空数组 { "id": "101", "name": "物流通知" } ] }

              
              {
    "id": "406979728071589", // 模板id
    "name": "code", // 模板名称
    "language": "zh_CN", // 模板语言
    "status": "APPROVED", // 状态，APPROVED为审核通过可用
    "category": "OTP", // 类别，目前支持 OTP/TRANSACTIONAL/MARKETING
    "components": [ // 模板具体内容，可包含 HEADER/BODY/FOOTER/BUTTON
        {
            "type": "HEADER",
            "format": "text", // 类型，支持 text/image/location/video/document，默认TEXT
            "text": "注册验证码" // 文本内容，当format为text时，为必选项
        },
        {
            "type": "BODY",
            "text": "您的验证码是 {{1}}，请于 5 分钟内输入。" // 两个大括号{{}}括起来的表示模板变量
        }
    ],
    "tags": [ // 该模板设置的标签，未设置标签时为空数组
        {
            "id": "101",
            "name": "物流通知"
        }
    ]
}

此代码块在浮窗中显示

上传示例媒体文件

在创建或编辑包含多媒体（image、video、document）页眉的模板时，Meta 要求先将媒体文件上传到 Meta 官方服务器。本 API 提供将模板示例文件上传并获取 handle_id 的功能，该 ID 需填入创建/编辑模板接口的 header_handle 字段中。

调用地址

POST https://wa.api.engagelab.cc/v1/media/handles

请求参数

Content-Type: multipart/form-data

参数	类型	选项	说明
file	file	必填	示例媒体文件。大小限制 20 MB，格式要求参见媒体消息格式要求。

请求示例

POST '/v1/media/handles' --header 'Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0' --form 'file=@"/Users/demo/files/demopic.jpeg"'

              
              POST '/v1/media/handles' 
--header 'Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0' 
--form 'file=@"/Users/demo/files/demopic.jpeg"'

此代码块在浮窗中显示

返回参数

成功返回

字段	类型	选项	描述
handle_id	String	必选	Meta 返回的文件标识，用于创建/编辑模版时填入 `example.header_handle` 字段。

返回示例：

{ "handle_id": "4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlczcn4hxLC6tkwjasjD4WL6_i34tIisq0IdWNFFFj1KwJMRXPU4xwygHSJd4DHu1f19LcBBl2qeb8EuEcgnIUPYIQ:e:1682169041:4985146461608173:100084026087657:ARazr9kxfzKshJE4WpY" }

              
              {
    "handle_id": "4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlczcn4hxLC6tkwjasjD4WL6_i34tIisq0IdWNFFFj1KwJMRXPU4xwygHSJd4DHu1f19LcBBl2qeb8EuEcgnIUPYIQ:e:1682169041:4985146461608173:100084026087657:ARazr9kxfzKshJE4WpY"
}

此代码块在浮窗中显示

失败返回

HTTP 状态码为 4xx 或者 5xx，响应体包含字段如下：

字段	类型	选项	描述
code	int	必选	错误码
message	String	必选	错误详情

返回示例：

{ "code": 3002, "message": "whatsapp.template field must be set correctly when type is template" }

              
              {
    "code": 3002,
    "message": "whatsapp.template field must be set correctly when type is template"
}

此代码块在浮窗中显示

创建模板

调用地址

POST https://wa.api.engagelab.cc/v1/templates

调用示例

{ "name": "template_name", // 模板名称，允许同名模板，仅支持小写字母及数字及下划线 "language": "zh_CN", // 模板语言，同名模板下不允许同语言模板 "category": "OTP", // 类别，目前支持 OTP/TRANSACTIONAL/MARKETING "components": [ { // 模板内容 "type": "BODY", // 内容块，目前支持 HEADER/BODY/FOOTER/BUTTONS "text": "define var as {{1}}" // 具体文本，当body为text时不需要传format字段 "example": { "body_text": [ [ "var1" ] ] } }, { "type": "HEADER", "format": "image", // 内容类型，支持 text/image/video/document/location "example": { "header_handle": [ "https://jiguang.cn/demopic.jpg" ] } }, { "type": "FOOTER", "text": "footer only support text without variable" }, { "type": "BUTTONS", "buttons": [ { "type": "PHONE_NUMBER", // 按钮类型，支持 PHONE_NUMBER/URL/QUICK_REPLY "text": "this is a phone number", "phone_number": "8613800138000" } ] } ] }

              
              {
    "name": "template_name", // 模板名称，允许同名模板，仅支持小写字母及数字及下划线
    "language": "zh_CN", // 模板语言，同名模板下不允许同语言模板
    "category": "OTP", // 类别，目前支持 OTP/TRANSACTIONAL/MARKETING
    "components": [
        { // 模板内容
            "type": "BODY", // 内容块，目前支持 HEADER/BODY/FOOTER/BUTTONS
            "text": "define var as {{1}}" // 具体文本，当body为text时不需要传format字段
          "example": {
                "body_text": [
                    [
                        "var1"
                    ]
                ]
            }
        },
        {
            "type": "HEADER",
            "format": "image", // 内容类型，支持 text/image/video/document/location
            "example": {
                "header_handle": [
                    "https://jiguang.cn/demopic.jpg"
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "footer only support text without variable"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "PHONE_NUMBER", // 按钮类型，支持 PHONE_NUMBER/URL/QUICK_REPLY              
                    "text": "this is a phone number",
                    "phone_number": "8613800138000"
                }
            ]
        }
    ]
}

此代码块在浮窗中显示

请求参数

参数	类型	选项	说明
name	String	必填	模版名字，仅支持小写字母、数字及下划线，不超过 512 个字符。
language	String	必填	模版语言，参见语言代码。
category	String	必填	模版类别。 OTP：一次性密码 MARKETING：市场营销 TRANSACTIONAL：交易事务注意：模板类别最晚在 2023 年 5 月 1 日更新为： AUTHENTICATION MARKETING UTILITY
components	Object Array	必填	描述模板内容的组件，参考 components 对象说明；注意必须包含 type=BODY 的 components。

components 对象

本对象用于描述模板内容。模板分为「页眉 HEADER」「正文 BODY」「页脚 FOOTER」「按钮 BUTTONS」几个组件，使用 type 来指定，不同的组件类型支持的参数不同，如下：

header 组件整体是可选的，如果不需要设置页眉，请不要设置此组件

参数	类型	选项	说明
type	String	必填	组件类型，取值 HEADER
format	String	必填	页眉格式，取值：text、image、video、document，对应着文本、图片、视频、文件。
text	String	可选	页眉文本内容，当 format=text 时需设置此字段内容。页眉文本内容中可以设置变量，但仅支持设置 1 个变量，用 {{1}} 进行表示。
example	JSON Object	可选	页眉示例，当 text 包含变量或 format 为媒体类型时，此字段必填。参考 example 对象说明

example 对象说明

参数	类型	选项	说明
header_handle	String Array	可选	当 format 为 image、video、document 时必填。该字段不再支持传入媒体 URL，必须传入通过上传示例媒体文件 API 获取的 handle_id。
header_text	String Array	可选	当 format 为 text 且包含变量时，对此字段传入该变量的替换值。例如："header_text": ["var1"]

body 正文组件

body 组件是必填的，必须设置正文内容。

参数	类型	选项	说明
type	String	必填	组件类型，取值 BODY
text	String	必填	正文内容，最长不超过 1024 个字符，支持设置多个变量，变量由两个大括号加变量序号组成，序号序号需要从 1 开始，保持递增，如 {{1}} 和 {{2}} 。
example	JSON Object	可选	正文示例，Meta 审核人员将根据示例判断你的消息合规性。参考 example 对象说明，当 text 包含变量时，此字段必填。

example 对象说明

参数	类型	选项	说明
body_text	String Array	可选	当 text 包含变量时，需要对此字段传入所有变量的替换值，按变量序号的顺序依次填写。例如："body_text": [["var1","var2","var3"]]

footer 组件整体是可选的，如果不需要设置页脚，请不要设置此组件

参数	类型	选项	说明
type	String	必填	组件类型，取值 FOOTER
text	String	必填	页脚内容，只能设置纯文本内容，不能定义变量。

buttons 按钮组件

buttons 组件整体是可选的，如果不需要设置按钮，请不要设置此组件

参数	类型	选项	说明
type	String	必填	组件类型，取值 BUTTONS
buttons	Object Array	必填	按钮信息，参考 buttons 对象说明。

buttons 对象说明

参数	类型	选项	说明
type	String	必填	按钮类型，取值： QUICK_REPLY、URL、PHONE_NUMBER，对应：快速回复、浏览网站、拨打电话号码
text	String	必填	按钮上的文字说明，不能包含变量，为纯文本，最长 25 个字符
url	String	可选	当 type=URL 时必填，可以在网址的结尾设置变量，且仅支持设置 1 个变量，用 {{1}} 进行表示。
phone_number	String	可选	当 type=PHONE_NUMBER 时必填，不能包含变量，内容为包含国际区号的电话号码。
example	String Array	可选	当 type=QUICK_REPLY 和 type=URL 时必填例如："example": ["`https://www.website.com/dynamic-url-example`"]

验证码类型的特别说明

注意事项

针对身份验证类别（即 AUTHENTICATION）的模版：

在 Components 中请不要设置 HEADER 组件。
模版内容文本会根据模版的语言 language 字段自动进行本地化设置。
针对 ONE_TAP 跳转 App 的模式，目前仅支持安卓应用，且 必须在你的 App 中进行相关握手处理，详细使用教程请阅读官方文档-身份验证模板。
创建模版时提交的参数字段，与创建成功后 WhatsApp 侧记录的模版字段是不一致的，本质上 WhatsApp 侧会将该类别模版中的 BODY、FOOTER 以及 BUTTONS 做替换，所以下发模版消息时请特别注意，需要添加button 变量，具体参考消息下发 API 文档。

COPY_CODE 示例

提交的数据：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { // body 是必须的 "type": "BODY", "add_security_recommendation": true // 是否添加安全建议描述 }, { // footer 是可选的 "type": "FOOTER", "code_expiration_minutes": 2 // 添加过期时间显示，范围[1,90]，不添加则不传该字段 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "copy_code", "text": "copy it" // 长度限制 25 字符 } ] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            // body 是必须的
            "type": "BODY",
            "add_security_recommendation": true  // 是否添加安全建议描述
            
        },
        {
            // footer 是可选的
            "type": "FOOTER",		
            "code_expiration_minutes": 2    // 添加过期时间显示，范围[1,90]，不添加则不传该字段
        },
        {
            "type": "BUTTONS",          
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "copy_code",
                    "text": "copy it"      // 长度限制 25 字符
                }
            ]
        }
    ]
}

此代码块在浮窗中显示

创建成功后，WhatsApp 侧实际得到的模版内容：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "text": "*{{1}}* 是你的验证码。为安全起见，请不要分享这组验证码。", "example": { "body_text": [ ["123456"] ] } }, { "type": "FOOTER", "text": "这组验证码将在 2 分钟后过期。" }, { "type": "BUTTONS", "buttons": [{ "type": "URL", "text": "Copy code", "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}", "example": [ "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456" ] }] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "text": "*{{1}}* 是你的验证码。为安全起见，请不要分享这组验证码。",
            "example": {
                "body_text": [
                    ["123456"]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "这组验证码将在 2 分钟后过期。"
        },
        {
            "type": "BUTTONS",
            "buttons": [{
              "type": "URL",
              "text": "Copy code",
              "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}",
              "example": [
                  "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456"
              ]
          }]
        }
    ]
}

此代码块在浮窗中显示

ONE_TAP 示例

提交的数据：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { // body是必须的 "type": "BODY", "add_security_recommendation": true // 是否添加安全建议描述 }, { // footer是可选的 "type": "FOOTER", "code_expiration_minutes": 2 // 添加过期时间显示，范围[1,90]，不添加则不传该字段 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "one_tap", "text": "auto1", // 长度限制25字符 "autofill_text": "auto1", // 长度限制25字符 "package_name": "ppssd", "signature_hash": "asds" } ] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            // body是必须的
            "type": "BODY",
            "add_security_recommendation": true  // 是否添加安全建议描述
            
        },
        {
            // footer是可选的
            "type": "FOOTER",		
            "code_expiration_minutes": 2    // 添加过期时间显示，范围[1,90]，不添加则不传该字段
        },
        {
            "type": "BUTTONS",          
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "one_tap",
                    "text": "auto1",      // 长度限制25字符
                    "autofill_text": "auto1",      // 长度限制25字符
                    "package_name": "ppssd",    
                    "signature_hash": "asds"  
                }
            ]
        }
    ]
}

此代码块在浮窗中显示

创建成功后，WhatsApp 侧实际得到的模版内容：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "text": "*{{1}}* 是你的验证码。为安全起见，请不要分享这组验证码。", "example": { "body_text": [ ["123456"] ] } }, { "type": "FOOTER", "text": "这组验证码将在 2 分钟后过期。" }, { "type": "BUTTONS", "buttons": [{ "type": "URL", "text": "copy1", "url": "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP\u0026cta_display_name=auto1\u0026package_name=ppssd\u0026signature_hash=asds\u0026code=otp{{1}}", "example": ["https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP\u0026cta_display_name=auto1\u0026package_name=ppssd\u0026signature_hash=asds\u0026code=otp123456"] }] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "text": "*{{1}}* 是你的验证码。为安全起见，请不要分享这组验证码。",
            "example": {
                "body_text": [
                    ["123456"]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "这组验证码将在 2 分钟后过期。"
        },
        {
            "type": "BUTTONS",
            "buttons": [{
                "type": "URL",
                "text": "copy1",
                "url": "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP\u0026cta_display_name=auto1\u0026package_name=ppssd\u0026signature_hash=asds\u0026code=otp{{1}}",
                "example": ["https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP\u0026cta_display_name=auto1\u0026package_name=ppssd\u0026signature_hash=asds\u0026code=otp123456"]
            }]
        }
    ]
}

此代码块在浮窗中显示

返回参数

成功返回

参数	类型	选项	说明
template_id	String	必填	模板 ID，成功时返回

{ "template_id": "1275172986566180" // 模板id }

              
              {
    "template_id": "1275172986566180"		// 模板id
}

此代码块在浮窗中显示

失败返回

参数	类型	选项	说明
code	int	必填	错误码，失败时返回
message	String	必填	错误信息，失败时返回

{ "code": 5002, "message": "Invalid parameter. code:100:2388042" }

              
              {
    "code": 5002,
    "message": "Invalid parameter. code:100:2388042"
}

此代码块在浮窗中显示

更新模板

调用地址

PUT https://wa.api.engagelab.cc/v1/templates/{templateId}

调用示例

{ "components": [{ // 模板内容 "type": "BODY", // 内容块 "text": "define var as {{1}}", "example": { "body_text": [["var1"]] } },{ "type": "HEADER", "format": "image", // 内容类型：image/video/document "example": { // 注意：此处必须填入上传接口返回的 handle_id，不再支持直接填写图片 URL "header_handle": ["4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlcz..."] } },{ "type": "FOOTER", "text": "footer only support text without variable" },{ "type": "BUTTONS", "buttons": [{ "type": "PHONE_NUMBER", "text": "this is a phone number", "phone_number": "8613800138000" }] }] }

              
              {
    "components": [{                        // 模板内容
        "type": "BODY",                     // 内容块
        "text": "define var as {{1}}", 
        "example": {
            "body_text": [["var1"]]
        }
    },{
        "type": "HEADER",
        "format": "image",                  // 内容类型：image/video/document
        "example": {
            // 注意：此处必须填入上传接口返回的 handle_id，不再支持直接填写图片 URL
            "header_handle": ["4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlcz..."]
        }
    },{
        "type": "FOOTER",
        "text": "footer only support text without variable"
    },{
        "type": "BUTTONS",
        "buttons": [{                                     
            "type": "PHONE_NUMBER",              
            "text": "this is a phone number",              
            "phone_number": "8613800138000"
        }]
    }]
}

此代码块在浮窗中显示

请求参数

同创建模版接口的请求参数。

返回参数

成功返回

参数	类型	选项	说明
code	int	必填	返回码，固定为 0
message	String	必填	返回信息，固定为success

{ "code": 0, "message": "success" }

              
              {
    "code": 0,
    "message": "success"
}

此代码块在浮窗中显示

失败返回

参数	类型	选项	说明
code	int	必填	错误码，失败时返回
message	String	必填	错误信息，失败时返回

{ "code": 5002, "message": "Invalid parameter. code:100:2593002" }

              
              {
    "code": 5002,
    "message": "Invalid parameter. code:100:2593002"
}

此代码块在浮窗中显示

删除模板

调用地址

DELETE https://wa.api.engagelab.cc/v1/templates/{template_name}
注意：此处传递的是模板名称并非模板 ID，将删除该模板名称的所有语言的模板内容

返回参数

成功返回

参数	类型	选项	说明
code	int	必填	返回码，固定为 0
message	String	必填	返回信息，固定为success

{ "code": 0, "message": "success" }

              
              {
    "code": 0,
    "message": "success"
}

此代码块在浮窗中显示

失败返回

参数	类型	选项	说明
code	int	必填	错误码，失败时返回
message	String	必填	错误信息，失败时返回

{ "code": 2004, "message": "something error" }

              
              {
    "code": 2004,
    "message": "something error"
}

此代码块在浮窗中显示

获取模板标签列表

返回当前 API 密钥所属 WABA 下的全部标签，不分页。

调用地址

GET https://wa.api.engagelab.cc/v1/template-tags

请求参数

NULL

请求示例

GET https://wa.api.engagelab.cc/v1/template-tags

              
              GET https://wa.api.engagelab.cc/v1/template-tags

此代码块在浮窗中显示

返回参数

参数	类型	选项	说明
id	String	必填	标签 ID
name	String	必填	标签名称
template_count	Integer	必填	当前 WABA 内设置了该标签的模板数量。同名多语言模板按模板 ID 分别计数

返回示例

[ { "id": "101", "name": "物流通知", "template_count": 3 }, { "id": "102", "name": "售后客服", "template_count": 0 } ]

              
              [
    {
        "id": "101",
        "name": "物流通知",
        "template_count": 3
    },
    {
        "id": "102",
        "name": "售后客服",
        "template_count": 0
    }
]

此代码块在浮窗中显示

WABA 下无标签时返回空数组 []。

创建模板标签

调用地址

POST https://wa.api.engagelab.cc/v1/template-tags

请求参数

参数	类型	选项	说明
name	String	必填	标签名称，长度 1～64 个字符，命名要求参见标签名称规则。

请求示例

{ "name": "物流通知" }

              
              {
    "name": "物流通知"
}

此代码块在浮窗中显示

返回参数

成功返回

参数	类型	选项	说明
id	String	必填	标签 ID
name	String	必填	规范化后的标签名称

{ "id": "101", "name": "物流通知" }

              
              {
    "id": "101",
    "name": "物流通知"
}

此代码块在浮窗中显示

失败返回

参数	类型	选项	说明
code	int	必填	错误码，失败时返回
message	String	必填	错误信息，失败时返回

{ "code": 3003, "message": "template tag name already exists" }

              
              {
    "code": 3003,
    "message": "template tag name already exists"
}

此代码块在浮窗中显示

修改模板标签

调用地址

PUT https://wa.api.engagelab.cc/v1/template-tags/{tag_id}

其中 {tag_id} 为需要修改的标签 ID。

请求参数

参数	类型	选项	说明
name	String	必填	新的标签名称，长度 1～64 个字符，命名要求参见标签名称规则。

请求示例

{ "name": "售后客服" }

              
              {
    "name": "售后客服"
}

此代码块在浮窗中显示

返回参数

成功返回

参数	类型	选项	说明
id	String	必填	标签 ID
name	String	必填	修改后的标签名称

{ "id": "101", "name": "售后客服" }

              
              {
    "id": "101",
    "name": "售后客服"
}

此代码块在浮窗中显示

失败返回

参数	类型	选项	说明
code	int	必填	错误码，失败时返回
message	String	必填	错误信息，失败时返回

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

此代码块在浮窗中显示

删除模板标签

调用地址

DELETE https://wa.api.engagelab.cc/v1/template-tags/{tag_id}
注意：删除标签仅解除模板与该标签的关联，不删除模板，不影响模板发送

其中 {tag_id} 为需要删除的标签 ID。

请求参数

NULL

请求示例

DELETE https://wa.api.engagelab.cc/v1/template-tags/101

              
              DELETE https://wa.api.engagelab.cc/v1/template-tags/101

此代码块在浮窗中显示

返回参数

成功返回

参数	类型	选项	说明
affected_template_count	Integer	必填	本次解除关联的模板数量。同名多语言模板按模板 ID 分别计数

{ "affected_template_count": 3 }

              
              {
    "affected_template_count": 3
}

此代码块在浮窗中显示

失败返回

参数	类型	选项	说明
code	int	必填	错误码，失败时返回
message	String	必填	错误信息，失败时返回

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

此代码块在浮窗中显示

设置模板标签

调用地址

PUT https://wa.api.engagelab.cc/v1/templates/{template_id}/tags
注意：本接口为全量覆盖，tag_ids 传入的是模板保存后的完整标签集合，未包含在内的原有标签将被解除关联

其中 {template_id} 为需要设置标签的模板 ID。

请求参数

参数	类型	选项	说明
tag_ids	String Array	必填	模板保存后的完整标签 ID 集合，须显式传入且不能为 `null`。所有 ID 须属于当前 WABA，重复 ID 自动去重。

tag_ids 取值说明：

传入 [] 表示清空该模板的全部标签。
未传 tag_ids 或传入 null 时请求失败，不会清空原有标签。
请求失败时模板的标签集合保持不变，可直接重试。
不限制单个模板的标签数量，可传入当前 WABA 的全部标签。

请求示例

{ "tag_ids": ["101", "102"] }

              
              {
    "tag_ids": ["101", "102"]
}

此代码块在浮窗中显示

返回参数

成功返回

参数	类型	选项	说明
code	int	必填	返回码，固定为 0
message	String	必填	返回信息，固定为 success

{ "code": 0, "message": "success" }

              
              {
    "code": 0,
    "message": "success"
}

此代码块在浮窗中显示

失败返回

参数	类型	选项	说明
code	int	必填	错误码，失败时返回
message	String	必填	错误信息，失败时返回

模板不存在或不属于当前 WABA：

{ "code": 4001, "message": "template not found" }

              
              {
    "code": 4001,
    "message": "template not found"
}

此代码块在浮窗中显示

标签不存在或不属于当前 WABA：

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

此代码块在浮窗中显示

未传 tag_ids 或传入 null：

{ "code": 3002, "message": "template tag IDs must be provided as an array" }

              
              {
    "code": 3002,
    "message": "template tag IDs must be provided as an array"
}

此代码块在浮窗中显示

错误码

下表中的「标签接口」即概述中列出的五个标签接口，另包含获取模板列表中传入 tag_id 筛选的场景。

错误码	http code	适用接口	说明
1000	500	全部接口	内部错误
2001	401	全部接口	EngageLab 侧鉴权失败，未携带有效数据格式的 token
2002	401	全部接口	EngageLab 侧鉴权失败，token 已过期或已被禁用
2003	400	全部接口	WhatsApp 侧鉴权失败，请联系 EngageLab 客服处理
2004	403	全部接口	无调用此 API 的权限，或相关账号、WABA 已被禁用
3001	400	全部接口	请求参数格式无效，请检查是否采用 JSON 格式，以及字段类型是否符合要求
3002	400	全部接口	请求参数有误，请检查请求参数是否符合要求
3002	400	标签接口	标签名称为空
3002	400	标签接口	标签名称超过 64 个字符，参见标签名称规则
3002	400	标签接口	标签名称包含不允许的字符，参见标签名称规则
3002	400	标签接口	标签 ID 格式无效，须为正整数字符串
3002	400	标签接口	设置模板标签时未传 tag_ids，或其值为 null
3003	400	全部接口	请求参数有误，相关业务校验失败
3003	400	标签接口	同一 WABA 内已存在相同的标签名称，判重时不区分大小写和重音符号
3003	400	标签接口	单个 WABA 的标签数量已达到 20 个上限
3003	400	标签接口	标签操作繁忙，稍后重试即可，重试不会产生重复数据
4001	400	全部接口	模板不存在或不属于当前 WABA
4001	400	标签接口	标签不存在或不属于当前 WABA
5002	400	全部接口	模板请求在 Meta 处理失败，详情参考 message 字段的错误描述

注释

媒体消息格式要求

媒体类型	支持的格式类型 Content-Type	大小限制
image	image/jpeg, image/png，不支持透明背景	5 MB
video	video/mp4	16MB
document	仅支持 PDF 格式	100 MB

标签名称规则

创建和修改标签时，服务端先对名称做规范化处理，再校验长度和重复。

规范化：去除首尾空白，并将名称中连续的空白字符合并为一个空格。例如提交 " 物流通知 "，实际保存和返回的名称为 "物流通知"。

字符限制：允许空格、下划线、短横线、各语言的可见字符和 emoji；不允许换行符、制表符、控制字符和不可见格式字符。

长度：规范化后须为 1～64 个字符。长度按 Unicode 码点计算，一个 emoji 可能占用多个码点。

判重：同一 WABA 内名称不可重复，判重时不区分大小写和重音符号，例如 Logistics、logistics、Logístics 视为同一名称。无保留词限制。

标签使用限制

单个 WABA 最多创建 20 个标签。
不限制单个模板的标签数量，可设置当前 WABA 已有的全部标签，因此实际上限为 20 个。
标签 ID 在请求和返回中均为字符串（如 "101"），请勿按数字类型解析。
同名多语言模板按各自的模板 ID 独立设置标签，例如同一模板的中英文版本需要分别设置。
标签不写入 Meta，不修改模板状态和质量评分，不触发重新审核。

语言代码

语言	Code
南非荷兰语	af
阿尔巴尼亚语	sq
阿拉伯语	ar
阿塞拜疆	az
孟加拉语	bn
保加利亚语	bg
加泰罗尼亚语	ca
中文（中国大陆）	zh_CN
中文（香港）	zh_HK
中文（台湾）	zh_TW
克罗地亚语	hr
捷克语	cs
丹麦语	da
荷兰语	nl
英语	en
英语（英国）	en_GB
英语（美国）	en_US
爱沙尼亚语	et
菲律宾语	fil
芬兰语	fi
法语	fr
格鲁吉亚语	ka
德语	de
希腊语	el
古吉拉特语	gu
豪萨语	ha
希伯来语	he
印地语	hi
匈牙利语	hu
印尼语	id
爱尔兰语	ga
意大利语	it
日语	ja
卡纳达语	kn
哈萨克语	kk
卢旺达	rw_RW
韩语	ko
吉尔吉斯斯坦	ky_KG
老挝语	lo
拉脱维亚语	lv
立陶宛语	lt
马其顿语	mk
马来语	ms
马拉雅拉姆语	ml
马拉地语	mr
挪威语	nb
波斯语	fa
波兰语	pl
葡萄牙语（巴西）	pt_BR
葡萄牙语（葡萄牙）	pt_PT
旁遮普语	pa
罗马尼亚语	ro
俄语	ru
塞尔维亚语	sr
斯洛伐克语	sk
斯洛文尼亚语	sl
西班牙语	es
西班牙语（阿根廷）	es_AR
西班牙语（西班牙）	es_ES
西班牙语（墨西哥）	es_MX
斯瓦希里语	sw
瑞典语	sv
泰米尔语	ta
泰卢固语	te
泰语	th
土耳其语	tr
乌克兰语	uk
乌尔都语	ur
乌兹别克语	uz
越南语	vi
祖鲁语	zu

相关语言和对应代码的对应关系，也可以下载本文件查看：
模板语言代码.xlsx

概述

调用验证

获取模板列表

调用地址

请求参数

请求示例

返回参数

返回示例

查询模板信息

调用地址

请求参数

请求示例

返回参数

返回示例

上传示例媒体文件

调用地址

请求参数

请求示例

返回参数

成功返回

失败返回

创建模板

调用地址

调用示例

请求参数

components 对象

header 页眉组件

example 对象说明

body 正文组件

example 对象说明

footer 页脚组件

buttons 按钮组件

buttons 对象说明

验证码类型的特别说明

注意事项

COPY_CODE 示例

ONE_TAP 示例

返回参数

成功返回

失败返回

更新模板

调用地址

调用示例

请求参数

返回参数

成功返回

失败返回

删除模板

调用地址

返回参数

成功返回

失败返回

获取模板标签列表

调用地址

请求参数

请求示例

返回参数

返回示例

创建模板标签

调用地址

请求参数

请求示例

返回参数

成功返回

失败返回

修改模板标签

调用地址

请求参数

请求示例

返回参数

成功返回

失败返回

删除模板标签

调用地址

请求参数

请求示例

返回参数

成功返回

失败返回