模板管理 API
概述
使用模板管理 API 可以对 WABA 的模板进行增删改查操作。
调用验证
EngageLab REST API 采用 HTTP 基本认证 的验证方式:HTTP Header(头)里加 Authorization:
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/DISABLED |
返回参数
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
id | String | 必填 | 模板 ID |
name | String | 必填 | 模板名字 |
language | String | 必填 | 模板语言,参见 语言代码 。 |
category | String | 必填 | 模板类别。 |
components | Object Array | 必填 | 模板内容的组件,参考 创建模板中的 components 对象 |
status | String | 必填 | 模板状态: 开发者需要关注的主要是 APPROVED/PENDING/REJECTED/DISABLED |
返回示例
// 一个 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 分钟内输入。" // 两个大括号{{}}括起来的表示模板变量
}
]
},
......
]
查询模板信息
调用地址
GET https://wa.api.engagelab.cc/v1//{template_id}
其中 {template_id} 为需要查询模板ID。
请求参数
NULL
请求示例
GET https://wa.api.engagelab.cc/v1/templates/406979728071589
返回参数
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
id | String | 必填 | 模板 ID |
name | String | 必填 | 模板名字 |
language | String | 必填 | 模板语言,参见 语言代码 。 |
category | String | 必填 | 模板类别。 注意:模板类别最晚在 2023 年 5 月 1 日更新为: |
components | Object Array | 必填 | 模板内容的组件,参考 创建模板中的 components 对象 |
status | String | 必填 | 模板状态: APPROVED, IN_APPEAL, PENDING, REJECTED, PENDING_DELETION, DELETED, DISABLED, PAUSED, LIMIT_EXCEEDED |
返回示例
{
"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 分钟内输入。" // 两个大括号{{}}括起来的表示模板变量
}
]
}
创建模板
调用地址
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 | String | 必填 | 模版名字,仅支持小写字母、数字及下划线,不超过 512 个字符。 |
language | String | 必填 | 模版语言,参见 语言代码 。 |
category | String | 必填 | 模版类别。 注意:模板类别最晚在 2023 年 5 月 1 日更新为: |
components | Object Array | 必填 | 描述模板内容的组件,参考 components 对象 说明;注意必须包含 type=BODY 的 components。 |
components 对象
本对象用于描述模板内容。模板分为「页眉 HEADER」「正文 BODY」「页脚 FOOTER」「按钮 BUTTONS」几个组件,使用 type 来指定,不同的组件类型支持的参数不同,如下:
header 页眉组件
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,且 url 能被访问,否则模版审核可能被拒绝。 例如:"header_handle": [" https://jiguang.cn/demopic.jpg "] |
header_text | String Array | 可选 | 当 format 为 text 且包含变量时,对此字段传入该变量的替换值。例如:"header_text": ["var1"] |
header_url | String Array | 可选 | 与header_handle的用法一致,注意此字段在 WhatsApp 未来的版本中将不再支持,尽量避免使用。 例如:"header_url": [" https://jiguang.cn/demopic.jpg "] |
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 页脚组件
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 字符
}
]
}
]
}
创建成功后,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"
]
}]
}
]
}
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"
}
]
}
]
}
创建成功后,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"]
}]
}
]
}
返回参数
成功返回
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
template_id | String | 必填 | 模板 ID,成功时返回 |
{
"template_id": "1275172986566180" // 模板id
}
失败返回
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
code | int | 必填 | 错误码,失败时返回 |
message | String | 必填 | 错误信息,失败时返回 |
{
"code": 5002,
"message": "Invalid parameter. code:100:2388042"
}
更新模板
调用地址
PUT https://wa.api.engagelab.cc/v1/templates/{templateId}
调用示例
{
"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_url": ["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"
}]
}]
}
请求参数
同创建模版接口的 请求参数。
返回参数
成功返回
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
code | int | 必填 | 返回码,固定为 0 |
message | String | 必填 | 返回信息,固定为success |
{
"code": 0,
"message": "success"
}
失败返回
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
code | int | 必填 | 错误码,失败时返回 |
message | String | 必填 | 错误信息,失败时返回 |
{
"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 | int | 必填 | 错误码,失败时返回 |
message | String | 必填 | 错误信息,失败时返回 |
{
"code": 2004,
"message": "something error"
}
错误码
错误码 | http code | 说明 |
---|---|---|
1000 | 500 | 内部错误 |
2001 | 401 | EngageLab 侧鉴权失败,未携带有效数据格式的 token |
2002 | 401 | EngageLab 侧鉴权失败,token已过期或已被禁用 |
2003 | 400 | WhatsApp 侧鉴权失败,请联系 EngageLab 客服处理 |
2004 | 403 | 无调用此 API 的权限 |
3001 | 400 | 请求参数格式无效,请检查是否采用 JSON 格式 |
3002 | 400 | 请求参数有误,请检查请求参数是否符合要求 |
3003 | 400 | 请求参数有误,相关业务校验失败 |
4001 | 400 | 模板不存在 |
5002 | 400 | 模板请求在 Meta 处理失败,详情参考 message 字段的错误描述 |
注释
媒体消息格式要求
媒体类型 | 支持的格式类型 Content-Type | 大小限制 |
---|---|---|
image | image/jpeg, image/png,不支持透明背景 | 5 MB |
video | video/mp4 | 16MB |
document | 仅支持 PDF 格式 | 100 MB |
语言代码
语言 | 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