创建消息模板
在WhatsApp应用下的指定的单个号码创建新的消息模板。
需要注意的是,如果创建模板时使用了富媒体交互模板,需要同时提交富媒体示例文件,富媒体示例文件通过“模板示例媒体上传”API接口上传。
- URL:
https://api2.nxcloud.com/api/wa/createTemplate
- Method:
POST
- Content-Type:
application/json
- 需要鉴权:
是
鉴权机制
鉴权规则请参考地址:API接口调用约定
请求参数
header参数:
参数名 |
类型 |
必选 |
示例值 |
说明 |
accessKey |
String |
是 |
fmexxx3ki |
用户身份标识 |
ts |
String |
是 |
1655710885431 |
当前请求的时间戳(单位是毫秒),牛信服务端允许用户端请求最大时间误差为60秒 |
bizType |
String |
是 |
2 |
WhatsApp业务类型,取固定值“2” |
action |
String |
是 |
createTemplate |
WhatsApp业务操作,取固定值“createTemplate” |
sign |
String |
是 |
6e95xxx826 |
API入参参数签名,签名算法 |
body参数:
参数名 |
类型 |
必选 |
示例值 |
说明 |
appkey |
String |
是 |
|
牛信云WhatsApp应用的appkey |
business_phone |
String |
是 |
86158xxx1795 |
商户的WhatsApp号码列表,需要带国码,如185xxx99 |
messaging_product |
String |
是 |
whatsapp |
发送消息的通道,应用于WhatsApp消息的发送时,值必须为“whatsapp” |
category |
String |
是 |
MARKETING |
模板类型 枚举值: "MARKETING" : "包括促销或优惠、信息更新或邀请客户回应/采取行动的信息。任何不符合效用或身份验证用途均为营销","UTILITY" : "促成商定的某个具体请求或交易,或向客户提供与进行中的交易相关的最新信息,包括售后通知和定期账单","AUTHENTICATION" :"使商家可以使用一次性密码验证用户身份,可能会在登录过程的多个步骤中出现(如帐号认证、帐号找回、诚信挑战)" |
language |
String |
是 |
zh_CN |
语言编码,例如zh_CN |
name |
String |
是 |
|
模板名称 |
message_send_ttl_seconds |
int |
否 |
|
模板发送的过期时间.针对身份验证模板,将该参数设为 30 到 900 秒(即 30秒 到 15 分钟);针对交易相关模板,将该参数设为 30 至 43200 秒(30 秒至 12 小时);针对营销相关模板,将该参数设为 43200 至 2592000 秒(12 小时至 30 天) |
components |
array[component object] |
是 |
|
模板组件 |
参数名 |
类型 |
是否必须 |
说明 |
type |
string |
必须 |
组件类型,取值包括:HEADER, BODY, FOOTER, BUTTONS,CAROUSEL |
format |
string |
必须/无 |
仅type= HEADER时有此项且为必须项,type!=HEADER时,无此项。描述HEADER里内容的类型。取值范围包括:TEXT,DOCUMENT,IMAGE, VIDEO |
text |
string |
必须/无 |
type= HEADER且format=text时,为必须项;type=BODY时,为必须项;type=FOOTER时,为必须项;type=BUTTONS时,无此项。 |
example |
object |
必须/无 |
变量示例,当HEADER或者BODY内容中配置了变量时,为必须项。否则无此项。 |
buttons |
array[button object] |
必须/无 |
仅type=BUTTONS时,为必须项,否则无此项。 |
add_security_recommendation |
boolean |
必须/无 |
添加安全建议 身份验证模板 type = BODY 时可选 值为 true/false。 |
code_expiration_minutes |
integer |
必须/无 |
验证码的失效时间 身份验证模板 type = FOOTER 时可选 值的可填范围是 1-90。 |
cards |
array[card object] |
必须/无 |
仅type=CAROUSEL 必填,轮播模板卡片. |
参数名 |
类型 |
是否必须 |
说明 |
components |
array[component object] |
必须/无 |
轮播模板组件. 且component的type取值为HEADER, BODY, BUTTONS. |
参数名 |
类型 |
是否必须 |
说明 |
header_handle |
string |
必须/无 |
当HEADER中 format=DOCUMENT或format=IMAGE或format=VIDEO时,与custom_header_handle_url二选一,否则无此项,如果与custom_header_handle_url同时存在时,以custom_header_handle_url为准。上传文件模板示例 获取 header_handle 值 |
custom_header_handle_url |
string |
必须/无 |
当HEADER中 format=DOCUMENT或format=IMAGE或format=VIDEO时,与header_handle二选一,否则无此项,示例媒体url建议小于1M,否则会超时。如果与header_handle同时存在时,以custom_header_handle_url为准 |
header_text |
array[string] |
必须/无 |
当HEADER中 format=TEXT时为必须项,否则无此项 |
body_text |
array[array[string]] |
必须/无 |
当BODY内容文本中配置了变量时为必须项,根据变量配置,数组中可能有1个或多个值。当BODY内容文本中未配置变量则无此项。 |
参数名 |
类型 |
是否必须 |
说明 |
type |
string |
必须/无 |
按钮类型,包括QUICK_REPLY, URL , PHONE_NUMBER,COPY_CODE,FLOW . 1. QUICK_REPLY即快速回复按钮;2. URL即行动号召url按钮;3. PHONE_NUMBER即行动号召phone_number按钮; 4. COPY_CODE 复制优化码 5. FLOW |
text |
string |
必须 |
按钮的显示文字 |
url |
string |
必须/无 |
行动号召按钮上配置的网址,仅type=URL时为必须项。如果是动态url,则需带上后缀变量{{1}}。 |
phone_number |
string |
必须/无 |
行动号召按钮上配置的电话,仅type= PHONE_NUMBER时为必须项 |
example |
array[string] |
必须/无 |
type=URL,且为动态url时为必须项,例如:https://www.baidu.com/user type=COPY_CODE,为必填项,并且类型为String |
otp_type |
string |
必须/无 |
验证码按钮类型 固定值 ONE_TAP 或者 COPY_CODE ;ONE_TAP的含义是一键填充 COPY_CODE的含义是复制验证码 |
autofill_text |
string |
必须/无 |
自动填充按钮文本,展示在按钮上的文案,仅otp_type = ONE_TAP 时为必须项 |
package_name |
string |
必须/无 |
安卓包名,仅otp_type = ONE_TAP 时为必须项 |
signature_hash |
string |
必须/无 |
应用hash,仅otp_type = ONE_TAP 时为必须项 |
flow_id |
string |
必须/无 |
当type =Flow时有值, WhatsApp 提供的流程的唯一标识符。流程必须已发布 |
flow_action |
string |
必须/无 |
当type =Flow时有值, navigate 或 data_exchange 默认:navigate |
navigate_screen |
string |
必须/无 |
当type =Flow时有值, 仅在 flow_action 为 navigate 时,此为必要项。流程的第一个屏幕的. |
请求示例
- 普通文本模板
body(application/json) 参数:
{
"appkey": "8eoxxxos",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"name": "normal_text",
"category": "MARKETING",
"language": "zh_CN",
"components": [
{
"type": "BODY",
"text": "hello world"
}
]
}
- 丰富模板
body(application/json) 参数:
{
"appkey": "8exxxos",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"name": "normal_text3",
"category": "MARKETING",
"language": "en_US",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "ni{{1}}hao",
"example": {
"header_text": [
"AA"
]
}
},
{
"type": "BODY",
"text": "hello{{1}}world{{2}}hahah",
"example": {
"body_text": [
[
"BB",
"CC"
]
]
}
},
{
"type": "FOOTER",
"text": "I am footer"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "I am QR1"
},
{
"type": "QUICK_REPLY",
"text": "I am QR2"
}
]
}
]
}
- header带有媒体模板
body(application/json) 参数:
{
"appkey": "8exxxos",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"name": "otp_1",
"category": "MARKETING",
"language": "en_US",
"components": [{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": "4:ZG93bl93YS5xxxg"
}
},
{
"type": "BODY",
"text": "hello{{1}}world{{2}}hahah",
"example": {
"body_text": [
[
"BB",
"CC"
]
]
}
},
{
"type": "FOOTER",
"text": "I am footer"
},
{
"type": "BUTTONS",
"buttons": [{
"type": "QUICK_REPLY",
"text": "I am QR1"
},
{
"type": "QUICK_REPLY",
"text": "I am QR2"
}
]
}
]
}
{
"appkey": "8exxxs",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"category": "MARKETING",
"name": "mkt_cpoy_code",
"language": "zh_CN",
"components": [
{
"type": "BODY",
"text": "hello world"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "COPY_CODE",
"example": "250FF"
}
]
}
]
}
{
"appkey": "8exxxs",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"category": "MARKETING",
"name": "mkt_flow",
"language": "zh_CN",
"components": [
{
"type": "BODY",
"text": "hello world"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "FLOW",
"text": "Flow Demo",
"flow_id": "1090xxxxxx438317",
"flow_action": "navigate",
"navigate_screen": "WELCOME_SCREEN"
}
]
}
]
}
- 简单MARKETING模板
body(application/json) 参数:
{
"appkey": "8exxxs",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"name": "otp_test",
"category": "MARKETING",
"language": "en",
"components": [
{
"type": "BODY",
"text": "Your code is {{1}}, please do not share with others.",
"example": {
"body_text": [
[
"10086"
]
]
}
}
]
}
{
"appkey": "8exxxs",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"category": "AUTHENTICATION",
"name": "otp_test_01",
"language": "zh_CN",
"components": [
{
"type": "BODY",
"add_security_recommendation": true
},
{
"type": "FOOTER",
"code_expiration_minutes": 5
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "COPY_CODE",
"text": "Copy Code"
}
]
}
]
}
{
"appkey": "8exxxs",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"category": "AUTHENTICATION",
"name": "otp_test_02",
"language": "zh_CN",
"components": [
{
"type": "BODY",
"add_security_recommendation": true
},
{
"type": "FOOTER",
"code_expiration_minutes": 5
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "ONE_TAP",
"text": "Copy Code2",
"autofill_text": "Autofill2",
"package_name": "com.example.myapplication",
"signature_hash": "K8a%2FAINcGX7"
}
]
}
]
}
{
"appkey": "8exxxs",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"name": "carousel_template_media_cards_v1",
"language": "en_US",
"category": "marketing",
"components": [
{
"type": "body",
"text": "Rare succulents for sale! {{1}}, add these unique plants to your collection. Each of these rare succulents are {{2}} if you checkout using code {{3}}. Shop now and add some unique and beautiful plants to your collection!",
"example": {
"body_text": [
[
"Pablo",
"30%",
"30OFF"
]
]
}
},
{
"type": "carousel",
"cards": [
{
"components": [
{
"type": "header",
"format": "image",
"example": {
"header_handle": [
"4:bWtsLmpwZWc=:aW1hZ2UvanBlZw==:--_2A:e:1740735962::"
]
}
},
{
"type": "body",
"text": "Add a touch of elegance to your collection with the beautiful Aloe 'Blue Elf' succulent. Its deep blue-green leaves have a hint of pink around the edges."
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "Send me more like this!"
},
{
"type": "url",
"text": "Shop",
"url": "https://www.luckyshrub.com/rare-succulents/{{1}}",
"example": [
"BLUE_ELF"
]
}
]
}
]
},
{
"components": [
{
"type": "header",
"format": "image",
"example": {
"header_handle": [
"4:bWtsLmpwZWc=:aW1hZ2UvanBlZw==:--_2A:e:1740735962::"
]
}
},
{
"type": "body",
"text": "The Crassula Buddha's Temple is sure to be a conversation starter with its tiny temple shaped leaves, intricate details, and lacy texture."
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "Send me more like this!"
},
{
"type": "url",
"text": "Shop",
"url": "https://www.luckyshrub.com/rare-succulents{{1}}",
"example": [
"BUDDHA"
]
}
]
}
]
},
{
"components": [
{
"type": "header",
"format": "image",
"example": {
"header_handle": [
"4:bWtsLmpwZWc=:aW1hZ2UvanBlZw==:--_2A:e:1740735962::"
]
}
},
{
"type": "body",
"text": "The Echeveria 'Black Prince' is a stunning succulent, with near-black leaves, adorned with a hint of green around the edges, giving it its striking appearance."
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "Send me more like this!"
},
{
"type": "url",
"text": "Shop",
"url": "https://www.luckyshrub.com/rare-succulents{{1}}",
"example": [
"BLACK_PRINCE"
]
}
]
}
]
}
]
}
]
}
响应参数
参数名 |
类型 |
说明 |
code |
Integer |
结果编码 |
data |
JsonObject |
请求结果 |
message |
String |
请求结果说明 |
参数名 |
类型 |
说明 |
id |
String |
模板id |
status |
String |
一般为APPROVED,REJECTED,PENDING审核状态枚举枚举值: APPROVED: 使用中 IN_APPEAL: 已提出上诉 PENDING: 待处理 REJECTED: 已拒绝 PENDING_DELETION: 待删除 DELETED: 已删除 DISABLED: 不可用 PAUSED: 暂时停用 LIMIT_EXCEEDED: 超出限制 |
category |
String |
枚举值:MARKETING,UTILITY,AUTHENTICATION |
响应示例
成功示例
{
"code": 0,
"data": {
"id": "3160xxxxxxx3536",
"category": "MARKETING",
"status": "APPROVED"
},
"message": "请求成功"
}
失败示例
{
"code": -1,
"message": "请求失败",
"data": null
}
响应码说明
code |
message |
解决办法 |
0 |
请求成功 |
|
-1 |
请求失败 |
请联系技术人员排除问题 |
1000~100X |
鉴权问题 |
详情查看API鉴权部分 |
9000 |
参数异常 |
参数遗漏,请检查必须的参数 |
9001 |
系统业务错误 |
请联系技术人员排除问题 |
9002 |
商户手机号错误 |
请确认商户号码是否属于whatsapp号码 |
9006 |
该whatsapp号码未绑定应用 |
请联系业务人员处理应用和手机号绑定操作 |
支持的模板语言
语言 |
代码 |
|
语言 |
代码 |
|
语言 |
代码 |
Afrikaans |
af |
|
Greek |
el |
|
Portuguese (BR) |
pt_BR |
Albanian |
sq |
|
Gujarati |
gu |
|
Portuguese (POR) |
pt_PT |
Arabic |
ar |
|
Hebrew |
he |
|
Punjabi |
pa |
Azerbaijani |
az |
|
Hindi |
hi |
|
Romanian |
ro |
Bengali |
bn |
|
Hungarian |
hu |
|
Russian |
ru |
Bulgarian |
bg |
|
Indonesian |
id |
|
Serbian |
sr |
Catalan |
ca |
|
Irish |
ga |
|
Slovak |
sk |
Chinese (CHN) |
zh_CN |
|
Italian |
it |
|
Slovenian |
sl |
Chinese (HKG) |
zh_HK |
|
Japanese |
ja |
|
Spanish |
es |
Chinese (TAI) |
zh_TW |
|
Kannada |
kn |
|
Spanish (ARG) |
es_AR |
Croatian |
hr |
|
Kazakh |
kk |
|
Spanish (SPA) |
es_ES |
Czech |
cs |
|
Korean |
ko |
|
Spanish (MEX) |
es_MX |
Danish |
da |
|
Lao |
lo |
|
Swahili |
sw |
Dutch |
nl |
|
Latvian |
lv |
|
Swedish |
sv |
English |
en |
|
Lithuanian |
lt |
|
Tamil |
ta |
English (UK) |
en_GB |
|
Macedonian |
mk |
|
Telugu |
te |
English (US) |
en_US |
|
Malay |
ms |
|
Thai |
th |
Estonian |
et |
|
Marathi |
mr |
|
Turkish |
tr |
Filipino |
fil |
|
Norwegian |
nb |
|
Ukrainian |
uk |
Finnish |
fi |
|
Persian |
fa |
|
Urdu |
ur |
French |
fr |
|
Polish |
pl |
|
Uzbek |
uz |
German |
de |
|
|
|
|
Vietnamese |
vi |