创建消息模板
在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] |
必须/无 |
|
| otp_type |
string |
必须/无 |
验证码按钮类型 固定值 ONE_TAP 或者 COPY_CODE ,ZERO_TAP；ONE_TAP的含义是一键填充 COPY_CODE的含义是复制验证码 ZERO_TAP的含义是零触式验证码 |
| autofill_text |
string |
必须/无 |
自动填充按钮文本，展示在按钮上的文案， |
| supported_apps |
array[string] |
必须/无 |
一个或者多个，最多支持5个 |
| flow_id |
string |
必须/无 |
当type =Flow时有值, WhatsApp 提供的流程的唯一标识符。流程必须已发布 |
| flow_action |
string |
必须/无 |
当type =Flow时有值, navigate 或 data_exchange 默认：navigate |
| navigate_screen |
string |
必须/无 |
当type =Flow时有值, 仅在 flow_action 为 navigate 时，此为必要项。流程的第一个屏幕的. |
| 参数名 |
类型 |
是否必须 |
说明 |
| package_name |
string |
必须/无 |
安卓包名， |
| signature_hash |
string |
必须/无 |
应用hash， |
请求示例
- 普通文本模板
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 Code",
"autofill_text": "Autofill2",
"supported_apps": [
{
"package_name": "com.example.myapplication",
"signature_hash": "K8a/AINcGX8"
},
{
"package_name": "com.example.myapplication",
"signature_hash": "K8a/AINcGX9"
},
{
"package_name": "com.example.myapplication",
"signature_hash": "K8a/AINcGX0"
}
]
}
]
}
]
}
{
"appkey": "8exxxs",
"messaging_product": "whatsapp",
"business_phone": "185xxx99",
"category": "AUTHENTICATION",
"name": "otp_test_03",
"language": "zh_CN",
"components": [
{
"type": "BODY",
"add_security_recommendation": true
},
{
"type": "FOOTER",
"code_expiration_minutes": 5
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "ZERO_TAP",
"zero_tap_terms_accepted": true,
"text": "Copy Code",
"autofill_text": "Autofill",
"supported_apps": [
{
"package_name": "com.example.myapplication",
"signature_hash": "K8a/AINcGX8"
},
{
"package_name": "com.example.myapplication",
"signature_hash": "K8a/AINcGX9"
},
{
"package_name": "com.example.myapplication",
"signature_hash": "K8a/AINcGX0"
}
]
}
]
}
]
}
{
"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 |