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}

このコードブロックは、フローティングウィンドウに表示されます

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 a template

call address

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

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
            }
        ]
    },
     …
]

このコードブロックは、フローティングウィンドウに表示されます

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

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

このコードブロックは、フローティングウィンドウに表示されます

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
}

このコードブロックは、フローティングウィンドウに表示されます

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

このコードブロックは、フローティングウィンドウに表示されます

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

このコードブロックは、フローティングウィンドウに表示されます

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

このコードブロックは、フローティングウィンドウに表示されます

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

このコードブロックは、フローティングウィンドウに表示されます

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

このコードブロックは、フローティングウィンドウに表示されます

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

このコードブロックは、フローティングウィンドウに表示されます

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

for more information about the relationship between the language and the corresponding code, download this file:
Template language code.xlsx

Template Management API

Overview

Call validation

Obtain a template

call address

response example

Response parameters

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