Template Management API

Overview

Using the template management API, you can add, delete, and check WABA's templates.

Call validation

EngageLab REST API HTTP basic authentication the verification method of: add HTTP Header Authorization (Header):

Authorization: Basic ${base64_auth_string}

          Authorization: Basic ${base64_auth_string}

This code block in the floating window

The preceding base64_auth_string generation algorithm is as follows: base64(dev_key:dev_secret)

the Header name is "Authorization" and the value is a base64-converted "username:password" pair (with a colon in the middle).
In WhatsApp API scenario, username is DevKey and password is DevSecret. In the console, choose configuration management- API key obtain the page.

Obtain templates

call address

GET https://wa.api.engagelab.cc/v1/templates

Request Parameters

Parameter	Type	Option	Description
name	String	Optional	Template name, note that this field uses fuzzy matching
language_code	String	Optional	Template language, see Language Code
category	String	Optional	Template category. ● AUTHENTICATION: Verification code ● MARKETING: Marketing ● UTILITY: Service notification
status	String	Optional	Template status: APPROVED - Approved PENDING - Pending REJECTED - Rejected PENDING_DELETION - Pending deletion DELETED - Deleted DISABLED - Disabled (banned) IN_APPEAL - In appeal PAUSED - Paused Developers mainly need to pay attention to APPROVED/PENDING/REJECTED/DISABLED

Response parameters

Parameter	Type	Option	Description
id	String	required	template ID
name	String	required	template name
language	String	required	template language, see language code .
category	String	required	The type of the template. OTP: one-time password MARKETING: marketing TRANSACTIONAL: transaction note: The template category will be updated: AUTHENTICATION MARKETING UTILITY
components	Object Array	required	for more information about the template content, see create components objects in a template
status	String	required	template status: APPROVED IN_APPEAL PENDING REJECTED PENDING_DELETION DELETED DISABLED PAUSED LIMIT_EXCEEDED

response example

// A json array, each object in the array is template information [ { "id": "406979728071589", // template id "name": "code", // template name "language": "zh_CN", // template language "status": "APPROVED", // status, APPROVED is available for approval "category": "OTP", // category, currently supports OTP/TRANSACTIONAL/MARKETING "components": [ // The specific content of the template, which can include HEADER/BODY/FOOTER/BUTTON { "type": "HEADER", "format": "text", // type, support text/image/location/video/document, default TEXT "text": "Registration Verification Code" // Text content, when the format is text, it is required }, { "type": "BODY", "text": "Your verification code is {{1}}, please enter it within 5 minutes." // Two braces {{}} indicate template variables } ] }, … ]

          // A json array, each object in the array is template information
[
    {
        "id": "406979728071589", // template id
        "name": "code", // template name
        "language": "zh_CN", // template language
        "status": "APPROVED", // status, APPROVED is available for approval
        "category": "OTP", // category, currently supports OTP/TRANSACTIONAL/MARKETING
        "components": [ // The specific content of the template, which can include HEADER/BODY/FOOTER/BUTTON
            {
                "type": "HEADER",
                "format": "text", // type, support text/image/location/video/document, default TEXT
                "text": "Registration Verification Code" // Text content, when the format is text, it is required
            },
            {
                "type": "BODY",
                "text": "Your verification code is {{1}}, please enter it within 5 minutes." // Two braces {{}} indicate template variables
            }
        ]
    },
     …
]

This code block in the floating window

Query Template Information

API Endpoint

GET https://wa.api.engagelab.cc/v1//{template_id}

Where {template_id} represents the template ID to be queried.

Request Parameters

None

Request Example

GET https://wa.api.engagelab.cc/v1/templates/406979728071589

Response Parameters

Parameter	Type	Required	Description
id	String	Required	Template ID
name	String	Required	Template Name
language	String	Required	Template language, see Language Codes.
category	String	Required	Template Category. OTP: One-time password MARKETING: Marketing TRANSACTIONAL: Transactional Note: The template categories will be updated by May 1, 2023 to: AUTHENTICATION MARKETING UTILITY
components	Object Array	Required	Components of the template content, refer to Components object in Create Template.
status	String	Required	Template status: APPROVED, IN_APPEAL, PENDING, REJECTED, PENDING_DELETION, DELETED, DISABLED, PAUSED, LIMIT_EXCEEDED

Response Example

{ "id": "406979728071589", // Template ID "name": "code", // Template Name "language": "en", // Template Language "status": "APPROVED", // Status, APPROVED means the template is approved and available "category": "OTP", // Category, currently supports OTP/TRANSACTIONAL/MARKETING "components": [ // Specific content of the template, can include HEADER/BODY/FOOTER/BUTTON { "type": "HEADER", "format": "text", // Type, supports text/image/location/video/document, default is TEXT "text": "Registration Verification Code" // Text content, required when format is text }, { "type": "BODY", "text": "Your verification code is {{1}}, please enter it within 5 minutes." // Double curly brackets {{}} indicate template variables } ] }

          {
    "id": "406979728071589", // Template ID
    "name": "code", // Template Name
    "language": "en", // Template Language
    "status": "APPROVED", // Status, APPROVED means the template is approved and available
    "category": "OTP", // Category, currently supports OTP/TRANSACTIONAL/MARKETING
    "components": [ // Specific content of the template, can include HEADER/BODY/FOOTER/BUTTON
        {
            "type": "HEADER",
            "format": "text", // Type, supports text/image/location/video/document, default is TEXT
            "text": "Registration Verification Code" // Text content, required when format is text
        },
        {
            "type": "BODY",
            "text": "Your verification code is {{1}}, please enter it within 5 minutes." // Double curly brackets {{}} indicate template variables
        }
    ]
}

This code block in the floating window

Create a template

call address

POST https://wa.api.engagelab.cc/v1/templates

call example

{ "name": "template_name", // template name, templates with the same name are allowed, only lowercase letters, numbers and underscores are supported "language": "zh_CN", // Template language, same language templates are not allowed under templates with the same name "category": "OTP", // category, currently supports OTP/TRANSACTIONAL/MARKETING "components": [ { // template content "type": "BODY", // content block, currently supports HEADER/BODY/FOOTER/BUTTONS "text": "define var as {{1}}", // specific text, when the body is text, there is no need to pass the format field "example": { "body_text": [ [ "var1" ] ] } }, { "type": "HEADER", "format": "image", // content type, support text/image/video/document/location "example": { "header_handle": [ "https://jiguang.cn/demopic.jpg" ] } }, { "type": "FOOTER", "text": "footer only support text without variable" }, { "type": "BUTTONS", "buttons": [ { "type": "PHONE_NUMBER", // button type, support PHONE_NUMBER/URL/QUICK_REPLY "text": "this is a phone number", "phone_number": "8613800138000" } ] } ] }

          {
    "name": "template_name", // template name, templates with the same name are allowed, only lowercase letters, numbers and underscores are supported
    "language": "zh_CN", // Template language, same language templates are not allowed under templates with the same name
    "category": "OTP", // category, currently supports OTP/TRANSACTIONAL/MARKETING
    "components": [
        { // template content
            "type": "BODY", // content block, currently supports HEADER/BODY/FOOTER/BUTTONS
            "text": "define var as {{1}}", // specific text, when the body is text, there is no need to pass the format field
            "example": {
                "body_text": [
                    [
                        "var1"
                    ]
                ]
            }
        },
        {
            "type": "HEADER",
            "format": "image", // content type, support text/image/video/document/location
            "example": {
                "header_handle": [
                    "https://jiguang.cn/demopic.jpg"
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "footer only support text without variable"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "PHONE_NUMBER", // button type, support PHONE_NUMBER/URL/QUICK_REPLY
                    "text": "this is a phone number",
                    "phone_number": "8613800138000"
                }
            ]
        }
    ]
}

This code block in the floating window

Request parameters

Parameter	Type	Option	Description
name	String	required	the name of the template. It can only contain lowercase letters, numbers, and underscores. It cannot exceed 512 characters in length.
language	String	required	template language, see language code .
category	String	required	the type of the template. OTP: one-time password MARKETING: marketing TRANSACTIONAL: transaction Note: The template category will be updated no later than May 1, 2023 to: AUTHENTICATION MARKETING UTILITY
components	Object Array		Required the components that describe the template content. For more information, see components object

components object

this object describes the template content. The template is divided into several components, such as HEADER, BODY, FOOTER, and Button BUTTONS. You can use type to specify these components. Different component types support different parameters as follows:

header and header components

the header component is optional. Do not set this component if you do not need to set the header.

Parameter	Type	Option	Description
type	String	required	the type of the component. Valid values: HEADER.
format	String	required	the header format. Valid values: text, image, video, and document, corresponding to text, image, video, and file.
text	String	optional	the content of the header text. This field must be set when format = text. You can set variables in the header text, but only one variable can be set, represented by {{1}}.
example	JSON Object	optional	header example. This field is required when text contains variables or format is media type. Reference example object description

example object description

Parameter	Type	Option	Description
header_handle	String Array	optional	if the format is image, video, or document, the url of the media of the corresponding type is passed into this field, and the url can be accessed. Otherwise, the template review may be rejected. For example: "header_handle": [`"https://jiguang.cn/demopic.jpg"`]
header_text	String Array	optional	if the format is text and contains a variable, the variable is replaced by this field. For example: "header_text": ["var1"]
header_url	String Array	optional	the usage is the same as that of header_handle. Note that this field will no longer be supported in future versions of WhatsApp. Avoid using this field as much as possible. For example: "header_url": [`"https://jiguang.cn/demopic.jpg"`]

body component

the body component is required. You must set the body content.

Parameter	Type	Option	Description
type	String	required	the type of the component. Valid values: BODY.
text	String	required	the content of the body. It can be up to 1024 characters in length. Multiple variables can be set. The variable consists of two braces and the sequence number of the variable. The sequence number must start from 1 and keep increasing, such as {{1}} and {{2}}.
example	JSON Object	optional	body example. Meta reviewers will determine your message compliance based on the example. Reference example object description this field is required when text contains variables.

example object description

Parameter	Type	Option	Description
body_text	String Array	optional	when text contains variables, you must pass in this field. All variables in the order of variable sequence numbers. For example: "body_text": [["var1","var2","var3"]]

the footer component is optional. Do not set this component if you do not need to set the footer.

Parameter	Type	Option	Description
type	String	required	the type of the component. Set the value to FOOTER.
text	String	required	the content of the footer. Only plain text content can be set, you cannot define a variable.

buttons button assembly

buttons component is optional as a whole. Do not set this component if you do not need to set a button.

Parameter	Type	Option	Description
type	String	required	the type of the component. Valid values: BUTTONS.
buttons	Object Array	required	button information, see buttons object description .

buttons object description

Parameter	Type	Option	Description
type	String	required	the type of the button. Valid values: QUICK_REPLY, URL, and PHONE_NUMBER.
text	String	required	the text description on the button, it cannot contain variables. It is plain text and can be up to 25 characters in length.
url	String	optional	this parameter is required when type = URL. You can set a variable at the end of the URL. You can set only one variable, represented by {{1}}.
phone_number	String	optional	required when type = PHONE_NUMBER, cannot contain variables, the content is the phone number containing the international area code.
example	String Array	optional	Required when type = QUICK_REPLY and type = URL

Response parameters

Success response

Parameter	Type	Option	Description
template_id	String	required	the ID of the template. This parameter is returned when the template is successful.

{ "template_id": "1275172986566180" // template id }

          {
    "template_id": "1275172986566180"	// template id
}

This code block in the floating window

Failed response

Parameter	Type	Option	Description
code	int	required	the error code. If the error fails, the error code is returned.
message	String	required	the error message returned when the error fails.

{ "code": 5002, "message": "Invalid parameter. code:100:2388042" }

          {
    "code": 5002,
    "message": "Invalid parameter. code:100:2388042"
}

This code block in the floating window

Update Template

call address

PUT https://wa.api.engagelab.cc/v1/templates/{templateId}

call example

{ "components": [ { // template content "type": "BODY", // content block, currently supports HEADER/BODY/FOOTER/BUTTONS "text": "define var as {{1}}" // specific text, when the body is text, there is no need to pass the format field "example": { "body_text": [ [ "var1" ] ] } }, { "type": "HEADER", "format": "image", // content type, support text/image/video/document/location "example": { "header_url": [ "https://jiguang.cn/demopic.jpg" ] } }, { "type": "FOOTER", "text": "footer only support text without variable" }, { "type": "BUTTONS", "buttons": [ { "type": "PHONE_NUMBER", // button type, support PHONE_NUMBER/URL/QUICK_REPLY "text": "this is a phone number", "phone_number": "8613800138000" } ] } ] }

          {
    "components": [
        { // template content
            "type": "BODY", // content block, currently supports HEADER/BODY/FOOTER/BUTTONS
            "text": "define var as {{1}}" // specific text, when the body is text, there is no need to pass the format field
      "example": {
                "body_text": [
                    [
                        "var1"
                    ]
                ]
            }
        },
        {
            "type": "HEADER",
            "format": "image", // content type, support text/image/video/document/location
            "example": {
                "header_url": [
                    "https://jiguang.cn/demopic.jpg"
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "footer only support text without variable"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "PHONE_NUMBER", // button type, support PHONE_NUMBER/URL/QUICK_REPLY
                    "text": "this is a phone number",
                    "phone_number": "8613800138000"
                }
            ]
        }
    ]
}

This code block in the floating window

Request parameters

It is the same as the request parameters of creating template interface.

Response parameters

Success response

Parameter	Type	Option	Description
code	int	required	return code, fixed to 0
message	String	required	the returned information. The value is fixed to success.

{ "code": 0, "message": "success" }

          {
    "code": 0,
    "message": "success"
}

This code block in the floating window

Failed response

Parameter	Type	Option	Description
code	int	required	the error code. If the error fails, the error code is returned.
message	String	required	the error message returned when the error fails.

{ "code": 5002, "message": "Invalid parameter. code:100:2593002" }

          {
    "code": 5002,
    "message": "Invalid parameter. code:100:2593002"
}

This code block in the floating window

Delete template

call address

DELETE https://wa.api.engagelab.cc/v1/templates/{template_name}

Note: The template name, not the template ID, is passed here and will delete the template content for all languages for that template name.

Response parameters

Success response

Parameter	Type	Option	Description
code	int	required	return code, fixed to 0
message	String	required	the returned information. The value is fixed to success.

{ "code": 0, "message": "success" }

          {
    "code": 0,
    "message": "success"
}

This code block in the floating window

Failed response

Parameter	Type	Option	Description
code	int	required	the error code. If the error fails, the error code is returned.
message	String	required	the error message returned when the error fails.

{ "code": 2004, "message": "something error" }

          {
    "code": 2004,
    "message": "something error"
}

This code block in the floating window

Error Codes

Code	Http Code	Description
1000	500	internal error
2001	401	EngageLab authentication failed without a valid token.
2002	401	EngageLab-side authentication failed. The token has expired or has been disabled.
2003	400	WhatsApp authentication failed, please contact EngageLab customer service
2004	403	you are not authorized to call this API.
3001	400	The request parameter format is invalid. Check whether the JSON format is used.
3002	400	The request parameters are incorrect. Check whether the request parameters meet the requirements.
3003	400	The error message returned because the request parameter is invalid.
4001	400	The template does not exist.
5002	400	The template request failed to process Meta. For more information, see the error description of the message field.

Comments

media Message Format requirements

Media Type	Supported format types Content-Type	Size Limit
image	image/jpeg, image/png, does not support transparent background	5MB
video	video/mp4	16MB
document	PDF format only	100MB

language code

Language	Code
Afrikaans	af
Albanian	sq
Arabic	ar
Azerbaijani	az
Bengali	bn
Bulgarian	bg
Catalan	ca
Chinese (CHN)	zh_CN
Chinese (HKG)	zh_HK
Chinese (TAI)	zh_TW
Croatian	hr
Czech	cs
Danish	da
Dutch	nl
English	en
English (UK)	en_GB
English (US)	en_US
Estonian	et
Filipino	fil
Finnish	fi
French	fr
Georgian	ka
German	de
Greek	el
Gujarati	gu
Hausa	ha
Hebrew	he
Hindi	hi
Hungarian	hu
Indonesian	id
Irish	ga
Italian	it
Japanese	ja
Kannada	kn
Kazakh	kk
Kinyarwanda	rw_RW
Korean	ko
Kyrgyz (Kyrgyzstan)	ky_KG
Lao	lo
Latvian	lv
Lithuanian	lt
Macedonian	mk
Malay	ms
Malayalam	ml
Marathi	mr
Norwegian	nb
Persian	fa
Polish	pl
Portuguese (BR)	pt_BR
Portuguese (POR)	pt_PT
Punjabi	pa
Romanian	ro
Russian	ru
Serbian	sr
Slovak	sk
Slovenian	sl
Spanish	es
Spanish (ARG)	es_AR
Spanish (SPA)	es_ES
Spanish (MEX)	es_MX
Swahili	sw
Swedish	sv
Tamil	ta
Telugu	te
Thai	th
Turkish	tr
Ukrainian	uk
Urdu	ur
Uzbek	uz
Vietnamese	vi
Zulu	zu

For more information about the relationship between the language and the corresponding code, you can also download this file:
Template language code.xlsx

Template Management API

Overview

Call validation

Obtain templates

call address

Request Parameters

Response parameters

response example

Query Template Information

API Endpoint

Request Parameters

Request Example

Response Parameters

Response Example

Create a template

call address

call example

Request parameters

components object

header and header components

example object description

body component

example object description

footer footer component

buttons button assembly

buttons object description

Response parameters

Success response

Failed response

Update Template

call address

call example

Request parameters

Response parameters

Success response

Failed response

Delete template

call address

Response parameters

Success response

Failed response

Error Codes

Comments

media Message Format requirements

language code