发送相关
send
发送一个短信模板给一个或多个用户
URL
https://api.sendcloud.net/smsapi/send
返回数据格式
json
HTTP请求方式
POST
参数说明
参数 | 类型 | 必选 | 说明 |
---|---|---|---|
smsUser | string | 是 | smsUser |
templateId | int | 是 | 模板ID |
labelId | int | 否 | 短信标签ID |
msgType | int | 否 | 0表示短信, 1表示彩信,2表示国际短信,3表示国内语音,5表示影音 默认值为0 |
phone | string | 是 | 收信人手机号,多个手机号用逗号,分隔,每次调用最大支持2000,更多地址建议使用联系人列表功能 |
vars | string | 否 | 替换变量的json串 |
sendRequestId | string | 否 | 最大支持128字符,1小时内相同sendRequestId的多次请求只会处理第一次 |
signature | string | 是 | 数字签名, 合法性验证,详情见API 验证机制 |
timestamp | string | 否 | UNIX时间戳 |
tag | string | 否 | 值为json 格式字符串,最大字符长度为128,比如:{"key1": "value1", "key2": "value2"} |
vars格式示例:
{"name": "lucy"} or {"%money%": "100"}
注意
:
-
系统会用vars中的参数替换短信模板中的变量, 所有手机号收到替换后的同一个内容. 如果每个手机号传递变量内容不同时,需要多次调用接口. 参数 vars 可能含有特殊字符, 记得
urlencode
. -
vars 所传递的变量的值, 长度默认不能超过16个字符, 格式为字符串, 变量中不能含有 HTTP 链接(特殊需求请联系客服)
-
生成签名时, 参数不要使用
urlencode
. 在调用 api 时, 才需要对参数做urlencode
-
msgType为5,表示可发送同时包含文字、图片、音频、视频信息的视频短信,也叫影信,可达2MB大小,详情见视频短信
sendVoice
发送语音验证码
URL
https://api.sendcloud.net/smsapi/sendVoice
返回数据格式
json
HTTP请求方式
POST
参数说明
参数 | 类型 | 必选 | 说明 |
---|---|---|---|
smsUser | string | 是 | smsUser |
phone | string | 是 | 收信人手机号 |
code | string | 是 | 验证码 |
labelId | int | 否 | 短信标签ID |
sendRequestId | string | 否 | 最大支持128字符,1小时内相同sendRequestId的多次请求只会处理第一次 |
signature | string | 是 | 数字签名, 合法性验证 |
timestamp | string | 否 | UNIX时间戳 |
tag | string | 否 | 值为json 格式字符串,最大字符长度为128,比如:{"key1": "value1", "key2": "value2"} |
code格式示例:
{"code": "123456"}
注意
:
- 参数 code 格式为字符串,内容为4-6位长度的数字
- 此接口不支持国际短信
sendCode(不需要短信模板)
发送短信验证码
URL
https://api.sendcloud.net/smsapi/sendCode
返回数据格式
json
HTTP请求方式
POST
参数说明
参数 | 类型 | 必选 | 说明 |
---|---|---|---|
smsUser | string | 是 | smsUser |
msgType | int | 是 | 0表示短信,2表示国际短信,默认值为0 |
phone | string | 是 | 收信人手机号 |
signId | Integer | * | 短信签名id |
signName | string | * | 短信签名名称 |
code | string | 是 | 验证码 |
labelId | int | 否 | 短信标签ID |
sendRequestId | string | 否 | 最大支持128字符,1小时内相同sendRequestId的多次请求只会处理第一次 |
signature | string | 是 | 数字签名, 合法性验证 |
timestamp | string | 否 | UNIX时间戳 |
tag | string | 否 | 值为json 格式字符串,最大字符长度为128,比如:{"key1": "value1", "key2": "value2"} |
code格式示例:
{"code": "123456"}
注意
:
- 参数 code 格式为字符串,内容为4-6位长度的数字
- signId为短信签名的id,signId和signName两个参数只需要传一个即可,如果signId不为空,signName自动忽略
timestamp
获取服务器时间戳
URL
https://api.sendcloud.net/smsapi/timestamp/get
返回数据格式
json
HTTP请求方式
GET
参数说明
无
返回码
短信 API 返回的结果是 JSON 格式, 示例如下:
# 请求成功
{
"message":"请求成功",
"info":{"successCount":1,"smsIds":["1458113381893_15_3_11_1ainnq$131112345678"]}},
"result":true,
"statusCode":200
}
# 手机号格式错误
{
"message":"手机号格式错误",
"info":{},
"result":false,
"statusCode":412
}
# 部分成功
{
"message":"部分成功",
"info":{
"successCount":1,
"failedCount":1,
"items":[{"phone":"1312222","vars":{},"message":"手机号格式错误"}],
"smsIds":["1458113381893_15_3_11_1ainnq$131112345678"]}
},
"result":true,
"statusCode":311
}
- result: API 请求是否成功
- statusCode: API 返回码
- message: API 返回码的中文解释
- info: 更多信息, 比如: 部分成功则返回具体失败信息, 获取时间戳则返回时间戳的值
API 返回码 | 含义 |
---|---|
200 | 请求成功 |
311 | 部分号码请求成功 |
312 | 全部请求失败 |
400 | 重复请求 |
401 | 短信内容不能为空 |
402 | 短信内容不能超过%s个字符 |
403 | 此接口暂不支持此类 msgType |
411 | 手机号不能为空 |
412 | 手机号格式错误 |
413 | 有重复的手机号 |
414 | 有重复的手机号 |
415 | 手机号检测个数不能超过%s个,且不能为0个 |
416 | tag格式错误 |
417 | tag长度不能超过128个字符 |
421 | 数字签名参数错误 |
422 | 数字签名错误 |
431 | 模板不存在 |
432 | 模板未提交审核或者未审核通过 |
433 | 模版ID不能为空 |
434 | 模板类型不匹配 |
435 | 模板名称不能为空 |
436 | 模板名称不能超过64个字节 |
437 | 模板内容不能为空 |
438 | 模板内容不超过512个字节 |
439 | 彩信标题不超过50个字节 |
440 | 【】表示短信签名,模板内容或彩信标题不能包含 |
441 | 替换变量格式错误 |
451 | 定时发送时间的格式错误 |
452 | 定时发送时间早于服务器时间, 时间已过去 |
461 | 时间戳无效, 与服务器时间间隔大于6秒 |
471 | smsUser不存在 |
472 | smsUser不能为空 |
473 | 没有权限, 免费用户不能发送短信 |
474 | 用户不存在 |
481 | 手机号和替换变量不能为空 |
482 | 手机号和替换变量格式错误 |
483 | 替换变量长度不能超过16或32个字符 |
499 | 账户额度不够 |
501 | 服务器异常 |
601 | 你没有权限访问 说明:IP防护的拦截 |
602 | 您没有使用该接口的权限 说明:没有调用sendVoice的权限 |
7241 | phones列表成员号码最多不能超过100个 |
50000 | 接口频率受限(每个smsUser,每个接口、每分钟调用4000次,目前只限制投递回应) |
SMSHook 错误码(statusCode) | 含义 |
---|---|
410 | 处理失败, 手机号在全局拦截列表 |
420 | 处理失败, 手机号在局部拦截列表 |
430 | 处理失败, 取消订阅 |
440 | 处理失败, 关键词过滤 |
450 | 处理失败, 替换变量错误 |
460 | 处理失败, 短信内容不能超过500个字符 |
500 | 发送失败, 手机空号 |
510 | 发送失败, 手机停机 |
550 | 发送失败, 该模板内容被投诉 |
580 | 发送失败, 手机关机 |
590 | 发送失败, 其他原因 |