WhatsApp API createTemplate

Create Message Template

Create a new message template for a specific number in the WhatsApp application.

Please note that if you use a rich media interactive template while creating the template, you need to submit a rich media example file. The rich media example file can be uploaded through the "Template Media Upload" API endpoint.

• URL: https://api2.nxcloud.com/api/wa/createTemplate
• Method: POST
• Content-Type: application/json
• Requires authentication: Yes

Authentication Mechanism

Please refer to the following address for authentication rules: API Interface Call Agreement

Request Parameters

Header Parameters:

Parameter Name	Type	Required	Example Value	Description
accessKey	String	Yes	fmexxx3ki	User identification
ts	String	Yes	1655710885431	The timestamp of the current request in milliseconds. The maximum allowable time difference between the user and server is 60 seconds.
bizType	String	Yes	2	WhatsApp business type. It should have a fixed value of "2".
action	String	Yes	createTemplate	WhatsApp business operation. It should have a fixed value of "createTemplate".
sign	String	Yes	6e95xxx826	API parameter signature. Signature algorithm

Body Parameters:

Parameter Name	Type	Required	Example Value	Description
appkey	String	Yes		Appkey for the NXCloud WhatsApp application
business_phone	String	Yes	86158xxx1795	List of merchant's WhatsApp numbers, including the country code, e.g., 185xxx99
messaging_product	String	Yes	whatsapp	The channel used to send the message. For WhatsApp messaging, the value must be "whatsapp".
category	String	Yes	MARKETING	Template type. Enum values: "MARKETING": "Includes promotional or discount information, information updates, or invitations for customers to respond/take action. Anything that is not for utility or authentication purposes is considered marketing", "UTILITY": "Facilitates a specific request or transaction agreed upon by the business, or provides customers with the latest information related to an ongoing transaction, including post-purchase notifications and regular bills", "AUTHENTICATION": "Allows businesses to use one-time passwords to verify the identity of users. It may appear in multiple steps of the login process (such as account authentication, account recovery, integrity challenge)"
language	String	Yes	zh_CN	Language code, e.g., zh_CN
name	String	Yes		Template name
components	array[component object]	Yes		Template components

• component object parameters:

Parameter Name	Type	Required	Description
type	string	Required	Component type. Possible values: HEADER, BODY, FOOTER, BUTTONS
format	string	Required/None	Only required when type=HEADER, otherwise not applicable. Describes the type of content in the HEADER. Possible values: TEXT, DOCUMENT, IMAGE, VIDEO
text	string	Required/None	Required for type=HEADER and format=text. Required for type=BODY. Required for type=FOOTER. Not applicable for type=BUTTONS.
example	object	Required/None	Variable example. Required when variables are configured in HEADER or BODY content, otherwise not applicable.
buttons	array[button object]	Required/None	Required for type=BUTTONS, otherwise not applicable.
add_security_recommendation	boolean	Required/None	Add security recommendation. Optional for type=BODY in authentication templates. Value: true/false.
code_expiration_minutes	integer	Required/None	Expiration time of the verification code. Optional for type=FOOTER in authentication templates. Valid range: 1-90.

• example object parameters:

Parameter Name	Type	Required	Description
header_handle	string	Required/None	Required when format=DOCUMENT or format=IMAGE or format=VIDEO in HEADER, otherwise not applicable.
header_text	array[string]	Required/None	Required when format=TEXT in HEADER, otherwise not applicable.
body_text	array[string]	Required/None	Required when variables are configured in BODY content. The number of values in the array depends on the variable configuration. Not applicable if no variables are configured in BODY content.

• button object parameters:

Parameter Name	Type	Required	Description
type	string	Required/None	Button type. Possible values: QUICK_REPLY, URL, PHONE_NUMBER. QUICK_REPLY for quick reply buttons. URL for action URL buttons. PHONE_NUMBER for action phone number buttons.
text	string	Required	Button display text.
url	string	Required/None	URL configured for the action URL button. Only required for type=URL. If it's a dynamic URL, it should include the suffix variable {{1}}.
phone_number	string	Required/None	Phone number configured for the action phone number button. Only required for type=PHONE_NUMBER.
example	array[string]	Required/None	URL example. Required when type=URL and it's a dynamic URL. Example: https://www.baidu.com/user
otp_type	string	Required/None	Verification code button type. Fixed values: ONE_TAP or COPY_CODE. ONE_TAP for autofill, COPY_CODE for copying the verification code.
autofill_text	string	Required/None	Autofill button text, displayed on the button. Required only when otp_type=ONE_TAP.
package_name	string	Required/None	Android package name. Required only when otp_type=ONE_TAP.
signature_hash	string	Required/None	Application hash. Required only when otp_type=ONE_TAP.

Request Example

• Plain Text Template Body (application/json) parameters:

{
    "appkey": "8eoxxxos",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "name": "normal_text",
    "category": "MARKETING",
    "language": "zh_CN",
    "components": [
        {
            "type": "BODY",
            "text": "hello world"
        }
    ]
}

• Rich Template Body (application/json) parameters:

{
	"appkey": "8exxxos",
	"messaging_product": "whatsapp",
	"business_phone": "185xxx99",
	"name": "normal_text3",
	"category": "MARKETING",
	"language": "en_US",
	"components": [{
			"type": "HEADER",
			"format": "TEXT",
			"text": "hello",
			"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 with Media Template Body (application/json) parameters:

{
	"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"
				}
			]
		}
	]
}

• Simple MARKETING Template Body (application/json) parameters:

{
	"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"
                    ]
				]
			}
		}
	]
}

• Authentication - Copy Code

{
    "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"
                }
            ]
        }
    ]
}

• Authentication - One-Tap Autofill

{
    "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"
                }
            ]
        }
    ]
}

Response Parameters

Parameter	Type	Description
code	Integer	Result code
data	JsonObject	Request result
message	String	Request result description

• data JsonObject parameters:

Parameter	Type	Description
id	String	Template ID

Response Example

Success Example

{
    "code": 0,
    "data": {
        "id": "900xxx0755"
    },
    "message": "Request successful"
}

Failure Example

{
    "code": -1,
    "message": "Request failed",
    "data": null
}

Response Code Explanation

code	message	Resolution
0	Request successful
-1	Request failed	Please contact technical support to troubleshoot the issue
1000~100X	Authentication issue	See API authentication section for details
9000	Parameter exception	Missing parameters, please check required parameters
9001	System business error	Please contact technical support to troubleshoot the issue
9002	Merchant phone number error	Please confirm if the merchant number belongs to a WhatsApp number
9006	The WhatsApp number is not bound to an application	Please contact the business personnel to handle the application and phone number binding process

Supported Template Languages

Language	Code		Language	Code		Language	Code
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