API 短信发送
若您希望自动化发送通知和营销短信，而不通过 EngageLab 平台生成，可以调用本接口。指定短信模板 ID 及目标收件人，系统将自动按模板内容发送短信。
平台配置
调用前，需要在 EngageLab SMS 控制台完成以下配置：
短信模板设置：在调用 API 前，请先前往模板管理页面，自定义并提交短信模板。模板需通过审核后，方可使用模板 ID。
API 密钥配置：前往API 密钥页面，创建 API Basic 鉴权密钥。
调用流程
请参考以下流程调用 API 发送短信，如有疑问，请联系客服。
调用地址
POST https://smsapi.engagelab.com/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": [
"923700056581"
],
"template": {
"id": 1233,
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
{
"to": [
"923700056581"
],
"template": {
"id": 1233,
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
此代码块在浮窗中显示
请求参数
一个请求对象以 JSON 格式表达，因此请求头需要带 Content-Type: application/json 。
| 名称 | 位置 | 类型 | 必选 | 中文名 | 说明 |
|---|---|---|---|---|---|
| Authorization | header | array[string] | 否 | ||
| to | body | array[string] | 是 | 发送的id list | 发送目标手机号 |
| plan_name | body | string | 否 | 计划名称 | 非必填,不填默认显示"-" |
| schedule_time | body | integer | 否 | 定时发送的时间 | 非定时发送不传该参数，时间戳 |
| template | body | object | 是 | ||
| id | body | string | 是 | ||
| params | body | object | 是 | ||
| custom_args | body | object | 否 | 自定义参数 |
如果您在创建模板时自定义了变量，则在此为它们传值，若不传，则将直接以变量Key下发，如{{var1}} |
对于params的说明
同时对于创建模版时模版内容有自定义的变量字段，也都通过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，响应体包含字段如下：
| 字段 | 类型 | 选项 | 描述 |
|---|---|---|---|
| plan_id | string | 必需 | 计划id |
| total_count | integer | 必需 | 接收到的目标数量 |
| accepted_count | integer | 必需 | 接收到的有效目标数量 |
| message_id | string | 可选 | 单个发送的时候会返回对应的 message_id |
成功示例（单目标）
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
此代码块在浮窗中显示
成功示例（多目标）
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
此代码块在浮窗中显示
成功示例（定时任务）
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
此代码块在浮窗中显示
异常示例
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
此代码块在浮窗中显示
发送异常
http 状态码为 200，响应体包含字段如下：
| 字段 | 类型 | 说明 |
|---|---|---|
| plan_id | string | 必填 |
| total_count | integer | 必填 |
| accepted_count | integer | 必填 |
| message | string | 必填 |
| code | integer | 必填 |
{
"plan_id": "string",
"total_count": 0,
"accepted_count": 0,
"message": "string",
"code": 0
}
{
"plan_id": "string",
"total_count": 0,
"accepted_count": 0,
"message": "string",
"code": 0
}
此代码块在浮窗中显示
错误码
| 错误码 | 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 字段的错误描述 |
