创建模板配置

创建新的模板配置，支持设置模板名称、类型、内容、发送国家及签名信息。创建后模板状态为"待审核"，需通过审核后方可使用。

调用地址

POST https://smsapi.engagelab.com/v1/template-configs

调用验证

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

请求示例

请求头

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_name": "订单通知模板", "template_type": "utility", "template_content": "您的订单{order_no}已发货，预计{delivery_time}送达", "country_codes": "CN,US", "add_signature": true, "sign_id": "987654321", "sign_position": 2 }

              
              {
  "template_name": "订单通知模板",
  "template_type": "utility",
  "template_content": "您的订单{order_no}已发货，预计{delivery_time}送达",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

此代码块在浮窗中显示

请求参数

参数	类型	选项	说明
template_name	String	必填	模板名称，最大 255 个字符
template_type	String	必填	模板类型：`authentication`（认证/验证码类）、`utility`（通知类）、`marketing`（营销类）；历史值 `otp` 会兼容映射为 `authentication`
template_content	String	必填	模板内容，不能包含：`【`、`】`、`、`、`测试`、`test`、`[`、`]`
country_codes	String	必填	主要发送国家代码，逗号分隔
add_signature	Boolean	可选	是否添加签名，默认 false
sign_id	String	条件必填	当 add_signature 为 true 时必填，签名 ID
sign_position	Integer	条件必填	当 add_signature 为 true 时必填，签名位置：1-前缀，2-后缀

返回参数

成功返回

http 状态码为 200，响应体包含字段如下：

字段	类型	描述
template_id	String	创建的模板 ID

成功示例

{ "template_id": "123456789" }

              
              {
  "template_id": "123456789"
}

此代码块在浮窗中显示

失败返回

http 状态码为 4xx/5xx，响应体包含字段如下：

字段	类型	描述
code	Integer	错误码
message	String	错误详情

异常示例

{ "code": 400, "message": "sign status is not approved, can not use" }

              
              {
  "code": 400,
  "message": "sign status is not approved, can not use"
}

此代码块在浮窗中显示

错误码

错误码	HTTP 状态	可能涉及的错误
`1000`	`500`	服务内部异常；查询模板列表/详情失败；创建、更新、删除模板时数据库操作失败；查询签名信息或待发送计划失败
`2001`	`401`	鉴权失败；Authorization 缺失、格式错误、token 无效
`2002`	`401/403`	开发者 token 过期、被禁用；业务已删除
`2005`	`400`	IP 不在白名单：`ip forbidden`
`3001`	`400`	请求 JSON 格式错误：`not correct parameter format`
`3002`	`400`	`templateId` 格式错误；`template_name` 为空或超过 255 字符；`template_type` 非法；`template_content` 为空；`country_codes` 为空；`add_signature=true` 时缺少 `sign_id`；`sign_position` 非法；模板内容包含禁用字符
`3002`	`400`	认证类模板校验失败：必须包含 `{{code}}`；且只支持 `{{code}}`、`{{ttl}}` 两个变量
`3003`	`400`	添加签名时签名未审核通过；模板不属于当前业务；待审核模板不能更新；有待发送或运行中的计划使用该模板，不能更新/删除
`4001`	`400`	模板不存在：`template config not exist`；创建/更新模板时引用的签名不存在：`sign config not exist`

常见错误信息：

sign config not exist：签名配置不存在
sign status is not approved, can not use：签名状态未审核通过，不能使用
template config not exist：模板配置不存在
ip forbidden：IP 不在白名单
not correct parameter format：请求 JSON 格式错误

注意事项

模板创建后状态为"待审核"（status=1），需通过审核后方可用于发送短信
如果添加签名，签名必须是已审核通过状态
模板内容不能包含禁用字符：【、】、、、测试、test、[、]
模板和签名的 ID 都是字符串类型的数字

附录

模板配置状态 (status)

值	说明
1	待审核
2	审核通过
3	审核拒绝

模板类型 (template_type)

值	说明
authentication	认证/验证码类
utility	通知类
marketing	营销类

历史值 otp 会兼容映射为 authentication。认证类模板内容必须包含 {{code}}，且只支持 {{code}}、{{ttl}} 两个变量。

签名位置 (sign_position)

值	说明
0	无签名
1	前缀
2	后缀