Template Management API

Last updated:2023-03-09

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

    在文档中心打开
    icon
    Contact Sales