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
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
}
}
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"
}
Failure Response
{
"code": 3003,
"message": "not contains any channel config"
}
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
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>
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"
}
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"
}
}
}
Variable Filling Priority
- Priority is given to the variable values passed in
template.paramsin the sending interface; - If not passed, the default values in the template's
pre_param_mapare used; - 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 |










