API 短信发送
若您希望自动化发送通知和营销短信，而不通过 EngageLab 平台生成，可以调用本接口。指定短信模板 ID 及目标收件人，系统将自动按模板内容发送短信。
平台配置
调用前，需要在 EngageLab NewSMS 控制台完成以下配置：
短信模板设置：在调用 API 前，请先前往模板管理页面，自定义并提交短信模板。模板需通过审核后，方可使用模板 ID。
API 密钥配置：前往API 密钥页面，创建 API Basic 鉴权密钥。
调用流程
请参考以下流程调用 API 发送短信，如有疑问，请联系客服。
调用地址
POST https://smsapi.engagelab.cc/v1/messages
调用验证
采用 HTTP 基本认证 的验证方式，在 HTTP Header（头）里加 Authorization：
Authorization: Basic ${base64_auth_string}
Authorization: Basic ${base64_auth_string}
此代码块在浮窗中显示
上述 base64_auth_string 的生成算法为：base64(dev_key:dev_secret)
请求格式
请求头
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
此代码块在浮窗中显示
请求体
{
"to_ids": [
"8613138283670"
],
"plan_name": "test",
"template": {
"id": 1970314609822883800,
"language": "en",
"params": {
"content": "erification code: 039487, will expire in 5 minutes. You are trying to create your"
}
},
"source": 1
}
{
"to_ids": [
"8613138283670"
],
"plan_name": "test",
"template": {
"id": 1970314609822883800,
"language": "en",
"params": {
"content": "erification code: 039487, will expire in 5 minutes. You are trying to create your"
}
},
"source": 1
}
此代码块在浮窗中显示
请求参数
一个请求对象以 JSON 格式表达，因此请求头需要带 Content-Type: application/json 。
| 名称 | 位置 | 类型 | 必选 | 中文名 | 说明 |
|---|---|---|---|---|---|
| Authorization | header | array[string] | 否 | none | |
| body | body | object | 否 | none | |
| » to_ids | body | [string] | 是 | 发送的id list | 如果只有一个就传一个就可以了 |
| » plan_name | body | string | 否 | 计划名称 | 非必填,不填默认显示"-" |
| » schedule_time | body | integer | 否 | 定时发送的时间 | 非定时发送不传该参数，时间戳 |
| » template | body | object | 是 | ||
| »» id | body | string | 是 | none | |
| »» language | body | string | 是 | none | |
| »» params | body | object | 是 | none | |
| »»» custom_param | body | string | 是 | none | |
| » custom_args | body | object | 是 | 自定义参数 |
如果您在创建模板时自定义了变量，则在此为它们传值，若不传，则将直接以变量Key下发，如{{var1}} |
对于params的说明
- 对于{{brand_name}}，{{ttl}}，{{pwa_url}} 等模版预设变量，不需要传递，系统会自动替换为模板创建时指定的内容；
- 同时对于创建模版时模版内容有自定义的变量字段，也都通过params进行赋值，如模版内容
Hi {{name}}, welcome to EngageLab，此时需要赋值参数params:{"name":"Bob"}
请求示例
1. 发送自定义通知内容：
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
此代码块在浮窗中显示
2. 发送自定义营销内容：
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
此代码块在浮窗中显示
返回参数
成功返回
http 状态码为 200，响应体包含字段如下：
| 字段 | 类型 | 选项 | 描述 |
|---|---|---|---|
| message_id | String | 必填 | 消息 ID，唯一标识某一条消息 |
| to_id | String | 必填 | 发送的手机号 |
{
"to_id": "8613138283670",
"message_id": "1971029055205646336"
}
{
"to_id": "8613138283670",
"message_id": "1971029055205646336"
}
此代码块在浮窗中显示
失败返回
http 状态码为 4xx 或者 5xx，响应体包含字段如下：
| 字段 | 类型 | 选项 | 描述 |
|---|---|---|---|
| err_code | int | 必填 | 错误码，详见 错误码说明 |
| err_msg | String | 必填 | 错误详情 |
{
"err_msg": "sms send failed",
"err_code": 10013
}
{
"err_msg": "sms send failed",
"err_code": 10013
}
此代码块在浮窗中显示
错误码
| 错误码 | http code | 说明 |
|---|---|---|
| 1000 | 500 | 内部错误 |
| 2001 | 401 | 鉴权失败，未携带正确的 token |
| 2002 | 401 | 鉴权失败，token已过期或已被禁用 |
| 2004 | 403 | 无调用此 API 的权限 |
| 3001 | 400 | 请求参数格式无效，请检查是否符合参数格式的 JSON 内容 |
| 3002 | 400 | 请求参数有误，请检查请求参数是否符合要求 |
| 3003 | 400 | 请求参数有误，相关业务校验失败，详情参考 message 字段的错误描述 |
| 3004 | 400 | 超出频率限制，针对同一模版以及同一目标用户，在验证码的有效期内无法再次下发 |
| 4001 | 400 | 相关资源不存在，如模版消息下发时使用了不存在的模版 |
| 5001 | 400 | 验证码消息下发失败，详情参考 message 字段的错误描述 |
