您的位置:首页 >  接口中心 > 短信接口说明
  短信接口说明
 

1 协议说明


名称说明
协议HTTP POST
编码格式UTF8
Content-Typeapplication/json
URLhttp://xxx/msg/send/json 或者 https://xxx/msg/send/json
       完整地址请登录云通讯自助通平台或者询问您的商务负责人获取
接口说明此接口一次可提交不超过50000个手机号码。


2 请求包体

包体为json字符串,参数如下:


{
         "account" : "N6000001", //用户在云通讯平台上申请的API账号
         "password" : "123456", //用户在云通讯平台上申请的API账号对应的API密钥
         "msg" : "【云通讯】您的验证码是:2530", //短信内容。长度不能超过536个字符
         "phone" : "15812345678", //手机号码。多个手机号码使用英文逗号分隔
         "sendtime" : "201704101400", //定时发送短信时间。格式为yyyyMMddHHmm,值小于或等于当前时间则立即发送,不填则默认为立即发送(选填参数)
         "report" : "true", //是否需要状态报告(默认为false)(选填参数)
         "extend" : "555", //用户自定义扩展码,纯数字,建议1-3位(选填参数)
         "uid" : "批次编号-场景名(英文或者拼音)" //自助通系统内使用UID判断短信使用的场景类型,可重复使用,可自定义场景名称,示例如 VerificationCode(选填参数)
     }


注:

  1. 客户发送短信的账号不是云通讯平台登录账号,是短信接口API账号 。

  2. 发送的短信内容一定要加上签名,账号有报备过签名的可不用带上签名, 但如果您有多个短信签名,请将需要的短信签名放在短信内容前面 。
         例如您有”【云通讯】”,”【通讯云】”两个签名,但是想以”【通讯云】”签名发送短信,则”msg”字段可赋值为:”【通讯云】你的验证码是xxxx”,不填默认第一个签名。

  3. 用户自定义扩展码,发送短信显示号码,规则为:10690+xxx(通道号)+xxx(系统扩展码) +xxx(用户自定义扩展码);扩展码的长度将直接影响短信上行接收的接收。如需要传扩展码参数时,请咨询客服相关设置问题 。


3 应答包体

{
     "code" : "0", //状态码
     "msgId" : "17041010383624511", //消息Id
     "errorMsg" : "", //失败状态码说明(成功返回空)
     "time" : "20170410103836" //响应时间
 }

注:code为响应状态码,可以和“响应状态码”进入对比


1 协议说明


名称说明
协议HTTP POST
编码格式UTF8
Content-Typeapplication/json
URLhttp://xxx/msg/variable/json 或者 https://xxx/msg/variable/json
       完整地址请登录云通讯自助通平台或者询问您的商务负责人获取
接口说明msg字段最多支持20个变量。params字段最多不超过1000个参数组。
       格式不符的参数,系统自动会过滤。

msg字段最多支持20个变量。params字段最多不超过1000个参数组。
       格式不符的参数,系统自动会过滤


2 请求包体

包体为json字符串,参数如下:


{
         "account" : "N6000001", //用户在云通讯平台上申请的API账号
         "password" : "123456", //用户在云通讯平台上申请的API账号对应的API密钥
         "msg" : "【云通讯】您的验证码是:2530", //短信内容。长度不能超过536个字符
         "phone" : "15812345678", //手机号码。多个手机号码使用英文逗号分隔
         "sendtime" : "201704101400", //定时发送短信时间。格式为yyyyMMddHHmm,值小于或等于当前时间则立即发送,不填则默认为立即发送(选填参数)
         "report" : "true", //是否需要状态报告(默认为false)(选填参数)
         "extend" : "555", //用户自定义扩展码,纯数字,建议1-3位(选填参数)
         "uid" : "批次编号-场景名(英文或者拼音)" //自助通系统内使用UID判断短信使用的场景类型,可重复使用,可自定义场景名称,示例如 VerificationCode(选填参数)
     }


注:

  1. 客户发送短信的账号不是云通讯平台登录账号,是短信接口API账号 。

  2. 发送的短信内容一定要加上签名,账号有报备过签名的可不用带上签名, 如果您有多个短信签名,请将需要的短信签名放在短信内容前面 。
         例如您有“【云通讯】”,“【通讯云】”两个签名,但是想以“【通讯云】”签名发送短信,则“msg”字段可赋值为:“【通讯云】尊敬的{$var},你好,您的密码是:{$var},{$var}分钟内有效”

  3. 用户自定义扩展码,发送短信显示号码,规则为:10690+xxx(通道号)+xxx(系统扩展码) +xxx(用户自定义扩展码);扩展码的长度将直接影响短信上行的接收。如需要传扩展码参数时,请咨询客服相关设置问题 。

  4. 变量短信第一个变量默认为手机号码,后面的变量依次匹配短信内容中{$var}所代表的变量,且变量符只能为{$var},变量之间英文逗号隔开,变量参数组之间用英文分号隔开 。

3 应答包体

{
    "code":"0", //状态码
    "msgId":"17041010383624511", //消息Id
    "errorMsg":"", //失败状态码说明(成功返回空)
    "failNum":"0", //失败条数
    "successNum":"1" //成功条数
}


注:code为响应状态码,可参照“状态码”对比

1 协议说明


名称说明
推送协议HTTP GET
接口说明短信发送以后,云通讯短信服务可以通过回调业务url的方式,通知客户短信下发的状态报告


注:
 如果用户需要回送短信的状态报告,需要设置(云通讯PaaS平台用户自行设置或联系客服人员设置)用户账号为需要回送状态报告,并且配置状态报告的回送地址。
 回送地址服务器需要启动一个http服务用于接收状态报告。

2 推送示例

http://client_url?receiver=admin&pswd=12345&msgid=17041010383624511&reportTime=1704101038&mobile=15700000004&notifyTime=170410103838&uid=17041010383624511&status=DELIVRD&statusDesc=短信发送成功


推送字段说明:
{
client_url://用户服务器地址
receiver://接收验证的用户名(不是账户名),是按照用户要求配置的名称,可以为空
pswd://接收验证的密码,可以为空
msgid://消息id
reportTime://运营商返回的状态更新时间,格式yyMMddHHmm,其中yy=年份的最后两位(00-99)
mobile://接收短信的手机号码
notifyTime://云通讯平台收到运营商回复状态报告的时间,格式yyMMddHHmmss
uid://用户在提交短信时传入的uid参数,状态报告会原样返回此参数,未提交则无该参数
status://状态码
statusDesc://状态说明,内容UTF-8编码

}


注释:

  • 推送到客户配置地址后,用户自行根据业务需求写方法接收参数

  • status值可以参考“状态码”对比


1 协议说明

名称说明
推送协议HTTP GET
接口说明短信下发完毕,用户收到短信后,回复短信,云通讯服务可以通过回调业务url的方式,通知业务方用户回复了短信


注:
 如果用户需要回送上行短信,需要设置(云通讯PaaS平台用户自行设置或联系客服人员设置)用户账号为需要回送上行短信,并且配置上行短信的回送地址。
 回送地址服务器需要启动一个http服务用于接收上行短信。

2 推送示例

http://client_url?receiver=admin&pswd=12345&moTime=1704142009&mobile=15200000005&msg=短信已经收到&destcode=106905841963717198&spCode=1069058419637171&notifyTime=170414200957

推送字段说明:client_url://用户服务器地址
receiver://接收验证的用户名(不是账户名),是按照用户要求配置的名称,可以为空
pswd://接收验证的密码,可以为空
moTime://上行时间,格式yyMMddHHmm,其中yy=年份的最后两位(00-99)
mobile://上行手机号码
msg://上行内容,内容经过URLEncode编码(UTF-8)
destcode://运营商通道码
spCode://系统通道码
notifyTime://云通讯平台收到运营商回复上行短信的时间,格式yyMMddHHmmss
isems://是否为长短信的一部分,1:是,0,不是。不带该参数,默认为普通短信
emshead://isems为1时,本参数以ASCII码形式显示长短信的头信息。用“,”隔开,分为三个部分,第一部分标识该条长短信 的ID(该ID为短信中心生成);第二部分,表明该长短信的总条数(pk_total);第三部分,该条短信为该长短信的第几条(pk_number)。例如:234,4,1,该短信的ID为234,该长短信的总长度为4条,1,当前为第一条。


注释:

  • 推送到客户配置地址后,用户自行根据业务需求写方法接收参数


1 协议说明

名称说明
协议HTTP POST
编码格式UTF8
Content-Typeapplication/json
URLhttp://xxx/msg/balance/json 或者 https://xxx/msg/balance/json 
       完整地址请登录云通讯平台或者询问您的商务负责人获取
接口说明查询当前账号可用余额

2 请求包体


{
     "account" : "N6000001", //用户在云通讯平台上申请的API账号
     "password" : "123456" //用户在云通讯平台上申请的API账号对应的API密钥
 }



注:

  1. 客户发送的账号不是云通讯平台登录账号,是短信接口API账号

3 应答包体


{
     "code" : 0, //状态码
     "balance" : "2530", //剩余可用余额条数
     "errorMsg" : "", //状态码说明(成功返回空)
     "time" : "20170410103836" //响应时间
 }



注:code为响应状态码,可参照“状态码”对比



1 协议说明

名称说明
协议HTTP POST
编码格式UTF8
Content-Typeapplication/json
URLhttp://xxx/msg/pull/report 或者 https://xxx/msg/pull/report 
       完整地址请登录云通讯平台或者询问您的商务负责人获取
接口说明短信下发成功,可调用此接口拉取短信状态报告。
       拉取过的内容不会再重复返回,可以理解为消息队列机制,请用户及时存储。
       此功能需注意账号需要开启主动拉取功能。


2 请求包体


{
     "account" : "N6000001", //用户在云通讯平台上申请的API账号
     "password" : "123456", //用户在云通讯平台上申请的API账号对应的API密钥
     "count" : "20" //拉取个数(最大100,默认20),选填
 }



3 应答包体


{
    "ret":0, //请求状态。0成功,其他状态为失败
    "result":[ //状态明细结果,没结果则返回空数组
        {
            "uid":"17042615580828306",//用户在提交短信时传入的uid参数,状态报告会原样返回此参数,未提交则无该参数
            "reportTime":"1704261558",//状态更新时间,格式yyMMddHHmm,其中yy=年份的最后两位
            "notifyTime":"170426155812",//云通讯平台收到运营商回复状态报告的时间,格式yyMMddHHmmss
            "status":"DELIVRD", //状态码
            "msgId":"17042615580828306", //消息Id
            "statusDesc":"短信发送成功", //状态说明
            "mobile":"18700000002" //接收短信的手机号码
        },
        {
            "uid":"17042615581328557",
            "reportTime":"1704261558",
            "notifyTime":"170426155837",
            "status":"DELIVRD",
            "msgId":"17042615581328557",
            "statusDesc":"短信发送成功",
            "mobile":"18700000002"
        }
    ]
}



应答包体业务错误时,返回示例如下


{
     "ret" : "1", //请求状态失败
     "error" : "账号或密码不能为空" //失败描述
 }


注:

  • 客户发送短信时report设置为true方可拉取到状态报告,否则为空数组

  • status值可以参考“状态码”对比

1 协议说明

名称说明
协议HTTP POST
编码格式UTF8
Content-Typeapplication/json
URLhttp://xxx/msg/pull/mo 或者 https://xxx/msg/pull/mo 
       完整地址请登录云通讯平台或者询问您的商务负责人获取
接口说明短信下发成功,用户收到短信后,回复短信后,可调用此接口拉取短信上行。
       拉取过的内容不会再重复返回,可以理解为消息队列机制,请用户及时存储。
       此功能需注意账号开启主动拉取功能。


2 请求包体


{
     "account" : "N6000001", //用户在云通讯平台上申请的API账号
     "password" : "123456", //用户在云通讯平台上申请的API账号对应的API密钥
     "count" : "20"  //拉取个数(最大100,默认20),选填
 }



3 应答包体

{
    "ret":0, //请求状态。0成功,其他状态为失败
    "result":[ //状态明细结果,没结果则返回空数组
        {
            "spCode":"1069014578708615", //系统通道码
            "moTime":"1704261604", //上行时间,格式yyMMddHHmm
            "messageContent":"好的", //上行内容
            "destCode":"1069128478708615", //运营商通道码
            "mobile":"18700000002" //上行手机号码
        },
        {
            "spCode":"1069014578708615",
            "moTime":"1704261604",
            "messageContent":"收到了",
            "destCode":"1069128478708615",
            "mobile":"18700000002"
        }
    ]
}


应答包体业务错误时,返回示例如下


{
     "ret" : "1", //请求状态失败
     "error" : "账号或密码不能为空" //失败描述
 }


    状态码描述
    0提交成功
    101无此用户
    102密码错误
    103提交过快(提交速度超过流速限制)
    104系统忙(因平台侧原因,暂时无法处理提交的短信)
    105敏感短信(短信内容包含敏感词)
    106消息长度错(>536或<=0)
    107包含错误的手机号码
    108手机号码个数错(群发>50000或<=0)
    109无发送额度(该用户可用短信数已使用完)
    110不在发送时间内
    113扩展码格式错(非数字或者长度不对)
    114可用参数组个数错误(小于最小设定值或者大于1000);变量参数组大于20个
    116签名不合法或未带签名(用户必须带签名的前提下)
    117IP地址认证错,请求调用的IP地址不是系统登记的IP地址
    118用户没有相应的发送权限(账号被禁止发送)
    119用户已过期
    120违反防盗用策略(日发送限制)
    123
    发送类型错误
    124白模板匹配错误
    125匹配驳回模板,提交失败
    127定时发送时间格式错误
    128内容编码失败
    129
    JSON格式错误
    130请求参数错误(缺少必填参数)


    状态码
    描述
    DELIVRD
    短信发送成功
    UNKNOWN
    未知短信状态
    REJECTD
    短信被短信中心拒绝
    MBBLACK
    目的号码是黑名单号码
    REJECT
    审核驳回
    其他网关内部状态