Logo Site EngageLab Mark Colored TransparentDocument
Search

Create Template

Request URL

POST https://otp.api.engagelab.cc/v1/template-configs

Authentication

Please refer to Authentication to learn how to perform API authentication.

Request

Request Parameters

A request object is expressed in JSON format, so the request header must include Content-Type: application/json.

Parameter Type Option Description
template_id String Required Custom template id, must be unique, limited to 128 characters
description String Optional Description of the template, limited to 255 characters
send_channel_strategy String Required Template strategy, single channel values are whatsapp/sms/email/voice, multi-channel separated by |, fallback in order, email cannot be combined with other channels
brand_name String Optional Brand logo, replaces the brand signature variable when some template styles have a brand signature, length limited to 2-10 characters
verify_code_config Object Conditionally Required Verification code configuration, required when the template contains a verification code type
verify_code_config.verify_code_type Integer Required Verification code type, value range [1,7], 1 number/2 lowercase letter/4 uppercase letter, can be combined (e.g., 3 means number + lowercase letter)
verify_code_config.verify_code_len Integer Required Verification code length, value range [4,10]
verify_code_config.verify_code_ttl Integer Required Verification code validity period in minutes, value range [1,10], when the strategy includes whatsapp it can only be 1, 5, 10
whatsapp_config Object Conditionally Required whatsapp strategy configuration, required when the delivery strategy includes whatsapp
whatsapp_config.template_type Integer Required whatsapp template type, currently only supports default template, fixed to 1
whatsapp_config.template_default_config Object Conditionally Required whatsapp default template configuration, required when whatsapp template type is default template
sms_config Object Conditionally Required sms strategy configuration, required when the delivery strategy includes sms
sms_config.template_type Integer Required sms template type, 1-default template/2-custom template
sms_config.template_default_config Object Conditionally Required sms default template configuration, required when sms template type is default template
sms_config.template_custom_config Object Conditionally Required sms custom template configuration, required when sms template type is custom template
sms_config.template_custom_config.custom_sub_type String Required Custom template type, authentication/marketing/utility
sms_config.template_custom_config.custom_content String Required Custom template content, must contain {{code}} variable when type is authentication
sms_config.template_custom_config.custom_country_codes String Optional Target country/region codes, comma-separated, used for reference during template audit
voice_config Object Conditionally Required voice strategy configuration, required when the delivery strategy includes voice
voice_config.template_type Integer Required voice template type, currently only supports default template, fixed to 1
voice_config.template_default_config Object Conditionally Required voice default template configuration, required when voice template type is default template
email_config Object Conditionally Required email strategy configuration, required when the delivery strategy includes email
email_config.template_name String Required email template name
email_config.template_custom_configs Array Conditionally Required email custom template configuration, required when email template type is custom template, supports multi-language configuration
email_config.template_custom_configs.language String Required Language, default is default, different template content can be matched according to the language parameter during message delivery
email_config.template_custom_configs.pre_from_name String Optional Preset sender name
email_config.template_custom_configs.pre_from_mail String Required Preset sender email
email_config.template_custom_configs.pre_subject String Required Preset email subject
email_config.template_custom_configs.template_content String Required Email content, supports html, variables need to be enclosed in {{}}
email_config.template_custom_configs.pre_param_map Object Optional Default values for variables in email content, declared as key-value pairs, value needs to be a string
pwa_config Object Optional pwa related configuration, temporarily not used
pwa_config.pwa_platform String Optional pwa platform used, please contact technical support for specific values
pwa_config.pwa_code String Optional code in the pwa platform used

Request Example

Request Header

POST /v1/template-configs HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
              
              POST /v1/template-configs  HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            
This code block in the floating window

Request Body

{ "template_id": "test-template-1", // Custom template id, unique within the application "description": "Test template 1", // Description of the template "send_channel_strategy": "whatsapp|sms",// Template delivery strategy, supports whatsapp/sms/voice/email. Combined strategies use the | character to indicate fallback on failure "brand_name": "Brand Name", // Brand name, used for signatures in template content in some countries/regions (e.g., some countries require registered signatures in the SMS channel) "verify_code_config": { // Verification code configuration, used to configure automatically generated verification codes, required when the template contains a verification code type "verify_code_type": 1, // Verification code type, value range [1,7] "verify_code_len": 6, // Verification code length, value range [4,10] "verify_code_ttl": 1 // Verification code validity period, value range [1,10], note that when the strategy includes whatsapp, the value can only be 1, 5, 10 }, "whatsapp_config": { // whatsapp strategy configuration, valid when the delivery strategy includes whatsapp "template_type": 1, // whatsapp template type, currently only supports default template, fixed value is 1 "template_default_config": { // whatsapp default template configuration, valid for default template type "contain_security": false, // Whether to add security reminder "contain_expire": false // Whether to add expiration time content } }, "sms_config": { // sms strategy configuration, valid when the delivery strategy includes sms "template_type": 2, // sms template type, values: 1-default template/2-custom template "template_default_config": { // sms default template configuration, valid for default template type "contain_security": false, // Whether to add security reminder "contain_expire": false // Whether to add expiration time content }, "template_custom_config": { // sms custom template configuration, valid when sms template type is custom template "custom_sub_type": "authentication", // Custom template type, values: authentication/marketing/utility "custom_content": "xxx", // Custom template content, note that if the sub-type is authentication, it must contain the {{code}} variable "custom_country_codes": "HK,PH" // Target country/region for custom template, used for reference during template audit, please fill in according to actual situation, otherwise it may affect actual delivery } }, "voice_config": { // voice strategy configuration, valid when the delivery strategy includes voice "template_type": 1, // voice template type, currently only supports default template, fixed value is 1 "template_default_config": { // voice default template configuration, valid for default template type "contain_security": false, // Whether to add security reminder "contain_expire": false // Whether to add expiration time content } }, "email_config": { // email strategy configuration, valid when the delivery strategy includes email "template_name": "email template name", // email template name "template_custom_configs": [{ // email custom template configuration, note this is an object array, mainly used to configure multiple languages via language "language": "default", // Language, default is default, different template content can be matched according to the language parameter during message delivery "pre_from_name": "test", // Preset sender name "pre_from_mail": "test@test.com",// Preset sender email "pre_subject": "test", // Preset email subject "template_content": "Preset email template content, required, custom variables like {{self}}, verification code is {{code}}", // Email content, supports html, variables need to be enclosed in double braces {{}} "pre_param_map": { // Default values for variables in email content, i.e., if variable values are not specified during delivery, the following default values will be used to replace variables, declared as key-value pairs, value needs to be a string "self": "Here is the preset value for the self variable" } }] }, "pwa_config": { // pwa related configuration, temporarily not used "pwa_platform": "xx", // pwa platform used, please contact technical support for specific values "pwa_code": "xx" // code in the pwa platform used } }
              
              {
    "template_id": "test-template-1",       // Custom template id, unique within the application
    "description": "Test template 1",       // Description of the template
    "send_channel_strategy": "whatsapp|sms",// Template delivery strategy, supports whatsapp/sms/voice/email. Combined strategies use the | character to indicate fallback on failure
    "brand_name": "Brand Name",             // Brand name, used for signatures in template content in some countries/regions (e.g., some countries require registered signatures in the SMS channel)
    "verify_code_config": {                 // Verification code configuration, used to configure automatically generated verification codes, required when the template contains a verification code type
        "verify_code_type": 1,              // Verification code type, value range [1,7]
        "verify_code_len": 6,               // Verification code length, value range [4,10]
        "verify_code_ttl": 1                // Verification code validity period, value range [1,10], note that when the strategy includes whatsapp, the value can only be 1, 5, 10
    },
    "whatsapp_config": {                    // whatsapp strategy configuration, valid when the delivery strategy includes whatsapp
        "template_type": 1,                 // whatsapp template type, currently only supports default template, fixed value is 1
        "template_default_config": {        // whatsapp default template configuration, valid for default template type
            "contain_security": false,      // Whether to add security reminder
            "contain_expire": false         // Whether to add expiration time content
        }
    },
    "sms_config": {                         // sms strategy configuration, valid when the delivery strategy includes sms
        "template_type": 2,                 // sms template type, values: 1-default template/2-custom template
        "template_default_config": {        // sms default template configuration, valid for default template type
            "contain_security": false,      // Whether to add security reminder
            "contain_expire": false         // Whether to add expiration time content
        },
        "template_custom_config": {         // sms custom template configuration, valid when sms template type is custom template
            "custom_sub_type": "authentication", // Custom template type, values: authentication/marketing/utility
            "custom_content": "xxx",        // Custom template content, note that if the sub-type is authentication, it must contain the {{code}} variable
            "custom_country_codes": "HK,PH" // Target country/region for custom template, used for reference during template audit, please fill in according to actual situation, otherwise it may affect actual delivery
        }
    },
    "voice_config": {                       // voice strategy configuration, valid when the delivery strategy includes voice
        "template_type": 1,                 // voice template type, currently only supports default template, fixed value is 1
        "template_default_config": {        // voice default template configuration, valid for default template type
            "contain_security": false,      // Whether to add security reminder
            "contain_expire": false         // Whether to add expiration time content
        }
    },
    "email_config": {                       // email strategy configuration, valid when the delivery strategy includes email
        "template_name": "email template name", // email template name
        "template_custom_configs": [{       // email custom template configuration, note this is an object array, mainly used to configure multiple languages via language
            "language": "default",          // Language, default is default, different template content can be matched according to the language parameter during message delivery
            "pre_from_name": "test",        // Preset sender name
            "pre_from_mail": "test@test.com",// Preset sender email
            "pre_subject": "test",          // Preset email subject
            "template_content": "Preset email template content, required, custom variables like {{self}}, verification code is {{code}}", // Email content, supports html, variables need to be enclosed in double braces {{}}
            "pre_param_map": {              // Default values for variables in email content, i.e., if variable values are not specified during delivery, the following default values will be used to replace variables, declared as key-value pairs, value needs to be a string
                "self": "Here is the preset value for the self variable"
            }
        }]
    },
    "pwa_config": {                         // pwa related configuration, temporarily not used
        "pwa_platform": "xx",               // pwa platform used, please contact technical support for specific values
        "pwa_code": "xx"                    // code in the pwa platform used
    }
}

            
This code block in the floating window

Response

Response Parameters

Field Type Option Description
code Integer Required Error code, 0 means success, others mean failure
message String Required Response message

Response Example

Success Response

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

            
This code block in the floating window

Failure Response

{ "code": 3003, "message": "not contains any channel config" }
              
              {
    "code": 3003,
    "message": "not contains any channel config"
}

            
This code block in the floating window

Email Template Variables Advanced Usage

When you enable the Email channel in the sending strategy, it supports highly customized email subjects and body content. Through variable placeholders {{variable_name}}, you can automatically fill in verification codes, brand information, etc., to achieve a flexible and personalized email experience.

Variable Types and Usage

Variables can be embedded in both the Email template body (template_content) and subject (pre_subject), in the format {{variable_name}}.

The sending API dynamically passes them through the template.params field, or sets default values during the template creation phase.

Supported Variables

The following variables are only applicable to the Email channel.

Variable Name Type Description Filling Method
{{logo_url}} Custom Variable Brand Logo image URL Passed via template.params when sending
{{title}} Custom Variable Email body title text Passed via template.params when sending
{{support_email}} Custom Variable Customer service/support email Passed via template.params when sending
{{subject}} Custom Variable Dynamically override email subject Passed via template.params when sending
{{from_name}} Custom Variable Dynamically override sender name Passed via template.params when sending
{{from_mail}} Custom Variable Dynamically override sender email Passed via template.params when sending

Note: The special variables {{subject}}, {{from_name}}, and {{from_mail}} will not be inserted into the body HTML, but will directly override the email's metadata fields.

Email Subject Example

{{brand_name}} Verification Code
              
              {{brand_name}} Verification Code

            
This code block in the floating window

Email Body Example

<img src="{{logo_url}}" /> <strong>{{title}}</strong> <p>Your verification code is <strong>{{code}}</strong>, please complete verification within {{ttl}} minutes.</p> <p>If you have any questions, please contact <a href="mailto:{{support_email}}">{{support_email}}</a></p>
              
              <img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>Your verification code is <strong>{{code}}</strong>, please complete verification within {{ttl}} minutes.</p>
<p>If you have any questions, please contact <a href="mailto:{{support_email}}">{{support_email}}</a></p>

            
This code block in the floating window

Template Default Value Setting

When creating a template, you can set default values for custom variables in the pre_param_map field. If no variables are passed when sending the email, the default values will be automatically used.

"pre_param_map": { "logo_url": "https://example.com/logo.png", "title": "Your Verification Code", "support_email": "support@example.com" }
              
              "pre_param_map": {
  "logo_url": "https://example.com/logo.png",
  "title": "Your Verification Code",
  "support_email": "support@example.com"
}

            
This code block in the floating window

Sending Parameter Description

Field Type Required Description
to string Yes Target email address
template.id string Yes Email template ID
template.language string No Language code, default default
template.params object No Template variable assignment (without {{}})

Example Request:

{ "to": "user@example.com", "template": { "id": "my_email_template", "language": "default", "params": { "logo_url": "https://example.com/logo.png", "title": "Your Verification Code", "support_email": "support@example.com" } } }
              
              {
  "to": "user@example.com",
  "template": {
    "id": "my_email_template",
    "language": "default",
    "params": {
      "logo_url": "https://example.com/logo.png",
      "title": "Your Verification Code",
      "support_email": "support@example.com"
    }
  }
}

            
This code block in the floating window

Variable Filling Priority

  1. Priority is given to the variable values passed in template.params in the sending interface;
  2. If not passed, the default values in the template's pre_param_map are used;
  3. If neither is set, the placeholders will be displayed as is in the email content.

Frequently Asked Questions

Q: Why are the variables not replaced?
A: Please confirm that the variable name is written and formatted correctly (requires {{variable_name}}), and ensure that the value has been provided via template.params, or the template has set a default value.

Q: How to dynamically set the email subject and sender?
A: Pass subject, from_name, and from_mail in the request parameter template.params to dynamically override the template's preset subject and sender information.

Error Codes

Error Code HTTP Code Description
1000 500 Internal error
2001 401 Authentication failed, incorrect token carried
2002 401 Authentication failed, token has expired or been disabled
2004 403 No permission to call this API
3001 400 Invalid request parameter format, please check if the JSON content conforms to the parameter format
3002 400 Incorrect request parameters, please check if the request parameters meet the requirements
3003 400 Business-level parameter error, please check the returned message field description
Icon Solid Transparent White Qiyu
Contact Sales