融云短信服务开发指南

概述

为满足应用中短信验证业务需求,融云与优质短信平台合作,提供具有全网覆盖能力的短信验证码发送验证功能接口,详细开通及使用说明如下:

短信功能使用流程

开发者在使用短信验证功能前,需前往 融云官方网站 注册创建融云开发者帐号。

image
使用流程

短信服务使用说明

认证企业开发者并购买短信

认证企业开发者

在融云开发者后台,选择需要开通短信功能的应用,进入应用详情页面,点击 短信服务 > 服务设置 进行企业认证,提交认证信息后,会在 5 个工作日内审核完成。

image
认证企业开发者

购买短信

认证成功后,需要充值购买短信才能使用短信服务,短信价格如下:

充值为 100 的整数倍 例如:100, 200, 1100, 1200…

  1. 充值金额 < 1000 元时,短信单价为 0.060 元/条
  2. 1000 ≤ 充值金额 < 5000 元时,短信单价为 0.055 元/条
  3. 充值金额 ≥ 5000 元时,短信单价为 0.050 元/条

短信签名

每条短信都必须带有签名,可以在开发者后台 短信服务 > 服务设置 中进行添加。

签名说明

  • 根据中国基础运营商的相关规定,每条短信的最后必须包含签名,如果没有签名,则短信肯定无法正常发送。
  • 签名格式为中文括号加公司简称或者店铺名称等:例如:【融云即时通讯云】,建议使用 3-7 个汉字。
  • 可以包含数字、汉字、英文,不能为纯数字、纯英文或数字+英文的组合,不能包含其他特殊符号。
  • 签名会自动附加,因此会占用短信的字数,请注意控制内容长度。
  • 受运营商限制,正常审核时间为 3 个工作日以内。

图片验证

开发者可选择开启或关闭图片验证功能,开启后可通过 获取图验接口 获取图验 URL 地址,在发送短信验证码时会对图验进行验证,验证通过才会下发短信验证码,否则不会下发短信验证码,防止短信骚扰。

短信模板

融云默认为提供用户注册密码找回修改密码身份验证等 4 个短信模板,如果用户有新的模板需求,可提交模板申请添加。

需要说明模板名称短信用途及内容短信内容中需要标出签名位置(只能在短信内容前面或最后)及验证码位置。

短信号码

短信号码说明

  1. 短信号码在每创建一个应用后,系统会自动分配一个短信端口号码。
  2. 因受政策限制,已分配的短信端口号码某些时候不可用。
  3. 暂不提供自定义短信号码。

Server API 短信服务

短信验证使用流程

App -> App Server: 请求获取短信验证码 App Server -> RongCloud Server: 请求发送短信验证码,如设置了图片验证码则需要提交图片验证信息 RongCloud Server --> App Server: 返回 sessionId (短信验证码唯一标识) RongCloud Server --> App: 发送短信验证码给目标手机号 App -> App Server: 请求验证短信验证码 App Server -> RongCloud Server: 通过 sessionId 和短信验证码进行验证 RongCloud Server --> App Server: 返回验证结果 App Server --> App: 通知用户验证结果

获取图片验证码 方法

开发者后台开通图片验证功能后,才能获取图片验证码,开启后在调用发送短信验证码接口时需要对图片验证码进行验证。

示例

HTTP 请求方式: GET

http://api.sms.ronghub.com/getImgCode.json?appKey=uwd1c0sxdlx2

表单参数

名称 类型 说明
appKey String 应用 AppKey。(必传)

返回值

名称 类型 说明
code int 返回码,200 为正常。
url String 返回的图片验证码 URL 地址。
verifyId String 返回图片验证标识 Id。

json格式:

{
  "code": 200,
  "url": "xxxxxxxxxxxxx",
  "verifyId": "xxxxxxxx"
}

发送短信验证码 方法

方法名:/sendCode

签名方法:请参考 通用 API 接口签名规则

URL:http://api.sms.ronghub.com/sendCode.json

HTTP 方法:POST

示例

HTTP 请求:

POST /sendCode.json HTTP/1.1
Host: api.sms.ronghub.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408706337
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/x-www-form-urlencoded

mobile=13500000000&verifyId=1408706337&verifyCode=890b422b&templateId=dsfdsfd&region=86

表单参数

名称 类型 说明
mobile String 接收短信验证码的目标手机号,每分钟同一手机号只能发送一次短信验证码。(必传)
verifyId String 图片验证标识 Id ,开启图片验证功能后此参数必传,否则可以不传。在获取图片验证码方法返回值中获取。
verifyCode String 图片验证码,开启图片验证功能后此参数必传,否则可以不传。
templateId String 短信模板 Id,在开发者后台->短信服务->服务设置->短信模版中获取。(必传)
region String 手机号码所属国家区号,目前只支持中国区号 86(必传)

返回值

名称 类型 说明
code int 返回码,200 为正常。
sessionId String 短信验证码唯一标识。

json格式:

{
 "code": 200,
 "sessionId": "xxxxxxx"
}
注:每分钟同一手机号只能发送一次短信验证码,短信验证码有效期为 15 分钟,短信验证成功后验证码失效。开通图片验证功能后,如果此条图片验证不成功则用户不会收到验证短信。

返回值请参考 API 方法返回值说明

验证码验证 方法

方法名:/verifyCode

签名方法:请参考 通用 API 接口签名规则

URL:http://api.sms.ronghub.com/verifyCode.json

HTTP 方法:POST

示例

HTTP 请求:

POST /verifyCode.json HTTP/1.1
Host: api.sms.ronghub.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408706337
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/x-www-form-urlencoded

sessionId=2312312&code=3122

表单参数

名称 类型 说明
sessionId String 短信验证码唯一标识,在发送短信验证码方法,返回值中获取。(必传)
code String 短信验证码内容。(必传)

返回值

名称 类型 说明
code int 返回码,200 为正常。
success Boolean true 验证成功,false 验证失败。

json格式:

{"code":200,"success":true}

返回值请参考 API 方法返回值说明

发送通知类短信 方法

方法名:/sendNotify

签名方法:请参考 通用 API 接口签名规则

URL:http://api.sms.ronghub.com/sendNotify.json

HTTP 方法:POST

示例

HTTP 请求:

POST /sendNotify.json HTTP/1.1
Host: api.sms.ronghub.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408706337
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/x-www-form-urlencoded

mobile=13500000000&templateId=dsfdsfd&region=86&p1=aa&p2=bb&p3=cc

表单参数

名称 类型 说明
mobile String 接收通知短信的目标手机号。(必传)
templateId String 短信模板 Id,在开发者后台->短信服务->服务设置->短信模版中获取。(必传)
region String 手机号码所属国家区号,目前只支持中国区号 86(必传)
p1 String 短信模板中,自定义变量值,如果在通知短信模板中定义了 {p1} 则在发送通知短信时必须传入此参数,替换模板中的 {p1},否则此参数可以不传。
p2 String 短信模板中,自定义变量值,如果在通知短信模板中定义了 {p2} 则在发送通知短信时必须传入此参数,替换模板中的 {p2},否则此参数可以不传。
p3 String 短信模板中,自定义变量值,如果在通知短信模板中定义了 {p3} 则在发送通知短信时必须传入此参数,替换模板中的 {p3},否则此参数可以不传。
注:发送的通知短信内容不能超过 210 个字节。

返回值

名称 类型 说明
code int 返回码,200 为正常。
sessionId String 短信唯一标识。

json格式:

 {
  "code": 200,
  "sessionId": "xxxxxxx"
 }

返回值请参考 API 方法返回值说明

API 方法返回值说明

code 描述 HTTP 状态码
1009 没有开启图验功能 400
1010 未使用已开启的图验功能 400
1000 内部逻辑错误 500
1003 参数错误 400
1005 参数长度超出限制 400
1008 调用超过频率上限 429
1002 缺少参数 400
1004 验证签名错误 401
1050 内部服务响应超时 504
1012 图片验证码不正确 430
1011 剩余条数不足,需要充值 430
1013 短信通道不可用 430
1014 短信验证码已验证过,再次验证失效 430
1015 短信验证码过期无效 430

© 2016 RongCloud. All Rights Reserved. Version 2.8.5