开发指南:短信验证码/通知

来自落地电话、呼叫中心等语音和IVR、短信的SDK文档—云通讯平台
跳转到: 导航, 搜索

注意:云通讯平台通过模板短信的方式提供短信验证码订单通知的短信下发,其它类型的短信不提供支持。        

短信验证码是通过短信网关将含有验证码字符串或通知内容的短信发送到用户手机上,常用在网站注册及重要资料修改、密码变更等环节用来验证用户身份及手机号码的有效性。

订单通知是指通过短信网关将用户的订单情况发送到用户手机上,一般用于电子商务或物流等有网上交易和货物送达之类的公司。

注意

默认以70个汉字(同70个英文)为一条(以下发内容长度为准),超过长度平台将会自动分割为多条(每条长度为67个字分割)发送,分割后的多条短信将按照具体占用条数计费。

SMS PHP DEMO下载                     SMS JAVA DEMO下载

安全审核说明

为避免企业开发者账户被恶意盗刷、终端用户遭到短信轰炸等骚扰,配合运营商的规定,针对涉及验证码相关模板配置的用户,我平台将对相关网站的注册环节进行安全机制核查:

1、在提交短信模板时,请根据您的产品类型进行选择(网站或App),微信公众平台按照App提交

  (1)如果注册渠道全部为通过APP完成,不涉及其他渠道:

     a.若App已经上线运营,请提供下载地址(可以成功下载即可,包含但不限于官网、安卓市场、App Store);

     b.若App仍未上线,请提供能够体现App名称的App主界面截图一张(匹配需要配置的短信模板签名)、需要使用验证短信的相关界面截图一张;

     c.若以上两个界面均无法体现App名称,请提供"关于"页面截图;

     d.微信公众平台请提交公众平台账号(匹配模板签名)信息页截图一张、关注公众号后的截图一张,查看示例

  (2)如果注册渠道涉及通过网页完成,须在注册环节添加图形验证码作为安全机制:

      a.若网站已经上线,请提供需要使用验证短信的URL(须匹配短信模板签名;

     b.若网站仍未上线,暂时不支持配置,请谅解;

3、短信模板配置后,请不要擅自调整甚至删除图形验证码,如擅自调整或删除图形验证码,云通讯平台有权随时将相关短信模板下线,如因调整安全机制造成的终端用户手机被骚扰、用户投诉等问题,须由被投诉企业负责联系投诉用户,并办理撤诉,在撤诉完成前,被投诉企业在云通讯平台的账户将被冻结;

4、出现3中的情况,被投诉企业须承担云通讯平台在投诉期间发生的一切损失(包括但不限于经济损失),且云通讯保留对被投诉企业追究法律责任的权利;

5、最终解释权归云通讯平台所有。

文档阅读说明:

1.入 门 必  读: 介绍模板短信的相关规则和注意事项【必读】
2.开 发 必  读: 介绍模板短信的开发流程【如果您想使用demo,可以略过此节,直接看第3章】
3.Demo示 例 : 结合云通讯提供的demo,提供模板短信的示例代码
4.常见错误码模板短信开发常见的错误码
5.常  见 问  题:模板短信使用过程的常见问题解答,避免这些常见问题,短信就可畅通无阻的下发。

支持语言

所有开发语言

一 入门必读

1 模板短信前置条件

      1.客户注册后,需提交企业级的认证,个人认证客户不允许使用模板短信。

      2.客户需累计充值500元以上才可以使用短信模板,否则不能使用短信模板,即用户第一次充值则至少充值500元,如果以前曾经充过值,则累计需要达到500元,不足500元,要使用模板短信必须充值不足到500元。

2 模板短信规则

  1. 现在云通讯平台仅支持模板短信,不支持非模板短信接口。
  2. 短信模板是需要审核人员和运营商方面进行审核的,审核工作每个工作日进行一次(9:00),只有审核通过的短信模板才可以被调用。
  3. 云通讯提供的测试模板仅供“控制台--号码管理”里面的3个测试号码发送,测试阶段需要绑定。
  4. 针对验证码类(模板类型是验证码类的,包含但不限于验证码关键字),同一模板同一号码每天发送次限制5条短信。如果多个模板,该限制按照模板数量叠加,但最多每个号码每天可以发送8条。
  5. 针对验证码类(模板类型是验证码类的,包含但不限于验证码关键字),同一模板同一号码发送时间间隔30秒。
  6. 针对通知类(模板内容是通知类的短信),同一模板同一号码每天发送次限制20条短信。

3.免费开发测试

   为了让用户在充值之前就能对模板短信进行体验,我们让客户免费开发测试,您觉得可以了,再正式充值使用模板短信。

 【免费开发测试也需要先注册成为平台用户,但不需要先做认证和充值】

  测试步骤和注意事项:

     1.下载测试程序 http://www.yuntongxun.com/activity/smsDemo#tiyan

     2.进入管理控制台创建应用

     3.用平台账户、应用信息代替demo中的对应信息

     a.测试号码为注册手机号或者在"控制台—应用—号码管理—测试号码"中设置

     b.使用的测试模板为:【云通讯】您使用的是云通讯短信模板,您的验证码是{1},请于{2}分钟内正确输入,模板ID为1

     c.若测试满意上线,只需用审核通过的模板ID替换官方测试模板ID(1)即可

4 正式上线准备工作

   1.注册成为云通讯用户

       在云通讯网站首页按照引导注册即可。

   2.提交企业认证

    进入控制台-账号-账号管理-认证信息,如图

%E8%AE%A4%E8%AF%81.jpg
信息按照页面提示填写即可,注意一定要以公司身份认证。

   3.充值

     进入在控制台-财务-充值,如图

800px-%E5%85%85%E5%80%BC1.jpg
   

   4.创建短信模板

      短信模板示例:

     云通讯提供的测试模板如下,其中 " {序号} " 为需要接口替换的变量,只允许使用数字变量,序号从1开始;"【云通讯】" 为每条模板短信必须带的短信签名,签名须前置。

    在自建的短信模板中请根据具体业务自定义替换"【】"中内容。

【云通讯】您使用的是云通讯短信模板,您的验证码是{1},请于{2}分钟内正确输入

    例如:程序内指定 {1} = 88888;{2} = 10

    则收到短信如下内容

【云通讯】您使用的是云通讯短信模板,您的验证码是88888,请于10分钟内正确输入

     创建短信模板过程如下:

     首先,在控制台创建您自己的应用,如下图。

%E5%88%9B%E5%BB%BA%E5%BA%94%E7%94%A8.jpg

      其次,在控制台的应用列表中选择自己创建的应用,点上线

%E5%BA%94%E7%94%A8%E4%B8%8A%E7%BA%BF.jpg

     然后,在控制台的短信模板中创建短信模板,短信模板示例:

%E6%96%B0%E5%A2%9E%E6%A8%A1%E6%9D%BF.jpg

     点击新增,出现如下窗口,根据模板短信使用环境分为三种方式提交:

     1、已发布的APP:

%E5%B7%B2%E5%8F%91%E5%B8%83app.jpg
    

     2、未发布的APP:

%E6%9C%AA%E5%AE%A1%E6%A0%B8app.jpg
    

     3、网站/网页:

Web.jpg
    

   点击确定后,将在短信模板页的列表中看见自己创建的短信模板名字,当前状态为审核中,审核通过后,就可以使用了。

   

二、开发必读

1 模板短信接口请求方式

1.1 业务流程说明
TemplateSMSFLOW.jpg

1.2 Base URL 

模板短信API引用的地址有Base URL。

    Base URL:https://app.cloopen.com:8883

   注意:为了确保数据隐私,云通讯平台的REST API是通过HTTPS方式请求。

1.3 统一请求包头 

URL格式:/2013-12-26/Accounts/{accountSid}/SMS/TemplateSMS?sig={SigParameter}

在URL格式中 {}内的内容表示为参数,非{}的内容固定不变。

属性说明:

属性 类型 约束 说明
accountSid
String 必选
开发者主账户ACCOUNT SID。(登陆官网在管理控制台获取)
SigParameter
String 必选
REST API 验证参数,生成规则如下:
1.使用MD5加密(账户Id + 账户授权令牌 + 时间戳)。其中账户Id和账户授权令牌根据url的验证级别对应主账户。时间戳是当前系统时间,格式"yyyyMMddHHmmss"。时间戳有效时间为24小时,如:20140416142030
2.SigParameter参数需要大写,如不能写成sig=abcdefg而应该写成sig=ABCDEFG

1.4 HTTP标准包头字段

Accept:application/xml;
Content-Type:application/xml;charset=utf-8;
Content-Length:256; 
Authorization:

属性说明:

属性 类型 约束 说明
Accept
String 必选 客户端响应接收数据格式:application/xml、application/json
Content-Type
String 必选 类型:application/xml;charset=utf-8、application/json;charset=utf-8
Content-Length
String 必选 Content-Length
Authorization String 必选 验证信息,生成规则详见下方说明
1.使用Base64编码(账户Id + 冒号 + 时间戳)其中账户Id根据url的验证级别对应主账户
2.冒号为英文冒号
3.时间戳是当前系统时间,格式"yyyyMMddHHmmss",需与SigParameter中时间戳相同。

1.5 请求包体

属性
类型 约束 说明
to String 必选 短信接收端手机号码
appId
String 必选 应用Id
templateId String 必选 模板Id 
datas String 必选 内容数据外层节点
data
String
可选
内容数据,用于替换模板中{序号}
     1.5.1 XML请求示例

POST /2013-12-26/Accounts/abcdefghijklmnopqrstuvwxyz012345/SMS/TemplateSMS?sig=C1F20E7A9733CE94F680C70A1DBABCDE HTTP/1.1

Host:192.168.0.1:8883
content-length: 139
Accept:application/xml; 
Content-Type:application/xml;charset=utf-8; 
Authorization:ZmY4MDgwODEzYzM3ZGE1MzAxM2M4MDRmODA3MjAwN2M6MjAxMzAyMDExNTABCDE=
<?xml version='1.0' encoding='utf-8'?> 
<TemplateSMS>
  <to>13912345678</to>
  <appId>ff8080813c37da53013c3054f567007e</appId> 
  <templateId>1</templateId>
  <datas>
    <data>替换内容</data>
    <data>替换内容</data>
  </datas>
</TemplateSMS>

    1.5.2 JSON请求示例

POST /2013-12-26/Accounts/abcdefghijklmnopqrstuvwxyz012345/SMS/TemplateSMS?sig=C1F20E7A9733CE94F680C70A1DBABCDE HTTP/1.1

Host:192.168.0.1:8883
content-length: 139
Accept:application/json; 
Content-Type:application/json;charset=utf-8; 
Authorization:ZmY4MDgwODEzYzM3ZGE1MzAxM2M4MDRmODA3MjAwN2M6MjAxMzAyMDExNTABCDE=
 {"to":"13911281234","appId":"ff8080813fc70a7b013fc72312324213","templateId":"1","datas":["替换内容","替换内容"]}

1.6 响应

  此步响应只表明客户的短信请求发送成功,不表明短信通道已经发送短信成功。

属性 类型 约束 说明
statusCode String 必选 请求状态码,取值000000(成功)
smsMessageSid
String 必选 短信唯一标识符
dateCreated
String 必选 短信的创建时间,格式:yyyyMMddHHmmss
    1.6.1 XML响应示例
HTTP/1.1 200 OK 
Content-Length: 641 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <statusCode>000000</statusCode>
  <TemplateSMS>
    <smsMessageSid>ff8080813c373cab013c94b0f0512345</smsMessageSid>
    <dateCreated>20130201155306</dateCreated>
  </TemplateSMS>
</Response>
    1.6.2 json响应示例
HTTP/1.1 200 OK 
Content-Length: 641
{"statusCode":"000000","TemplateSMS":{"dateCreated":"20130201155306",
"smsMessageSid":" ff8080813c373cab013c94b0f0512345"}}

1.7 判断请求状态,重发


对响应解析后,statusCode为“000000”表示请求发送成功。statusCode不是“000000”,表示请求发送失败,客户服务端可以根据自己的逻辑进行重发或者其他处理。

三、Demo示例

我们在网站上提供各种开发语言的Demo下载,用户要参考模板短信功能如何实现,可以在“REST Server Demo”部分根据自己的开发语言下载相应的Demo例子。

1 PHP Demo中模板短信的使用说明

1.1 目录介绍

Php_demo_TempSMS.jpg

1.2发送模板短信接口介绍

1.接口声明文件:SDK\CCPRestSDK.php

2.接口函数定义:function sendTemplateSMS($to,$datas,$tempId)

3.参数说明:

$to :短信接收手机号码集合,用英文逗号分开,如 “13810001000,13810011001”,最多一次发送100个。
$datas: 内容数据,需定义成数组方式,如模板中有两个参数,定义方式为array(‘3456’,’123’)。
$tempId: 模板Id,如使用测试模板,模板id为1,如使用自己创建的模板,则使用自己创建的短信模板id即可。

4.接口调用示例:

include_once("../SDK/CCPRestSDK.php");
说明:需要包含接口声明文件,可将该文件拷贝到自己的程序组织目录下。

$accountSid= 
说明:主账号,登陆云通讯网站后,可在“控制台-应用”中看到开发者主账号ACCOUNT SID。

$accountToken= 
说明:主账号Token,登陆云通讯网站后,可在控制台-应用中看到开发者主账号AUTH TOKEN。

$appId=
说明:应用Id,请使用自己创建应用的APPID。

$serverIP='app.cloopen.com'; 
说明:请求地址。

$serverPort='8883'; 
说明:请求端口 

$softVersion='2013-12-26'; 
说明:REST API版本号保持不变。

 function sendTemplateSMS($to,$datas,$tempId)

{
     // 初始化REST SDK
     global $accountSid,$accountToken,$appId,$serverIP,$serverPort,$softVersion; 
     $rest = new REST($serverIP,$serverPort,$softVersion); 
     $rest->setAccount($accountSid,$accountToken); 
     $rest->setAppId($appId); 
    

     // 发送模板短信
     echo "Sending TemplateSMS to $to <br/>";
     $result = $rest->sendTemplateSMS($to,$datas,$tempId); 
     if($result == NULL ) {
         echo "result error!"; 
         break; 
     }
     if($result->statusCode!=0) {
         echo "模板短信发送失败!<br/>";
         echo "error code :" . $result->statusCode . "<br>";
         echo "error msg :" . $result->statusMsg . "<br>";
         //下面可以自己添加错误处理逻辑
     }else{
         echo "模板短信发送成功!<br/>";
         // 获取返回信息
         $smsmessage = $result->TemplateSMS; 
         echo "dateCreated:".$smsmessage->dateCreated."<br/>";
         echo "smsMessageSid:".$smsmessage->smsMessageSid."<br/>";
         //下面可以自己添加成功处理逻辑
     }
}
可参考demo中的接口调用文件:Demo\SendTemplateSMS.php。

2 Java Demo中模板短信的使用说明

2.1 目录介绍

Java_demo_TempSMS.jpg

2.2 发送模板短信接口介绍

1.接口声明文件:sdk\src\com\cloopen\rest\sdk\CCPRestSDK.java

2.接口函数定义:public HashMap<String, Object> sendTemplateSMS(String to, String templateId, String[] datas)

3.参数说明:

to: 字符串类型,短信接收手机号码集合,用英文逗号分开,如 “13810001000,13810011001”,最多一次发送100个。
templateId: 字符串类型,模板Id,如使用测试模板,模板id为“1”,如使用自己创建的模板,则使用自己创建的短信模板id即可。
datas:字符串数组类型,内容数据,需定义成数组方式,如模板中有两个参数,定义方式为String{“3456”,“测试”}。

说明:CCPRestSDK.java依赖Jar包:package com.cloopen.rest.sdk,在LIB目录下

4.接口调用示例:

import com.cloopen.rest.sdk.CCPRestSDK; 
import com.cloopen.rest.sdk.CCPRestSDK.BodyType; 
public class SDKTestSendTemplateSMS {
public static void main(String[] args) {
HashMap<String, Object> result = null; 
CCPRestSDK restAPI = new CCPRestSDK();
restAPI.init("app.cloopen.com", "8883");// 初始化服务器地址和端口

restAPI.setAccount("accountSid", "accountToken");// 初始化主账号名称和主账号令牌,登陆云通讯网站后,可在“控制台-应用”中看到开发者主账号ACCOUNT SID和主账号令牌AUTH TOKEN。
restAPI.setAppId("AppId");// 初始化应用ID,请使用自己创建应用的APPID。
result = restAPI.sendTemplateSMS("号码1,号码2等","模板Id" ,new String[]{"模板内容1","模板内容2"});
System.out.println("SDKTestGetSubAccounts result=" + result); 
if("000000".equals(result.get("statusCode"))){
//正常返回输出data包体信息(map)
HashMap<String,Object> data = (HashMap<String, Object>) result.get("data");
Set<String> keySet = data.keySet();
for(String key:keySet){ 
Object object = data.get(key); 
System.out.println(key +" = "+object); 
}
}else{
//异常返回输出错误码和错误信息
System.out.println("错误码=" + result.get("statusCode") +" 错误信息= "+result.get("statusMsg"));
}
}
}
可参考demo中的接口调用文件:
demo\src\com\cloopen\rest\demoSDKTestSendTemplateSMS.Java。

3 Python Demo中模板短信的使用说明

3.1 目录介绍

Python_demo_TempSMS.jpg

3.2 发送模板短信接口介绍

1.接口声明文件:SDK \CCPRestSDK.py
2.接口函数定义:def sendTemplateSMS(self, to,datas,tempId) 
3.参数说明:
  to: 短信接收手机号码集合,用英文逗号分开,如 “13810001000,13810011001”,最多一次发送100个。

  datas:内容数据,需定义成数组方式,如模板中有两个参数,定义方式为array['Marry','Alon']。

  templateId: 模板Id,如使用测试模板,模板id为“1”,如使用自己创建的模板,则使用自己创建的短信模板id即可。

4.接口调用示例:

  1. 编码说明:coding=utf-8或gbk

from CCPRestSDK import REST
import ConfigParser

accountSid= '您的主账号'; 
#说明:主账号,登陆云通讯网站后,可在“控制台-应用”中看到开发者主账号ACCOUNT SID。

accountToken= '您的主账号Token'; 
#说明:主账号Token,登陆云通讯网站后,可在控制台-应用中看到开发者主账号AUTH TOKEN。

appId='您的应用ID'; 
#说明:请使用自己创建应用的APPID.

serverIP='https://app.cloopen.com';
#说明:请求地址。

serverPort='8883'; 
#说明:请求端口,

softVersion='2013-12-26'; #说明:REST API版本号保持不变。 

def sendTemplateSMS(to,datas,tempId): 
    #初始化REST SDK
    rest = REST(serverIP,serverPort,softVersion) 
    rest.setAccount(accountSid,accountToken) 
    rest.setAppId(appId)

    result = rest.sendTemplateSMS(to,datas,tempId) 
    for k,v in result.iteritems():
        if k=='templateSMS' : 
                for k,s in v.iteritems():
                    print '%s:%s' % (k, s) 
        else: 
            print '%s:%s' % (k, v) 
可参考demo中的接口调用文件:SendTemplateSMS.py。

4 C# Demo中模板短信的使用说明

4.1 目录介绍

CSharp_demo_TempSMS.jpg

4.2 发送模板短信接口介绍

1.接口声明文件:CCPRestSDK.cs

2.接口函数定义: public Dictionary<string, object> SendTemplateSMS(string to, string templateId, string[] data)

3.参数说明:

to: 短信接收手机号码集合,用英文逗号分开,如 “13810001000,13810011001”,最多一次发送100个。

templateId: 模板Id,如使用测试模板,模板id为”1”,如使用自己创建的模板,则使用自己创建的短信模板id即可。

datas:内容数据,需定义成数组方式,如模板中有两个参数,定义方式为{“1234”,”10”}。

4.接口调用示例:

using System; 
using System.Collections.Generic; 
using System.Linq; 
using System.Web; 
using System.Web.UI; 
using System.Web.UI.WebControls; 

namespace SendTemplateSMS
{
    public partial class _Default : Page
    {
        protected void Page_Load(object sender, EventArgs e) 
        {
            string ret = null; 
            CCPRestSDK.CCPRestSDK api = new CCPRestSDK.CCPRestSDK();

            bool isInit = api.init("app.cloopen.com", "8883");
            api.setAccount(主账号, 主账号令牌); 
            api.setAppId(应用ID); 

            try
            {
                if (isInit) 
                {
                    Dictionary<string, object> retData = api.SendTemplateSMS(短信接收号码, 短信模板id, 内容数据); 
                    ret = getDictionaryData(retData); 
                }
                else
                {
                    ret = "初始化失败";
                }
            }
            catch (Exception exc) 
            {
                ret = exc.Message; 
            }
            finally
            {
                Response.Write(ret); 
            }
        }

        private string getDictionaryData(Dictionary<string, object> data)

        {
            string ret = null; 
            foreach (KeyValuePair<string, object> item in data) 
            {
                if (item.Value != null && item.Value.GetType() == typeof(Dictionary<string, object>))
                {
                    ret += item.Key.ToString() + "={";
                    ret += getDictionaryData((Dictionary<string, object>)item.Value); 
                    ret += "};";
                }
                else
                {
                    ret += item.Key.ToString() + "=" + (item.Value == null ? "null" : item.Value.ToString()) + ";";
                }
            }
            return ret; 
        }
    }
}
可参考demo中的接口调用文件:

CCPRestDemo\Demo\SendTemplateSMS\Default.aspx.cs。

四 常见错误码

代码 含义
112300
接收短信的手机号码为空
112301
短信正文为空
112302
群发短信已暂停
112303
应用未开通短信功能
112304
短信内容的编码转换有误
112305
应用未上线,短信接收号码外呼受限
112306
接收模板短信的手机号码为空
112307
模板短信模板ID为空
112308
模板短信模板data参数为空
112309
模板短信内容的编码转换有误
112310
应用未上线,模板短信接收号码外呼受限
160031
【短信】参数解析失败
160032
【短信】短信模板无效
160033
【短信】短信存在黑词
160034
【短信】号码黑名单
160035
【短信】短信下发内容为空
160036
【短信】短信模板类型未知
160037
【短信】短信内容长度限制
160038
【短信】短信验证码发送过频繁
160039
【短信】发送数量超出同模板同号天发送次数上限
160040
【短信】验证码超出同模板同号码天发送上限
160041
【短信】通知超出同模板同号码天发送上限
160042
【短信】号码格式有误
160043
【短信】应用与模板id不匹配
160050
【短信】短信发送失败

五 常见问题

1.短信发送成功,但是目标手机却没有收到?

答:A.同一个手机号每天只能发1条内容相同的短信

B.同一个手机号每天只能发10条内容不同的短信

C.在用未上线应用或者测试DEMO的时候,只能给“控制台-测试号码”里面配置的手机号发送短信。

D.非模板短信不允许发送

E.测试模板1只允许未上线应用使用,上线应用不能使用

2.符合所有模板短信规则,目标手机却没有收到短信。

答:A.请联系网页上技术支持或售前,由他们为您解决具体的问题。

3.模板审核通过,请求却提示:”模板不存在“?

答:模板对应应用。1若是测试,请使用未上线状态的应用appid来测试,可以新建一个应用来测试;2若是正式使用切换自定义模板,请求包体里面的appid也应相对切换到运营中的应用appid。

六 Demo演示

通过浏览器体验:短信验证码/通知

七 收费方式

计费单位:按条计费;

对应价格:"(国内)短信(下行)",报价请进入价格查看。

八 补充说明

目前短信功能只面向企业发送短信验证码、相关通知,不可用于广告群发业务; 使用短信接口需报备发送模板,审核通过后才可正常使用,控制台—提交模板中提交短信模板。