首页 > API中心 > IVR群呼 > 文档指引

创建消息模板

POST

https://api.itniotech.com/wa/template/add

用于消息模板的创建,然后根据模板来发送模板消息

请求参数

参数	说明	是否必填	类型
appId	应用id	是	String
channelType	通道类型：0-WhatsApp，默认送0；	是	Integer
templateName	模板名称：小写字母、数字和下划线、512字符；	是	String
type	模板类型：0-AUTHENTICATION（身份验证）；1-MARKETING（营销性）；2-UTILITY（交易类)；	是	Integer
language	模板语言：如"zh_CN",详见国家语言枚举定义，一个模板名称可存在多种语言，一次只能创建一种语言	是	String
components	模板组件	否	Object
header	页眉	否	Object
type	组件类型：HEADER，默认HEADER	是	String
format	页眉的类型：0-TEXT， 1:IMAGE， 2:VIDEO， 3:DOCUMENT， 4:LOCATION，默认0，type=HEADER时必填	是	String
text	最多60个字符，允许插入1个变量，type=HEADER，format=0时必填	是	String
example	页眉变量示例，当text中有变量时必填	是	Object
header_text	页眉文本变量示例，页眉有变量时必填	是	Array
header_handle	调用上传模板示例文件接口返回的文件的句柄，页眉是图片/视频/文档时必填	是	Array
body	组件类型	否	Object
type	组件类型：BODY，默认BODY	是	String
text	最多1024个字符，允许插入变量，限制最多20个变量，模板类型为交易相关和营销时必填	否	String
add_security_recommendation	添加安全建议：true、false，模板类型为身份验证时必填	否	Boolean
example	正文变量示例，当text中有变量时必填	否	Object
body_text	正文文本变量示例，与text中变量个数一致，正文有变量必填	否	Array
footer	组件类型	否	Object
type	组件类型：FOOTER，默认FOOTER	否	String
text	最多60个字符，模板类型为非身份验证时必传	否	String
code_expiration_minutes	验证码的失效时间，身份验证类模板有此项，值的可填范围是1-90	否	Integer
button	组件类型	否	Object
type	组件类型：BUTTONS，默认BUTTONS，模板类型为身份验证时必填	否	String
buttons	按钮对象	否	Object
type	按钮类型： 1:URL， 2:QUICK_REPLY， 3:OTP， 4:PHONE_NUMBER， 5:ONE_TAP3-OTP	是	Integer
text	按钮显示的名称，25字符以内（type为URL、QUICK_REPLY、PHONE_NUMBER时必填）	是	String
otp_type	验证码按钮类型：copy_code（复制验证码）、one_tap（一键式填充）	是	String
phone_number	用户轻触该按钮时会拨打的电话号码，20 字符以内（type为PHONE_NUMBER时必填）	是	String
url	应用用户轻触该按钮时，系统就会在设备的默认移动网页浏览器中加载该网址。支持1个变量，该变量应附加到网址字符串的末尾处，且变量名需要设置为{{1}}。长度不超过2,000个字符（type为URL时必填）	是	String
example	网址示例，长度不超过2,000个字符（type为URL时且url有变量时必填）	是	Array
autofill_text	一键式按钮的名称（type为ONE_TAP时必填）	是	String
package_name	安卓应用的程序包名称（type为ONE_TAP时必填）	是	String
signature_hash	应用签名密钥哈希。（type为ONE_TAP时必填）	是	String

请求示例

Request URL:
    https://api.itniotech.com/wa/template/add
Request Method:
    POST
Request Headers:
    Content-Type: application/json;charset=UTF-8
    Sign: 05d7a50893e22a5c4bb3216ae3396c7c
    Timestamp: 1690286812882
    Api-Key: 7Wqzu5rm

//创建营销类、header为text的模板，且按钮为电话和网址，正文一个变量（模板type类型随意搭配）
Request Body:
{
    "appId": "yYgJ5EVD",
    "channelType": 0,
    "templateName": "dd_template",
    "type": 1,
    "language": "zh_CN",
    "components":
    {
        "header":{
            "type": "HEADER",
            "format": 0,
            "text": "智能otp正在{{#}}活动中",
            "example": {
                "header_text": ["打折"]
            }
        },
        "body":{
            "type": "BODY",
            "text": "公司新开业, {{#}}活动火热进行中....",
            "example":{
                "body_text": [
                    ["打折"]
                ]
            }
        },
        "footer": {
            "type": "FOOTER",
            "text": "颂量科技"
        }
    }
}

//创建模板: 身份认证类:
{
    "appId": "yYgJ5EVD",
    "channelType": 0,
    "templateName": "skyline_template_tt",
    "type": 0,
    "language": "zh_CN",
    "components": {
        "body": {
            "type": "BODY",
            "add_security_recommendation": true
        },
        "button": {
            "type": "BUTTONS",
            "buttons": [{
                "otp_type": "COPY_CODE",
                "text": "3232",
                "type": 3
            }]
        },
        "footer": {
            "type": "FOOTER",
            "code_expiration_minutes": 10
        }
    }
}

//无请求头的交易类型:
{
    "appId": "DHhgCjMX",
    "channelType": 0,
    "templateName": "sjhdd_template_jy_1",
    "type": 2,
    "language": "cs",
    "components": {
        "body": {
            "type": "BODY",
            "text": "You have successfully checked in! Below is the boarding pass for this flight{{#}} {{#}}k {{#}} whe de ds d fd htttt ",
            "example": {
                "body_text": [
                    ["you","and","haha"]
                ]
            }
        },
        "footer": {
            "type": "FOOTER",
            "text": "You have successfully checked in!"
        }
    }
}

轮播模板-请求参数说明

参数	说明	是否必填	类型
appId	应用id	是	String
channelType	通道类型：0-WhatsApp，默认送0；	是	Integer
templateName	模板名称：小写字母、数字和下划线、512字符；	是	String
type	模板类型：0-AUTHENTICATION（身份验证）；1-MARKETING（营销性）；2-UTILITY（交易类)；	是	Integer
markingChildType	营销模板子分类，1素材图卡轮播模板；	创建轮播模板时必填	Integer
language	模板语言：如"zh_CN",详见国家语言枚举定义，一个模板名称可存在多种语言，一次只能创建一种语言	是	String
components	模板组件	否	Object
body	消息正文组件	是	Object
type	组件类型，"body"	是	String
text	最多1024个字符，允许插入变量，限制20个变量。	模板类型为交易相关和营销时，必填	String
example	正文变量示例	当text中有变量时必填	Object
body_text	正文文本变量示例，与text中变量个数一致，text有变量必填	是	array[array[string]]
carousel	轮播组件	模板为轮播模版时必填	Object
type	组件类型，"carousel"	模板为轮播模版时必填	String
headerType	页眉的类型:1:IMAGE，2:VIDEO	模板为轮播模版时必填	String
carouselButtonsType	按钮类型配置，多个用逗号隔开(1-URL,2-QUICK_REPLY,4-PHONE_NUMBER)，每个卡片中卡片按钮组的按钮类型需与此类型其保持一致	否	String
cards	卡片对象，限制2-10张	type=carousel时必填	array[object]
components	卡片模板组件	是	Object
header	卡片页眉	是	Object
type	组件类型，"header"	是	String
example	页眉变量示例	是	Object
header_handle	调用上传模板示例文件接口返回的文件句柄	是	array[]
body	卡片正文	否	Object
type	组件类型，"body"	是	String
text	最多160个字符，允许插入变量。变量个数不能大于20	是	String
example	正文变量示例	当text中有变量时必填	Object
body_text	正文文本变量示例，与text中变量个数一致，每个示例不超过64字符	text有变量必填	array[array[string]]
button	卡片按钮	否	Object
type	组件类型，"buttons"	是	String
buttons	卡片按钮组，卡片必须至少包含一个按钮。支持两个按钮	是	array[object]
type	按钮类型：1:网址跳转；2:快速回复；4:拨打电话	是	Integer
text	按钮显示的名称，25字符以内	是	String
phone_number	拨打电话按钮参数：用户轻触该按钮时会拨打的电话号码，20 字符以内，需带区号。	按钮类型type=4必填	String
url	网址跳转按钮参数：应用用户轻触该按钮时，系统就会在设备的默认移动网页浏览器中加载该网址。支持 1 个变量，该变量应附加到网址字符串的末尾处。	按钮类型type=1必填	String
example	网址跳转按钮参数：网址示例	网址存在变量时，必填	array[string]

轮播模板-请求示例

Request URL:
    https://api.itniotech.com/wa/template/sendMsg
Request Method:
    POST
Request Headers:
    Content-Type: application/json;charset=UTF-8
    Sign: 05d7a50893e22a5c4bb3216ae3396c7c
    Timestamp: 1630468800
    Api-Key: bDqJFiq9
Request Body:
{
  "appId": "lYOxMDYC",
  "channelType": 0,
  "recipient": "8615986688129",
  "businessPhone": "12026693133",
  "template": {
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "9.1日开业大吉"
          }
        ]
      },
      {
        "type": "carousel",
        "cards": [
          {
            "card_index": 0,
            "components": [
              {
                "type": "body",
                "parameters": [
                  {
                    "text": "打折",
                    "type": "text"
                  }
                ]
              },
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "link": "https://www.luckyshrub.com/assets/blue-echeveria.jpeg"
                    }
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "url",
                "index": "0",
                "parameters": [
                  {
                    "type": "text",
                    "text": "urlVal"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": "1",
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "more-aloes"
                  }
                ]
              }
            ]
          },
          {
            "card_index": 1,
            "components": [
              {
                "type": "body",
                "parameters": [
                  {
                    "text": "2打折",
                    "type": "text"
                  }
                ]
              },
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "link": "https://www.luckyshrub.com/assets/blue-echeveria.jpeg"
                    }
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "url",
                "index": "0",
                "parameters": [
                  {
                    "type": "text",
                    "text": "2urlVal"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": "1",
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "2more-aloes"
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "language": {
      "code": "en"
    },
    "name": "template_marketing_api_20"
  }
}

响应参数

参数	说明	类型
status	状态码，0成功，其他失败参见响应状态码说明	String
reason	失败原因说明	String
data	发送结果	Object
templateId	模板id	String
templateName	模板名称	String
type	模板类型：0-AUTHENTICATION（身份验证）；1-MARKETING（营销性）；2-UTILITY（交易类)；	String
languageCode	模板语言，详见国家枚举	String
status	模板状态：PENDING（审核中）、REJECTED（审核未通过）、APPROVED（审核通过）、DELETED（已删除）、DISABLED（禁用）、PENDING_DELETION(待删除)、IN_APPEAL（已提出上诉）、PAUSED（暂时停用）、LIMIT_EXCEEDED（超出限制）、FLAGGED（计划禁用）、REINSTATED（恢复）	String

响应状态码

status	状态说明
0	成功
-1	身份验证错误
-2	模板状态不正确
-4	时间戳过期
-5	系统异常
-6	IP受限
-7	参数校验异常
-8	参数校验异常
-10	应用不存在
-11	应用名称已存在
-12	网络异常，请稍后重试
-14	账号未认证
-16	消息模板删除后一个月内不可再次使用相同名称创建，请重新定义模板名称
-18	fileId不能为空
-19	fileId不能为空
-21	header消息过长
-23	Button type不能为空
-24	buttons数量太多
-32	当前模板名下语言重复
-33	模板名格式不对
-34	模板两个变量不能同时挨着出现
-37	创建模板失败
-38	当前模板不存在
-40	示例文件太大
-74	语言代码格式错误
-75	模板类型与现有类型不匹配
-76	请输入正确的类型
-77	请输入正确的格式电话号码和区域代码
-78	请输入正确的语言
-82	body示例太长了
-83	请输入正确的format参数
-84	文本内容不能为空
-86	模板正文type不能为空
-87	模板页脚type不能为空
-88	模板页脚文本太长了
-89	模板组件不能为空
-90	Header不能有连续的变量
-91	标题文本中变量的数量与示例的数量不匹配。或标题文本中的变量数不能大于1
-92	文本长度不能大于25
-99	通道类型错误
-100	头部类型为文本时format不能为空
-101	请输入正确的format值
-102	请输入正确的button类型, 当前只支持otp类型即type:3
-103	当模板类型为身份验证时, body 正文不能为空
-104	body添加的安全提醒参数错误
-105	模板页脚长度不能超过60
-106	过期时间必须在0-90
-107	该应用没有应用别名
-108	按钮参数otp_type不能为空
-109	当模板类型为身份验证时, 按钮不能为空
-136	重复创建模板
-137	header示例值不能为空
-138	body示例值不能为空
-241	营销模板类别才允许创建轮播模板
-242	轮播模板子分类只能是默认或轮播
-243	轮播模板的正文不能为空
-244	轮播模板carsouel组件类型不能为空
-245	轮播模板应添加至少2张，至多10张卡片
-246	轮播模板卡片的组件不能为空
-247	轮播模板卡片的页眉组件不能为空
-248	轮播模板页眉类型不能为空，且只能是1-image、2-video
-249	轮播模板卡片的页眉组件类型不能为空
-250	轮播模板卡片的页眉示例文件句柄不能为空
-251	轮播模板卡片的正文组件类型不能为空
-252	轮播模板卡片的正文内容不能为空，且不大于160个字符
-253	轮播模板卡片的正文内容中不能存在连续变量
-254	轮播模板卡片的正文内容变量个数不能大于20，且示例参数应和变量个数一致
-255	轮播模板卡片的正文内容示例参数内容不能大于64个字符
-256	轮播模板页眉按钮类型必须是1、2、4,多个用英文逗号隔开
-257	轮播模板卡片的按钮组件类型不能为空
-258	轮播模板卡片的按钮类型只能是1:网址跳转；2:快速回复；4:拨打电话
-259	轮播卡片模板主消息不支持标头、页脚和按钮组件
-260	轮播模板卡片的正文内容变量个数不能大于20，且示例参数应和变量个数一致

ISV对接API流程

删除消息模板

此页面的内容有帮助吗？

对接有疑问？联系我们的技术支持

ITNIO TECH API 专属 TG 技术对接频道，即时响应您的需求

前往Telegram联系

LANGUAGE

Java

PHP

REQUEST

package com.itniotech.api.demo.im;

import cn.hutool.core.map.MapUtil;
import cn.hutool.crypto.SecureUtil;
import cn.hutool.http.Header;
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;

import java.time.LocalDateTime;
import java.time.ZoneId;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
 
private static void createTemplate() {
    final String baseUrl = "https://api.itniotech.com/wa/";
    final String apiKey = "your api key";
    final String apiPwd = "your api secret";
    final String appId = "your appid";

    final String templateName = "template name"; //the template name
    final String language = "language code"; // the template support language
    final int channelType = 0; //channelType: 0-WhatsApp, default is 0
    final int type = 1;

    final String url = baseUrl.concat("template/add");

    HttpRequest request = HttpRequest.post(url);

    // currentTime
    final String datetime = String.valueOf(LocalDateTime.now().atZone(ZoneId.systemDefault()).toInstant().getEpochSecond());

    final String sign = SecureUtil.md5(apiKey.concat(apiPwd).concat(datetime));
    request.header(Header.CONNECTION, "Keep-Alive")
            .header(Header.CONTENT_TYPE, "application/json;charset=UTF-8")
            .header("Sign", sign)
            .header("Timestamp", datetime)
            .header("Api-Key", apiKey);

    String headerJson = "{"type":"HEADER","format":0,"text":"智能otp正在{{#}}活动中","example":{"header_text":["打折"]}}";
    String bodyValJson = "{"type":"BODY","text":"公司新开业, {{#}}活动火热进行中....","example":{"body_text":[["打折"]]}}";
    String footerJson = "{"type":"FOOTER","text":"颂量科技"}";


    Map componentsMap = MapUtil.builder("header", JSONUtil.parseObj(headerJson))
                                                .put("body", JSONUtil.parseObj(bodyValJson))
                                                .put("footer", JSONUtil.parseObj(footerJson))
                                                .build();

    String body = JSONUtil.createObj()
            .set("appId", appId)
            .set("channelType", channelType)
            .set("templateName", templateName)
            .set("type", type)
            .set("components", componentsMap)
            .set("language", language)
            .toString();

    HttpResponse response = request.body(body).execute();
    if (response.isOk()) {
        String result = response.body();
        System.out.println(result);
    }
}

REQUEST

header('content-type:text/html;charset=utf8');

$apiKey = "your api key";
$apiSecret = "your api secret";
$appId = "your appid";
$timeStamp = time();
$sign = md5($apiKey.$apiSecret.$timeStamp);
$headers = array('Content-Type:application/json;charset=UTF-8',"Sign:$sign","Timestamp:$timeStamp","Api-Key:$apiKey");

$url = "https://api.itniotech.com/wa/template/add";

$dataArr["appId"] = $appId;
$dataArr["channelType"] = 0;
$dataArr["templateName"] = "template name";
$dataArr["type"] = 1;
$dataArr["language"] = "language code";

$headerArr = array(
    array(
        "type" => "HEADER",
        "format" => 0,
        "text" => "智能otp正在{{#}}活动中",
        "example" => array(
            "header_text" => "打折"
        )
    )
);
$bodyArr = array(
    array(
        "type" => "BODY",
        "text" => "公司新开业, {{#}}活动火热进行中....",
        "example" => array(
            "body_text" => "打折"
        )
    )
);
$footerArr = array(
    array(
        "type" => "FOOTER",
        "text" => "颂量科技"
    )
);
$dataArr["components"] = array(
    'header' => $headerArr,
    'body' => $bodyArr,
    'footer' => $footerArr
);

$data = json_encode($dataArr);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 600);
curl_setopt($ch, CURLOPT_HTTPHEADER,$headers);
curl_setopt($ch, CURLOPT_POSTFIELDS , $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

$output = curl_exec($ch);
curl_close($ch);
var_dump($output);

RESPONSEEXAMPLE

{
    "status": "0",
    "reason": "success",
    "data": {
    "templateId": "0bd9ea48738d4d0db667b1e1f50020a9",
        "templateName": "itnio_template_xk_test",
        "type": 1,
        "languageCode": "en",
        "status": "APPROVED"
    }
}

消息

语音

快速入门

语音API

快速入门

坐席端API

管理端API

快速入门

AI Agent API

平台 API

创建消息模板

此页面的内容有帮助吗？

LANGUAGE

短信

语音

行业

场景

消息

语音

快速入门

语音API

快速入门

坐席端API

管理端API

快速入门

AI Agent API

平台 API

创建消息模板

此页面的内容有帮助吗？

LANGUAGE