Logo Site EngageLab Mark Colored Transparent文档
搜索

创建模板

调用地址

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

调用验证

请参考 调用验证 了解如何进行 API 鉴权。

请求

请求参数

一个请求对象以 JSON 格式表达,因此请求头需要带 Content-Type: application/json 。

参数 类型 选项 说明
template_id String 必填 自定义的模版 id,具有唯一性,限制 128 字符
description String 选填 模版的描述,限制 255 字符
send_channel_strategy String 必填 模版策略,单个通道取值为 whatsapp/sms/email/voice,多通道用|隔开,按顺序补发,email 不能和其他通道一起组成策略
brand_name String 选填 品牌标志,在某些模版样式具有品牌签名时会替换品牌签名变量,长度限制在 2-10 个字符
verify_code_config Object 条件必填 验证码的配置,模版包含验证码类型时必填
verify_code_config.verify_code_type Integer 必填 验证码类型,取值范围[1,7],1 数字/2 小写英文字母/4 大写英文字母,可组合(如 3 表示数字+小写字母)
verify_code_config.verify_code_len Integer 必填 验证码长度,取值范围[4,10]
verify_code_config.verify_code_ttl Integer 必填 验证码有效期,单位分钟,取值[1,10],策略包含 whatsapp 时只能为 1、5、10
whatsapp_config Object 条件必填 whatsapp 策略的配置,下发策略包含 whatsapp 时必填
whatsapp_config.template_type Integer 必填 whatsapp 模版类型,目前仅支持默认模版,固定为 1
whatsapp_config.template_default_config Object 条件必填 whatsapp 默认模版配置,whatsapp 模版类型为默认模版时必填
sms_config Object 条件必填 sms 策略的配置,下发策略包含 sms 时必填
sms_config.template_type Integer 必填 sms 模版类型,1-默认模版/2-自定义模版
sms_config.template_default_config Object 条件必填 sms 默认模版配置,sms 模版类型为默认模版时必填
sms_config.template_custom_config Object 条件必填 sms 自定义模版配置,sms 模版类型为自定义模版时必填
sms_config.template_custom_config.custom_sub_type String 必填 自定义模版类型,authentication-验证码/marketing-营销/utility-通知
sms_config.template_custom_config.custom_content String 必填 自定义模版内容,authentication 类型时必须包含{{code}}变量
sms_config.template_custom_config.custom_country_codes String 选填 目标国家地区代码,逗号分隔,用于模版审核时参考
voice_config Object 条件必填 voice 策略的配置,下发策略包含 voice 时必填
voice_config.template_type Integer 必填 voice 模版类型,目前仅支持默认模版,固定为 1
voice_config.template_default_config Object 条件必填 voice 默认模版配置,voice 模版类型为默认模版时必填
email_config Object 条件必填 email 策略的配置,下发策略包含 email 时必填
email_config.template_name String 必填 email 模版名称
email_config.template_custom_configs Array 条件必填 email 自定义模版配置,email 模版类型为自定义模版时必填,支持多语言配置
email_config.template_custom_configs.language String 必填 语言,default 为默认,消息下发时可根据 language 参数匹配不同模版内容
email_config.template_custom_configs.pre_from_name String 选填 预设的发送人名称
email_config.template_custom_configs.pre_from_mail String 必填 预设的发送人邮箱
email_config.template_custom_configs.pre_subject String 必填 预设的邮件主题
email_config.template_custom_configs.template_content String 必填 邮件内容,支持 html,变量需用{{}}括起来
email_config.template_custom_configs.pre_param_map Object 选填 邮件内容变量的默认值,key-value 对声明,value 需要使用字符串
pwa_config Object 选填 pwa 相关配置,暂时可不使用
pwa_config.pwa_platform String 选填 使用的 pwa 平台,具体取值请与技术支持联系获取
pwa_config.pwa_code String 选填 使用的 pwa 平台中的 code

请求示例

请求头

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

            
此代码块在浮窗中显示

请求体

{ "template_id": "test-template-1", // 自定义的模版id,应用内唯一 "description": "测试模版1", // 该模版的描述说明 "send_channel_strategy": "whatsapp|sms", // 模版的下发策略,支持whatsapp/sms/voice/email四类,组合策略则使用|字符表示失败补发 "brand_name": "品牌名称", // 品牌名称,用在一些国家地区模版内容中的签名(如短信通道中一些国家地区要求要注册签名) "verify_code_config": { // 验证码的配置,用于配置自动生成的验证码,模版包含验证码类型时必填 "verify_code_type": 1, // 验证码类型,取值范围[1,7] "verify_code_len": 6, // 验证码长度,取值范围[4,10] "verify_code_ttl": 1 // 验证码有效期,取值范围[1,10],注意当策略包含whatsapp时取值只能是1,5,10 }, "whatsapp_config": { // whatsapp策略的配置,当下发策略包含whatsapp时有效 "template_type": 1, // whatsapp模版类型,目前仅支持默认模版,即固定取值为1 "template_default_config": { // whatsapp默认模版配置,针对默认模版类型时有效 "contain_security": false, // 是否添加安全提醒 "contain_expire": false // 是否添加过期时间内容 } }, "sms_config": { // sms策略的配置,当下发策略包含sms时有效 "template_type": 2, // sms模版类型,取值:1-默认模版/2-自定义模版 "template_default_config": { // sms默认模版配置,针对默认模版类型时有效 "contain_security": false, // 是否添加安全提醒 "contain_expire": false // 是否添加过期时间内容 }, "template_custom_config": { // sms自定义模版配置,sms模版类型为自定义模版时有效 "custom_sub_type": "authentication", // 自定义模版类型,取值:authentication-验证码/marketing-营销/utility-通知 "custom_content": "xxx", // 自定义模版内容,注意若子类型为authentication验证码类型时必须包含{{code}}变量 "custom_country_codes": "HK,PH" // 自定义模版的目标国家地区,用于模版审核时参考,请按实际填写,否则可能影响实际下发 } }, "voice_config": { // voice策略的配置,当下发策略包含voice时有效 "template_type": 1, // voice模版类型,目前仅支持默认模版,即固定取值为1 "template_default_config": { // voice默认模版配置,针对默认模版类型时有效 "contain_security": false, // 是否添加安全提醒 "contain_expire": false // 是否添加过期时间内容 } }, "email_config": { // email策略的配置,当下发策略包含email时有效 "template_name": "email模板名称", // email模版名称 "template_custom_configs": [{ // email自定义模版配置,注意这里是对象数组,主要是通过language进行区分配置多个 "language": "default", // 语言,default为默认,消息下发时可以根据language参数来匹配不同的模版内容 "pre_from_name": "test", // 预设的发送人名称 "pre_from_mail": "test@test.com", // 预设的发送人邮箱 "pre_subject": "test", // 预设的邮件主题 "template_content": "预设邮件模版内容,必填,自定义变量如{{self}},验证码是{{code}}", // 邮件内容,支持html,变量需要使用两个大括号{{}}括起来 "pre_param_map": { // 邮件内容中变量的默认值,即下发时若不指定变量值,则采用下述的默认值来替换变量,采用key-value对声明,value需要使用字符串 "self": "这里是self变量预设值" } }] }, "pwa_config": { // pwa相关的配置,暂时可以不使用 "pwa_platform": "xx", // 使用的pwa平台,具体取值请与技术支持联系获取确定 "pwa_code": "xx" // 使用的pwa平台中的code } }
              
              {
    "template_id": "test-template-1",       // 自定义的模版id,应用内唯一
    "description": "测试模版1",                 // 该模版的描述说明
    "send_channel_strategy": "whatsapp|sms",    // 模版的下发策略,支持whatsapp/sms/voice/email四类,组合策略则使用|字符表示失败补发
    "brand_name": "品牌名称",                   // 品牌名称,用在一些国家地区模版内容中的签名(如短信通道中一些国家地区要求要注册签名)
    "verify_code_config": {                     // 验证码的配置,用于配置自动生成的验证码,模版包含验证码类型时必填
        "verify_code_type": 1,                  // 验证码类型,取值范围[1,7]
        "verify_code_len": 6,                   // 验证码长度,取值范围[4,10]
        "verify_code_ttl": 1                    // 验证码有效期,取值范围[1,10],注意当策略包含whatsapp时取值只能是1,5,10
    },
    "whatsapp_config": {                        // whatsapp策略的配置,当下发策略包含whatsapp时有效
        "template_type": 1,                      // whatsapp模版类型,目前仅支持默认模版,即固定取值为1
        "template_default_config": {            // whatsapp默认模版配置,针对默认模版类型时有效
            "contain_security": false,              // 是否添加安全提醒
            "contain_expire": false                 // 是否添加过期时间内容
        }
    },
    "sms_config": {                             // sms策略的配置,当下发策略包含sms时有效
        "template_type": 2,                     // sms模版类型,取值:1-默认模版/2-自定义模版
        "template_default_config": {            // sms默认模版配置,针对默认模版类型时有效
            "contain_security": false,              // 是否添加安全提醒
            "contain_expire": false                 // 是否添加过期时间内容
        },
        "template_custom_config": {             // sms自定义模版配置,sms模版类型为自定义模版时有效
            "custom_sub_type": "authentication",    // 自定义模版类型,取值:authentication-验证码/marketing-营销/utility-通知
            "custom_content": "xxx",                // 自定义模版内容,注意若子类型为authentication验证码类型时必须包含{{code}}变量
            "custom_country_codes": "HK,PH"         // 自定义模版的目标国家地区,用于模版审核时参考,请按实际填写,否则可能影响实际下发
        }
    },
    "voice_config": {                           // voice策略的配置,当下发策略包含voice时有效
        "template_type": 1,                      // voice模版类型,目前仅支持默认模版,即固定取值为1
        "template_default_config": {            // voice默认模版配置,针对默认模版类型时有效
            "contain_security": false,              // 是否添加安全提醒
            "contain_expire": false                 // 是否添加过期时间内容
        }
    },
    "email_config": {                           // email策略的配置,当下发策略包含email时有效
        "template_name": "email模板名称",                     // email模版名称
        "template_custom_configs": [{           // email自定义模版配置,注意这里是对象数组,主要是通过language进行区分配置多个
            "language": "default",              // 语言,default为默认,消息下发时可以根据language参数来匹配不同的模版内容
            "pre_from_name": "test",            // 预设的发送人名称
            "pre_from_mail": "test@test.com",   // 预设的发送人邮箱
            "pre_subject": "test",              // 预设的邮件主题
            "template_content": "预设邮件模版内容,必填,自定义变量如{{self}},验证码是{{code}}",    // 邮件内容,支持html,变量需要使用两个大括号{{}}括起来
            "pre_param_map": {                  // 邮件内容中变量的默认值,即下发时若不指定变量值,则采用下述的默认值来替换变量,采用key-value对声明,value需要使用字符串
                "self": "这里是self变量预设值"
            }
        }]
    },
    "pwa_config": {                             // pwa相关的配置,暂时可以不使用
        "pwa_platform": "xx",                   // 使用的pwa平台,具体取值请与技术支持联系获取确定
        "pwa_code": "xx"                        // 使用的pwa平台中的code
    }
}

            
此代码块在浮窗中显示

响应

响应参数

字段 类型 选项 描述
code Integer 必填 错误码,0 表示成功,其他为失败
message String 必填 响应信息

响应示例

成功返回

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

            
此代码块在浮窗中显示

失败返回

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

            
此代码块在浮窗中显示

Email 模板变量高级用法

当您在发送策略中启用 Email 通道时,支持高度自定义邮件主题和正文内容。通过变量占位符 {{变量名}},可自动填充验证码、品牌信息等内容,实现灵活的个性化邮件体验。

变量类型及用法

Email 模板正文(template_content)和主题(pre_subject)均可嵌入变量,格式为 {{变量名}}

发送 API 通过 template.params 字段动态传入,或在模板创建阶段设置默认值。

支持的变量

下面变量仅 Email 通道适用。

变量名 类型 说明 填充方式
{{logo_url}} 自定义变量 品牌 Logo 图片地址 发送时通过 template.params 传入
{{title}} 自定义变量 邮件正文标题文字 发送时通过 template.params 传入
{{support_email}} 自定义变量 客服/支持邮箱地址 发送时通过 template.params 传入
{{subject}} 自定义变量 动态覆盖邮件主题 发送时通过 template.params 传入
{{from_name}} 自定义变量 动态覆盖发件人名称 发送时通过 template.params 传入
{{from_mail}} 自定义变量 动态覆盖发件人邮箱 发送时通过 template.params 传入

注意{{subject}}{{from_name}}{{from_mail}} 这几个特殊变量不会插入到正文 HTML,而是直接覆盖邮件的元数据字段。

邮件主题示例

{{brand_name}} 验证码
              
              {{brand_name}} 验证码

            
此代码块在浮窗中显示

邮件正文示例

<img src="{{logo_url}}" /> <strong>{{title}}</strong> <p>您的验证码是 <strong>{{code}}</strong>,请在 {{ttl}} 分钟内完成验证。</p> <p>如有疑问,请联系 <a href="mailto:{{support_email}}">{{support_email}}</a></p>
              
              <img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>您的验证码是 <strong>{{code}}</strong>,请在 {{ttl}} 分钟内完成验证。</p>
<p>如有疑问,请联系 <a href="mailto:{{support_email}}">{{support_email}}</a></p>

            
此代码块在浮窗中显示

模板默认值设置

模板创建时,可在 pre_param_map 字段设置自定义变量的默认值。发送邮件时未传入变量时,将自动使用默认值。

"pre_param_map": { "logo_url": "https://example.com/logo.png", "title": "您的验证码", "support_email": "support@example.com" }
              
              "pre_param_map": {
  "logo_url": "https://example.com/logo.png",
  "title": "您的验证码",
  "support_email": "support@example.com"
}

            
此代码块在浮窗中显示

发送参数说明

字段 类型 必填 说明
to string 目标邮箱地址
template.id string 邮件模板 ID
template.language string 语言代码,默认 default
template.params object 模板变量赋值(不含 {{}}

示例请求:

{ "to": "user@example.com", "template": { "id": "my_email_template", "language": "default", "params": { "logo_url": "https://example.com/logo.png", "title": "您的验证码", "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": "您的验证码",
      "support_email": "support@example.com"
    }
  }
}

            
此代码块在浮窗中显示

变量填充优先级

  1. 优先使用发送接口中 template.params 传入的变量值;
  2. 若未传入,则使用模板 pre_param_map 中的默认值;
  3. 若两者均未设置,则占位符原样显示在邮件内容中。

常见问题解答

Q: 为什么变量未被替换?
A: 请确认变量名书写及格式正确(需 {{变量名}}),并确保已通过 template.params 提供值,或模板已设置默认值。

Q: 如何动态设置邮件主题、发件人?
A: 在请求参数 template.params 内传入 subjectfrom_namefrom_mail,即可动态覆盖模板预设的主题和发件人信息。

错误码

错误码 http code 说明
1000 500 内部错误
2001 401 鉴权失败,未携带正确的 token
2002 401 鉴权失败,token 已过期或已被禁用
2004 403 无调用此 API 的权限
3001 400 请求参数格式无效,请检查是否符合参数格式的 JSON 内容
3002 400 请求参数有误,请检查请求参数是否符合要求
3003 400 业务级别的参数错误,请检查返回 message 字段说明
Icon Solid Transparent White Qiyu
联系销售