发送短信
若您希望自动化发送通知和营销短信，可以调用本接口。指定短信模板 ID 及目标收件人，系统将自动按模板内容发送短信。
平台配置提示 调用前，需要在 EngageLab SMS 控制台完成以下配置：
调用地址
POST https://smsapi.engagelab.com/v1/messages
调用验证
请参考 调用验证 了解如何进行 API 鉴权。
请求示例
请求头
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。
| 参数 | 类型 | 选项 | 说明 |
|---|---|---|---|
| to | Array[String] | 必填 | 发送目标手机号列表，如 ["923700056581"] |
| plan_name | String | 可选 | 计划名称，不填默认显示 "-" |
| schedule_time | Integer | 可选 | 定时发送的时间。非定时发送不传该参数。Unix 时间戳，单位是「秒」。 校验规则：必须为正数；必须严格晚于当前时刻至少 3 分钟；不能超过从当前时刻起 30 天。 |
| template | JSON Object | 必填 | 模板信息，所含二级参数见下方 |
| |_ id | String | 必填 | 模板 ID |
| |_ params | JSON Object | 必填 | 自定义模板变量 Key 的取值 如果您在创建模板时自定义了变量，则在此为它们传值，若不传，则将直接以变量 Key 下发，如 {{var1}} |
| custom_args | JSON Object | 可选 | 自定义参数 |
对于 params 的说明
对于创建模版时模版内容有自定义的变量字段，都需要通过 params 进行赋值。例如模版内容为 Hi {{name}}, welcome to EngageLab，此时需要赋值参数 params: {"name": "Bob"}。
更多请求示例
1. 发送自定义通知内容：
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
此代码块在浮窗中显示
2. 发送自定义营销内容：
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
{
"to": ["+6591234567"],
"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 |
| schedule_info | JSON Object | 可选 | 定时任务的相关信息（仅定时发送时返回） |
| |_ task_id | Integer | 必填 | 定时任务 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
}
}
此代码块在浮窗中显示
失败返回
http 状态码为 200（部分异常情况）或 4xx/5xx，响应体包含字段如下：
| 字段 | 类型 | 选项 | 描述 |
|---|---|---|---|
| plan_id | String | 必填 | 计划 ID |
| total_count | Integer | 必填 | 接收到的目标数量 |
| accepted_count | Integer | 必填 | 接收到的有效目标数量 |
| code | Integer | 必填 | 错误码，详见错误码说明 |
| message | String | 必填 | 错误详情 |
异常示例
{
"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 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 字段的错误描述 |
