สร้างเทมเพลต
ที่อยู่การเรียกใช้
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
เนื้อหาคำขอ
{
"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": 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}} 验证码
ตัวอย่างเนื้อหาอีเมล
<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"
}
คำอธิบายพารามิเตอร์การส่ง
| ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
|---|---|---|---|
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"
}
}
}
ลำดับความสำคัญของการเติมค่าตัวแปร
- ใช้ค่าตัวแปรที่ส่งผ่าน
template.paramsในอินเทอร์เฟซการส่งก่อนเป็นอันดับแรก - หากไม่ได้ส่งเข้ามา จะใช้ค่าเริ่มต้นใน
pre_param_mapของเทมเพลต - หากทั้งสองอย่างไม่ได้ตั้งค่า ตัวยึดตำแหน่งจะแสดงตามเดิมในเนื้อหาอีเมล
คำถามที่พบบ่อย
Q: ทำไมตัวแปรจึงไม่ถูกแทนที่?
A: โปรดยืนยันว่าการเขียนชื่อตัวแปรและรูปแบบถูกต้อง (ต้องเป็น {{变量名}}) และตรวจสอบให้แน่ใจว่าได้ระบุค่าผ่าน template.params หรือเทมเพลตได้ตั้งค่าเริ่มต้นไว้แล้ว
Q: จะตั้งค่าหัวข้ออีเมลและผู้ส่งแบบไดนามิกได้อย่างไร?
A: ส่ง subject、from_name、from_mail ในพารามิเตอร์คำขอ template.params ก็สามารถแทนที่หัวข้อและข้อมูลผู้ส่งที่กำหนดไว้ล่วงหน้าในเทมเพลตแบบไดนามิกได้
รหัสข้อผิดพลาด
| รหัสข้อผิดพลาด | http code | คำอธิบาย |
|---|---|---|
| 1000 | 500 | ข้อผิดพลาดภายใน |
| 2001 | 401 | การยืนยันตัวตนล้มเหลว ไม่ได้แนบ token ที่ถูกต้อง |
| 2002 | 401 | การยืนยันตัวตนล้มเหลว token หมดอายุหรือถูกปิดใช้งานแล้ว |
| 2004 | 403 | ไม่มีสิทธิ์เรียกใช้ API นี้ |
| 3001 | 400 | รูปแบบพารามิเตอร์คำขอไม่ถูกต้อง โปรดตรวจสอบว่าเนื้อหา JSON สอดคล้องกับรูปแบบพารามิเตอร์หรือไม่ |
| 3002 | 400 | พารามิเตอร์คำขอไม่ถูกต้อง โปรดตรวจสอบว่าพารามิเตอร์คำขอตรงตามข้อกำหนดหรือไม่ |
| 3003 | 400 | พารามิเตอร์ผิดพลาดในระดับธุรกิจ โปรดตรวจสอบคำอธิบายในฟิลด์ message ที่คืนค่า |










