WhatsApp API createTemplate - nxtele/http-api-document-en GitHub Wiki

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