Home > API Center > API interface guide

Create a Message Template

POST

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

Used to create message templates, and then send template messages according to the templates

Request Parameters

Parameters	Description	Required	Type
appId	Application id	Yes	String
channelType	Channel type: 0-WhatsApp, send 0 by default	Yes	Integer
templateName	Template name: lowercase letters, numbers and underscores, 512 characters	Yes	String
type	Template type: 0-AUTHENTICATION (authentication); 1-MARKETING (marketing); 2-UTILITY (transaction class)	Yes	Integer
language	Template language: such as "zh_CN", see detailsCountry language enumeration definition, a template name can exist in multiple languages, only one language can be created at a time	Yes	String
components	Template component	No	Object
header	Header	No	Object
type	Component type: HEADER, default HEADER	Yes	String
format	Type of header: 0-TEXT, 1-IMAGE, 2-VIDEO, 3-DOCUMENT, 4-LOCATION	Yes	String
text	Up to 60 characters, allowing 1 variable to be inserted. Required when type=HEADER, format=0	Yes	String
example	Header variable example. Required when there are variables in text	Yes	Object
header_text	Example header text variable. Required when there are variables in header	Yes	Array
header_handle	The handle of the file returned by calling the upload template sample file interface. Required when the header is a image/video/document.	No	Array
body	Component type	No	Object
type	Component type: BODY, default BODY	Yes	String
text	Up to 1024 characters, allows inserting variables, limit up to 20 variables. Required when the template type is transaction-related and marketing	No	String
add_security_recommendation	Add security advisories: true, false. Required when template type is authentication	No	Boolean
example	Text variable example. Required when there are variables in text	No	Object
body_text	Example of text variables in the body text, variables must be filled in the body text. Optional, consistent with the number of variables in text	No	Array
footer	Component type	No	Object
type	Component type: FOOTER, default FOOTER	No	String
text	up to 60 characters. It must be passed When the template type isn't authentication	No	String
code_expiration_minutes	The expiration time of the verification code, the identity verification template has this item, the value can be filled in the range of 1-90	No	Integer
button	Component type	No	Object
type	Component type: BUTTONS, default BUTTONS. Required when template type is authentication	No	String
buttons	button object	No	Object
type	Button type: 1-URL, 2-UICK_REPLY, 3-OTP, 4-PHONE_NUMBER, 5-ONE_TAP	Yes	Integer
text	The displayed name of the button, within 25 characters. (type is URL, QUICK_REPLY, PHONE_NUMBER required)	Yes	String
otp_type	Verification code button type: copy_code (copy verification code), one_tap (one-click filling)	Yes	String
phone_number	The phone number that will be dialed when the user taps the button, within 20 characters. (type is PHONE_NUMBER required)	Yes	String
url	When an app user taps the button, the URL will be loaded in the device's default mobile web browser. Supports 1 variable, which should be appended to the end of the URL string, and the variable name needs to be set to {{1}}. 2,000 characters or less in length. (type is URL required)	Yes	String
example	Example URL, 2,000 characters or less. (type is dynamic URL is required)	Yes	Array
autofill_text	The name of the one-touch button. (type is ONE_TAP required)	Yes	String
package_name	Android application package name. (type is ONE_TAP required)	Yes	String
signature_hash	Apply signing key hash. (type is ONE_TAP required)	Yes	String

Request Sample

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

//Create a marketing template with a header of text, with buttons for phone and website, and a variable for the main text (template type can be matched freely)
Request Body:
{
    "appId": "yYgJ5EVD",
    "channelType": 0,
    "templateName": "dd_template",
    "type": 1,
    "language": "zh_CN",
    "components":
    {
        "header":{
            "type": "HEADER",
            "format": 0,
            "text": "OTP is currently in {{#}} activity",
            "example": {
                "header_text": ["Discounts"]
            }
        },
        "body":{
            "type": "BODY",
            "text": "The company is newly opened, and {{#}} activities are in full swing...",
            "example":{
                "body_text": [
                    ["Discounts"]
                ]
            }
        },
        "footer": {
            "type": "FOOTER",
            "text": "ITNIOTECH"
        }
    }
}

//Create Template: Identity Authentication Class
{
    "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
        }
    }
}

//Transaction type without request header
{
    "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!"
        }
    }
}

Carousel Template - Description of request parameters

Parameter	Description	Required	Type
appId	application id	Yes	String
channelType	Channel type: 0-WhatsApp, send 0 by default;	Yes	Integer
templateName	Template name: lowercase letters, numbers and underscores, 512 characters;	Yes	String
type	Template type: 0-AUTHENTICATION (authentication); 1-MARKETING (marketing); 2-UTILITY (transaction class);	Yes	Integer
markingChildType	Marketing Templates Subcategory: 1-Carousel Templates	Required when creating a carousel template	Integer
language	Template language: such as "zh_CN", see detailsCountry language enumeration definition, a template name can exist in multiple languages, only one language can be created at a time	Yes	String
components	template component	No	Object
body	component type	Yes	Object
type	Component type: "body"	Yes	String
text	Up to 1024 characters, allows inserting variables, limit up to 20 variables	Required when the template type is UTILITY and MARKETING	String
example	Text variable example	Required when text has variables	Object
body_text	Example of text variables in the body text	Optional, consistent with the number of variables in text	array[array[string]]
carousel	Carousel template component	Required if the template is a carousel template	Object
type	Component type，"carousel"	Required if the template is a carousel template	String
headerType	Header type:1:IMAGE，2:VIDEO	Required if the template is a carousel template	String
carouselButtonsType	Button types, multiple buttons separated by commas(1-URL,2-QUICK_REPLY,4-PHONE_NUMBER), the button type in each card must be consistent with this type.	No	String
cards	Card object, limited to 2-10 cards	Required if the template is a carousel template	array[object]
components	Card components	Yes	Object
header	header	Yes	Object
type	Component type，"header"	Yes	String
example	header variable example	Yes	Object
header_handle	The handle of the file returned by calling the upload template sample file interface	Yes	array[]
body	body	No	Object
type	Component type， "body"	Yes	String
text	Up to 1024 characters, allows inserting variables, limit up to 20 variables	Yes	String
example	Text variable example	Required if there are variables in the text field.	Object
body_text	Text variable example，each example not exceeding 64 characters.	Required if there are variables in the text field.	array[array[string]]
button	button	No	Object
type	Component type，"buttons"	Yes	String
buttons	Button group. The card must contain at least one button. Two buttons are supported.	Yes	array[object]
type	Button type: 1:URL 2:QUICK_REPLY 4:PHONE_NUMBER	Yes	Integer
text	The displayed name of the button, within 25 characters	Yes	String
phone_number	The phone number that will be dialed when the user taps the button, within 20 characters	Required when button type is PHONE_NUMBER	String
url	When an app user taps the button, the URL will be loaded in the device's default mobile web browser. Supports 1 variable, which should be appended to the end of the URL string. 2,000 characters or less in length	Required when button type is URL	String
example	URL example	URLs containing variables are required.	array[string]

Carousel Template - Request Example

Request URL:
    https://api.itniotech.com/wa/template/add
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"
  }
}

Response Parameters

Parameters	Description	Type
status	Status code, 0 is successful, other failures refer to the interface response code	String
reason	Reason for failure	String
data	Send result	Object
templateId	Template id	String
templateName	Template name	String
type	Template type: 0-AUTHENTICATION (authentication); 1-MARKETING (marketing); 2-UTILITY (transaction class)	String
languageCode	Template language, see Country Enumeration for details	String
status	Template status: PENDING (under review), REJECTED (not passed the review), APPROVED (passed the review), DELETED (deleted), DISABLED (disabled),PENDING_DELETION (pending deletion), IN_APPEAL (appeal filed), PAUSED (temporarily suspended), LIMIT_EXCEEDED (limit exceeded), FLAGGED (planned to be disabled), REINSTATED (reinstated)	String

Response Status Code

status	Description
0	success
-1	Authentication error
-2	Incorrect template status
-4	Timestamp expires
-5	System exception !
-6	Restricted IP access
-7	json parse exception, plase check you param's type and json format
-8	Abnormal parameter verification
-10	Application does not exist
-11	The application name already exists
-12	Network exception or parameter error
-14	Account not authenticated
-16	the same name template is deleted and cannot be used again within one month
-18	The fileId cannot be blank
-19	The fileId cannot be blank
-21	The header message is too long.
-23	Button type cannot be empty
-24	The quantity of buttons are too many
-32	The current templateName and language already exist
-33	The elementName format is incorrect.
-34	Template content cannot have continuous variables
-37	Error creating template
-38	It is failed to delete the template,current template was not found.
-40	Example file too large
-74	The languageCode format err
-75	The template type does not match the existing type.
-76	Please enter the correct type
-77	Please enter the correct format PhoneNumber and areaCode
-78	Please enter the correct language
-82	The bodyExample is too long
-83	Please enter the correct format params
-84	The text cannot be empty
-86	Template body type cannot be null
-87	Template footer type cannot be null
-88	Template footer text is too long
-89	Template component cannot be null
-90	The header cannot have continuous variables
-91	The number of variables in the header text does not match the number of examples. or The number of variables in the header text can not greater than one
-92	The text length cannot be greater than 25
-99	The channelType error !
-100	header format cannot be empty case type is text
-101	Please enter the correct format value
-102	Please enter the correct of button type, only OTP is supported(type:3)
-103	Body text not be null when type not 0 (AUTHENTICATION)
-104	The body add security recommendation param error
-105	Template footer text length cannot more than 60
-106	code_expiration_minutes must be lower or equal to 90
-107	This app have not app alias!
-108	Button otp_type cannot be empty
-109	when template type is 0 (AUTHENTICATION), buttons cannot be empty
-136	The template cannot be repeat created
-137	The header example value is not be null
-138	The body example value is not be null
-241	Only the marketing template category allows the creation of carousel templates
-242	template message carousel child type can only be 0(default) or 1(carousel)
-243	The carousel template body cannot be empty
-244	The carousel template type cannot be empty, and the type can only be 'carousel'
-245	The carousel template should have at least two cards and a maximum of 10 cards
-246	The carousel template card components cannot be empty
-247	The header in the carousel template card component cannot be empty
-248	The header type in the carousel template card component cannot be empty, and the type can only be 1(IMAGE) or 2(VIDEO)
-249	The header type in the carousel template card component cannot be empty, and the type can only be 'header'
-250	The header example in the carousel template card component cannot be empty
-251	The body type in the carousel template card component cannot be empty, and the type can only be 'body'
-252	The body text in the carousel template card component cannot be empty, and cannot exceed 160 characters
-253	The body content in the carousel template card component cannot have continuous variables
-254	The template has variable example parameters that cannot be empty or the number does not match
-255	The bodyExample in the carousel template card component cannot exceed 64 characters
-256	The button type must be one of 1(URL), 2(QUICK_REPLY), or 4(PHONE_NUMBER), or a combination of two (separated by commas)
-257	The button type in the carousel template card component cannot be empty, and must be "buttons"
-258	The buttons item type in the carousel template card button component cannot be empty, and the type can only be 1(URL)、2(URL)、4(PHONE_NUMBER)
-259	The main message of the carousel card template does not support headers, footers and button components.
-260	The carousel template carousel component cannot be empty

Query Number Information

Delete Message Template

Was this page helpful?

Questions about integration? Contact our technical support

ITNIO TECH API dedicated TG technical support channel, real-time response to your needs

Contact via 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 is currently in {{#}} activity","example":{"header_text":["Discounts"]}}";
    String bodyValJson = "{"type":"BODY","text":"The company is newly opened, and {{#}} activities are in full swing","example":{"body_text":[["Discounts"]]}}";
    String footerJson = "{"type":"FOOTER","text":"ITNIOTECH"}";


    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";

$headerArray = array(
    array(
        "type" => "HEADER",
        "format" => 0,
        "text" => "OTP is currently in {{#}} activity",
        "example" => array(
            "header_text" => "Discounts"
        )
    )
);
$bodyArray = array(
    array(
        "type" => "BODY",
        "text" => "The company is newly opened, and {{#}} activities are in full swing",
        "example" => array(
            "body_text" => "Discounts"
        )
    )
);
$footerArray = array(
    array(
        "type" => "FOOTER",
        "text" => "ITNIOTECH"
    )
);
$dataArr["components"] = array(
    'header' => $headerArray,
    'body' => $bodyArray,
    'footer' => $footerArray
);

$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"
    }
}

Message

Voice

Quick Start

Voice API

Quick Start

Agent Groups API

Management Side API

AI Agent API

Platform API

Create a Message Template

Was this page helpful?

language

SMS

VOICE

By Industry

By Scenario

Message

Voice

Quick Start

Voice API

Quick Start

Agent Groups API

Management Side API

AI Agent API

Platform API

Create a Message Template

Was this page helpful?

language