สร้างเทมเพลต

ที่อยู่การเรียกใช้

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 จำเป็นตามเงื่อนไข การตั้งค่ารหัส OTP จำเป็นเมื่อเทมเพลตมีประเภทรหัส OTP
verify_code_config.verify_code_type Integer จำเป็น ประเภทรหัส OTP ช่วงค่า[1,7] 1 ตัวเลข/2 ตัวอักษรภาษาอังกฤษพิมพ์เล็ก/4 ตัวอักษรภาษาอังกฤษพิมพ์ใหญ่ สามารถรวมกันได้ (เช่น 3 หมายถึงตัวเลข+ตัวอักษรพิมพ์เล็ก)
verify_code_config.verify_code_len Integer จำเป็น ความยาวรหัส OTP ช่วงค่า[4,10]
verify_code_config.verify_code_ttl Integer จำเป็น อายุการใช้งานรหัส OTP หน่วยเป็นนาที ช่วงค่า[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-รหัส OTP/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 ไม่บังคับ code ในแพลตฟอร์ม pwa ที่ใช้

ตัวอย่างคำขอ

ส่วนหัวคำขอ

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 ในกลยุทธ์การส่ง จะรองรับการกำหนดหัวข้อและเนื้อหาอีเมลแบบกำหนดเองในระดับสูง ผ่านตัวยึดตำแหน่งตัวแปร {{变量名}} สามารถเติมเนื้อหาเช่นรหัส OTP และข้อมูลแบรนด์ได้โดยอัตโนมัติ เพื่อมอบประสบการณ์อีเมลส่วนบุคคลที่ยืดหยุ่น

ประเภทตัวแปรและการใช้งาน

ทั้งเนื้อหาเทมเพลต 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: ส่ง subjectfrom_namefrom_mail ในพารามิเตอร์คำขอ template.params ก็สามารถแทนที่หัวข้อและข้อมูลผู้ส่งที่กำหนดไว้ล่วงหน้าในเทมเพลตแบบไดนามิกได้

รหัสข้อผิดพลาด

รหัสข้อผิดพลาด 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
ติดต่อฝ่ายขาย