短信消息回执推送接口文档
一、推送说明
当253平台收到运营商回送的短信状态后，会按照您账户配置的短信回送地址，以GET请求方式推送回执信息。
1.1 推送重试机制
- 推送失败后将自动重试，最多重试2次（共3次推送机会）
- 每次推送间隔时间为1分钟
- 第三次推送失败后，将不再继续推送
1.2 客户端响应要求
服务端推送成功后，客户端需返回指定JSON格式响应码，用于确认接收状态：
| 响应码JSON | 含义说明 |
|---|
| {"clcode":"000000"} | 接收成功，无需再次推送 |
| {"clcode":"111111"} | 接收失败，平台将按重试规则重新推送 |
二、推送URL格式
http://client_url?receiver=&pswd=&msgid=xxx&reportTime=xxx&mobile=xxx&status=xxx¬ifyTime=xxx&statusDesc=xxx&length=xxx&uid=xxx
说明：
client_url 为您账户中配置的短信回送地址- 参数间以
&连接，无值参数（如未配置receiver、pswd）保留参数名，值为空
三、推送参数说明
| 参数名 | 类型 | 描述 | 示例值 |
|---|
| receiver | String | 接收验证的用户名，未配置则为空（如需配置请联系技术支持） | （空）或指定用户名 |
| pswd | String | 接收验证的密码，未配置则为空（如需配置请联系技术支持） | （空）或指定密码 |
| mobile | String | 接收短信的手机号码 | "13900000000" |
| status | String | 运营商返回的短信接收状态（成功状态仅为DELIVRD，其余失败状态见code.253.com） | "DELIVRD" |
| statusDesc | String | 状态对应的中文解释，已通过UTF-8进行URLEncode编码，需客户端解码后使用 | "%E7%9F%AD%E4%BF%A1%E5%8F%91%E9%80%81%E6%88%90%E5%8A%9F" |
| notifyTime | String | 253平台收到运营商状态报告的时间，格式：yyMMddHHmmss | "241104172820" |
| reportTime | String | 运营商返回的状态更新时间，格式：YYMMddHHmm（YY为年份后两位） | "2411041728" |
| msgid | String | 消息唯一ID（32位纯数字，与发送接口响应的msgId一致） | "24073116453300902203000007708373" |
| length | int | 下发短信的计费条数（纯数字） | "1" |
| uid | String | 发送接口中传入的uid参数，未传入则无此参数 | "154789574" |
四、示例演示
4.1 推送URL示例（已配置receiver/pswd）
http://client_url?receiver=test_user&pswd=test_pwd&msgid=24073116453300902203000007708373&reportTime=2411041728&mobile=13900000000&status=DELIVRD¬ifyTime=241104172820&statusDesc=%E7%9F%AD%E4%BF%A1%E5%8F%91%E9%80%81%E6%88%90%E5%8A%9F&length=1&uid=154789574
4.2 推送URL示例（未配置receiver/pswd、未传入uid）
http://client_url?receiver=&pswd=&msgid=24073116453300902203000007708373&reportTime=2411041728&mobile=13900000000&status=DELIVRD¬ifyTime=241104172820&statusDesc=%E7%9F%AD%E4%BF%A1%E5%8F%91%E9%80%81%E6%88%90%E5%8A%9F&length=1
4.3 客户端成功响应示例
{"clcode":"000000"}
4.4 客户端失败响应示例
{"clcode":"111111"}
五、注意事项
- 请确保回送地址（client_url）可正常访问，且支持GET请求
statusDesc参数需通过UTF-8解码后获取明文，解码前需处理URL转义字符- 请妥善保存
msgid参数，用于消息状态的唯一关联查询
- 失败状态码详情可访问 code.253.com 查询
- 如需配置receiver/pswd验证，或有其他疑问，请联系技术支持
| 前置条件 | 说明 |
|---|
传入report参数
|
- 提交短信接口入参中，传入report参数："report"="true"，否则无法使用回执接口
|
| 提前配置获取方式 |
- 新开账户默认为推送方式，如需改为拉取需要登录控制台修改
- 推送方式的推送地址可通过短信接口传入，也可以登录控制台配置。
|
开发引导
以使用短信接口为列
第一步：注册及报备
1、注册账号后登陆创蓝短信后台。
2、第一步，添加企业认证审核，通过后添加短信签名，短信模板，审核通过以后即可使用，此步骤不涉及技术开发，请联系商务或者客服解决。
第二步：下载对应语言示例，选择合适的短信发送接口，每个接口的入参不同，请查看右边目录跳转至参数说明处
| API 列表 | 接口地址 | 特性 | 常用场景 |
|---|
| 相同内容单、群发接口 | https://smssh1.253.com/msg/v1/send/json | 此接口适用批量发送相同内容 | 任何场景 |
| 不同内容单、群发接口 | https://smssh1.253.com/msg/variable/json | 单号码对应单内容批量下发 | 任何场景 |
| 账号余额查询 | https://smssh1.253.com/msg/balance/json | 查询账号剩余量（条数） | 任何场景 |
| 拉取上行明细 | https://smssh1.253.com/msg/pull/mo | 查询终端的短信回复情况 | 回复量<20W |
| 拉取状态报告明细 | https://smssh1.253.com/msg/pull/report | 查询短信是否发送成功 | 日发送量<20W |
第三步：根据需求开发其他 API
1.短信平台类客户可能拥有多个账号，多个签名和多个短信模板，可能需要开发“添加签名 API”、“添加模板 API”，从而实现使用 API 进行管理。
2.提交短信后接口会产生 msgid 唯一参数，若想使用此参数查询，您可能需要开发“msgid 查询 API”。
3.若想自定义发送短信的 msgid 参数，您可能需要开发“msgid 自定义 API 短信”。
4.发送量比较大，手动拉取状态比较费时的，可能需要“自动回送状态报告功能”或“自动回送上行记录功能”。
语言示例
创蓝提供了
Java PHP Python GO ASP ASP.NET NODE 七种语言的
示例，供您按需下载。
返回值说明
常见问题
调用说明
注：云通讯为确保您的账户和信息安全，请在功能上线前进入后台添加您要使用的 IP 地址到 IP 白名单列表中
统一请求格式
URL：https://smssh1.253.com/msg/v1/send/json
其中，如短信下发为 send，余额查询为 balance；
HTTP 头信息:
Content-Type:application/json;charset=utf-8;
说明：
请求方式(Method)：统一用 POST 方式编码：UTF-8
最佳实践：
请使用发短信接口
复制已报备的模板到 msg 参数中,示例：”msg“：“【签名】+内容”
请设置好 IP 白名单
IP 白名单可以有效提高账户安全性
请补充完整您的账户资料信息
包括设置余额提醒阈值、邮箱绑定和营业执照等账户信息，方便我们提供更好的服务
提高发送速度建议
配置合适的线程数，避免网络拥塞导致您延迟增加。根据您实际发送量与对接或运维人员配置好流量。
海外用户可以调用云通讯国际短信接口。
demo 下载
本页面提供 Java、PHP、Python、C#、go 的 demo 下载。
demo 包内有部分使用说明，各接口的详细使用说明请浏览各 API 详情页。
如创蓝未提供您使用语言的 demo，您可以根据 API 文档开发接口。
代码示例
PHP DEMO
功能说明：该接口要求提前在创蓝后台添加模板，提交短信时，系统会自动匹配审核通过的模板，匹配成功任意一个模板即可发送。签名和短信内容需要提前在创蓝云通讯后台报备,审核通过后即可发送。
<?php
http://zabbix.253.com/zabbixheader("Content-Type:text/html;charset=utf-8"\);
//$code = mt_rand(100000,999999);
$clapi=newChuanglanSmsApi();
//设置您要发送的内容：其中“【】”中括号为运营商签名符号，多签名内容前置添加提交
//普通短信发送调用
$result= $clapi->sendSMS('18516627499','【253云通讯】您好，您的验证码是123456' );
if(!is_null(json_decode($result))){
$output=json\_decode\($result,**true**\);
if(isset($output['code']) && $output['code']=='0'){
echo'发送成功';
}else{
echo$output['errorMsg'];
}
}else{
echo$result;
}
class ChuanglanSmsApi
{
//参数的配置请登录www.chuanglan.com获取以下API信息↓↓↓↓↓↓↓
constAPI_SEND_URL='
http://smssh1.253.com/msg/v1/send/json
'; //创蓝发送短信接口URL
constAPI_VARIABLE_URL='[[
http://smssh1.253.com/msg/variable/json';//创蓝变量短信接口URL](https://smssh1.253.com/msg/variable/json';//创蓝变量短信接口URL](http://smssh1.253.com/msg/variable/json';//创蓝变量短信接口URL](http://smssh1.253.com/msg/variable/json';//创蓝变量短信接口URL)\\\
)
constAPI_BALANCE_QUERY_URL='[[
http://smssh1.253.com/msg/balance/json';//创蓝短信余额查询接口URL](https://smssh1.253.com/msg/balance/json';//创蓝短信余额查询接口URL](http://smssh1.253.com/msg/balance/json';//创蓝短信余额查询接口URL](http://smssh1.253.com/msg/balance/json';//创蓝短信余额查询接口URL)\\\
)
constAPI_ACCOUNT= 'N57***'; //创蓝API账号
constAPI_PASSWORD= '*******';//创蓝API密码
functionsendSMS($mobile, $msg, $needstatus = 'true')
{
//创蓝接口参数
$postArr =array(
'account' =>self::API_ACCOUNT,
'password' =>self::API_PASSWORD,
'msg' => urlencode($msg),
'phone' => $mobile,
'report' => $needstatus
);
$result = $this->curlPost(self::API_SEND_URL, $postArr);
//var_dump($postArr);die();
return$result;
}
functionsendVariableSMS($msg, $params)
{
global$chuanglan_config;
//创蓝接口参数
$postArr =array(
'account' =>self::API_ACCOUNT,
'password' =>self::API_PASSWORD,
'msg' => $msg,
'params' => $params,
'report' => 'true'
);
$result = $this->curlPost\(**self**::API\_VARIABLE\_URL, $postArr\);
return$result; }
functionqueryBalance() { global$chuanglan_config;
$result = $this->curlPost\(**self**::API\_VARIABLE\_URL, $postArr\);
return$result;
}
functionqueryBalance()
{
global$chuanglan_config;
//查询参数
$postArr =array( 'account' =>self::API_ACCOUNT, 'password' =>self::API_PASSWORD, ); $result = $this->curlPost(self::API_BALANCE_QUERY_URL, $postArr); return$result; }
functioncurlPost($url, $postFields) { $postFields = json_encode($postFields); $ch = curl_init(); curl_setopt($ch,CURLOPT_URL, $url); curl_setopt($ch,CURLOPT_HTTPHEADER,array( 'Content-Type: application/json; charset=utf-8' //json版本需要填写 Content-Type: application/json; ) ); curl_setopt($ch,CURLOPT_IPRESOLVE,CURL_IPRESOLVE_V4); curl_setopt($ch,CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch,CURLOPT_POST, 1); curl_setopt($ch,CURLOPT_POSTFIELDS, $postFields); curl_setopt($ch,CURLOPT_TIMEOUT, 60); curl_setopt($ch,CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch,CURLOPT_SSL_VERIFYPEER, 0); $ret = curl_exec($ch); if(false== $ret) { $result = curl_error($ch); }else{ $rsp = curl_getinfo($ch,CURLINFO_HTTP_CODE); if(200 != $rsp) { $result = "请求状态" . $rsp . "" . curl_error($ch); }else{ $result = $ret; } } curl_close($ch); return$result; }
}
C# DEMO
功能说明：该接口要求提前在创蓝后台添加模板，提交短信时，系统会自动匹配审核通过的模板，匹配成功任意一个模板即可发送。签名和短信内容需要提前在创蓝云通讯后台报备,审核通过后即可发送。
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Text;
using System.Threading.Tasks;
namespace sendDemo
{
classProgram
{
staticvoid Main(string[] args)
{
//请求地址请登录www.chuanglan.com获取
String account ="N9994784";//API账号
String password ="Dasibugaosuni12";//API密码
String url ="[[[
https://smssh1.253.com/msg/v1/send/json";//API接口地址](https://smssh1.253.com/msg/send/json";//API接口地址](http://smssh1.253.com/msg/send/json";//API接口地址](http://smssh1.253.com/msg/send/json";//API接口地址)](http://smssh1.253.com/msg/send/json";//API接口地址](http://smssh1.253.com/msg/send/json";//API接口地址](http://smssh1.253.com/msg/send/json";//API接口地址](http://smssh1.253.com/msg/send/json";//API接口地址))\
)
String phone ="18516627499";
String msg ="【253云通讯】您的验证码是123456";//253短信测试内容
string postJsonTpl ="\"account\":\"{0}\",\"password\":\"{1}\",\"phone\":\"{2}\",\"report\":\"true\",\"msg\":\"{3}\"";
string jsonBody =string.Format(postJsonTpl, account, password, phone, msg);
String result= doPostMethodToObj(url,"{" + jsonBody +"}");
}
publicstaticstring doPostMethodToObj(string url,string jsonBody)
{
string result =String.Empty;
HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(url);
httpWebRequest.ContentType ="application/json";
httpWebRequest.Method ="POST";
// Create NetworkCredential Object
NetworkCredential admin_auth =newNetworkCredential("username","password");
// Set your HTTP credentials in your request header
httpWebRequest.Credentials = admin\_auth;
// callback for handling server certificates
ServicePointManager.ServerCertificateValidationCallback =delegate {returntrue; };
using (StreamWriter streamWriter =newStreamWriter(httpWebRequest.GetRequestStream()))
{
streamWriter.Write\(jsonBody\);
streamWriter.Flush\(\);
streamWriter.Close\(\);
HttpWebResponse httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (StreamReader streamReader =newStreamReader(httpResponse.GetResponseStream()))
{
result = streamReader.ReadToEnd\(\);
}
}
return result;
}
}
Asp DEMO
功能说明：该接口要求提前在创蓝后台添加模板，提交短信时，系统会自动匹配审核通过的模板，匹配成功任意一个模板即可发送。签名和短信内容需要提前在创蓝云通讯后台报备,审核通过后即可发送。
Sms.js
<%@LANGUAGE="VBSCRIPT" CODEPAGE="65001"%>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<%
dim username,getcode
username=request.Form("username")
getcode=cstr(session("getcode"))
Function Post(url,data)
dim Https
set Https=server.createobject("MSXML2.XMLHTTP")
Https.open "POST",url,false
Https.setRequestHeader "Content-Type","application/json"
Https.send data
if Https.readystate=4 then
dim objstream
set objstream = Server.CreateObject("adodb.stream")
objstream.Type = 1
objstream.Mode =3
objstream.Open
objstream.Write Https.responseBody
objstream.Position = 0
objstream.Type = 2
objstream.Charset = "utf-8"
Post = objstream.ReadText
objstream.Close
set objstream = nothing
set https=nothing
end if
End Function
dim target,post_data,tempResult
''//请登录www.chuanglan.com获取API账号、密码以及短信发送的URL
target = "
https://smssh1.253.com/msg/v1/send/json
"
''//设置您要发送的内容：其中“【】”中括号为运营商签名符号，多签名内容前置添加提交
post_data="{""account"":""N9994784"",""password"":""Dasibugaosuni12"",""phone"":"""&username&""",""msg"":""用户您好，您的验证码是"&getcode&""",""report"":""false""}"
response.Write(Post(target,post_data))
''//请自己解析Post(target,post_data)返回的json格式并实现自己的逻辑
%>
Go DEMO
功能说明：该接口要求提前在创蓝后台添加模板，提交短信时，系统会自动匹配审核通过的模板，匹配成功任意一个模板即可发送。签名和短信内容需要提前在创蓝云通讯后台报备,审核通过后即可发送。
Main.go
package main
import (
"net/http"
"net/url"
"encoding/json"
"fmt"
"bytes"
"io/ioutil"
"unsafe"
)
type JsonPostSample struct {
}
func main() {
params := make\(map\[string\]interface{}\)
//请登录www.chuanglan.com获取API账号、密码以及短信发送的URL
params\["account"\] = "" //创蓝API账号
params\["password"\] = "" //创蓝API密码
params\["phone"\] = "18721755342" //手机号码
//设置您要发送的内容：其中“【】”中括号为运营商签名符号，多签名内容前置添加提交
params\["msg"\] =url.QueryEscape\("【253云通讯】您好，您的验证码是999999"\)
params\["report"\] = "true"
bytesData, err := json.Marshal\(params\)
if err != nil {
fmt.Println\(err.Error\(\) \)
return
}
reader := bytes.NewReader\(bytesData\)
url := "http://smssh1.253.com/msg/v1/send/json" //短信发送URL
request, err := http.NewRequest\("POST", url, reader\)
if err != nil {
fmt.Println\(err.Error\(\)\)
return
}
request.Header.Set\("Content-Type", "application/json;charset=UTF-8"\)
client := http.Client{}
resp, err := client.Do\(request\)
if err != nil {
fmt.Println\(err.Error\(\)\)
return
}
respBytes, err := ioutil.ReadAll\(resp.Body\)
if err != nil {
fmt.Println\(err.Error\(\)\)
return
}
str := \(\*string\)\(unsafe.Pointer\(&respBytes\)\)
fmt.Println\(\*str\)
}
Node.js DEMO
功能说明：该接口要求提前在创蓝后台添加模板，提交短信时，系统会自动匹配审核通过的模板，匹配成功任意一个模板即可发送。签名和短信内容需要提前在创蓝云通讯后台报备,审核通过后即可发送。
const http = require('http');
/* 参数的配置 请登录www.chuanglan.com 获取以下API信息 ↓↓↓↓↓↓↓ */
// API账号
let account = '';
// API密码
let password = '';
//接口域名
let host = '';
/* 发送短信方法 ↓↓↓↓↓↓↓ */
const sendSms = (options) => {
// option:发送提交的参数
let params = JSON.stringify(options);
post('/msg/send/json', params);
};
/* 余额查询方法 ↓↓↓↓↓↓↓ */
const getBlance = (options) => {
// option:查询余额提交的参数
let params = JSON.stringify(options);
post('/msg/balance/json', params);
};
/* 发送请求过程，可根据自身系统处理 ↓↓↓↓↓↓↓ */
function post(url, params) {
let options = {
protocol: 'http:', // 创蓝所有接口支持https和http协议，建议https
hostname: host,
port: 80,
path: url,
method: 'POST',
headers: {
'Content-Type': 'application/json; charset=UTF-8'
}
};
const req = http.request(options, (res) => {
console.log(`状态码: ${res.statusCode}`);
res.setEncoding('utf8');
res.on('data', (chunk) => {
console.log(`返回参数: ${chunk}`);
});
});
req.write(params);
req.end();
}
/* 发送短信实例模拟 ↓↓↓↓↓↓↓ */
sendSms({
account: account, // 必传，API账号，管理后台获取
password: password, // 必传，API密码，管理后台获取（8-16位)
msg: '【253云通讯】您的验证码是123456。如非本人操作，请忽略。', // 审核通过的签名以及模板，长度不超过536个字符
phone: '15121060862' // 必传，接收的手机号；多个手机号使用英文逗号间隔，一次不要超过1000个；
// "sendtime": "" // 可不传，定时发送时间的时间戳
// "report": flase, // 可不传，是否需要状态报告，默认false；如需状态报告则传”true”
// "extend": 253, // 可不传，下发短信号码扩展码,建议1-3位
// "uid": "2018abc" // 可不传，该条短信在您业务系统内的ID，如订单号或者短信发送记录流水号
});
/* 查询余额实例模拟 ↓↓↓↓↓↓↓ */
getBlance({
account: account, // 必传，API账号，管理后台获取
password: password // 必传，API密码，管理后台获取（8-16位)
});
Python DEMO
功能说明：该接口要求提前在创蓝后台添加模板，提交短信时，系统会自动匹配审核通过的模板，匹配成功任意一个模板即可发送。签名和短信内容需要提前在创蓝云通讯后台报备,审核通过后即可发送。
sms.py
#!/usr/local/bin/python
#-*- coding:utf-8 -*-
# Author: jacky
# Time: 14-2-22 下午11:48
# Desc: 短信http接口的python代码调用示例
import httplib
import urllib
import json
#参数的配置 请登录www.chuanglan.com获取以下API信息 ↓↓↓↓↓↓↓
#创蓝接口域名
host = ""
#创蓝API账号
account = ""
#创蓝API密码
password = ""
#端口号
port = 80
#版本号
version = "v1.1"
#余额查询的URL
balance_get_uri = "/msg/balance/json"
#普通短信发送的URL
sms_send_uri = "/msg/v1/send/json"
def get_user_balance():
"""
取账户余额
"""
params = {'account': account, 'password' : password}
params=json.dumps\(params\)
headers = {"Content-type": "application/json"}
conn = httplib.HTTPConnection\(host, port=port\)
conn.request\('POST', balance\_get\_uri, params, headers\)
response = conn.getresponse\(\)
response\_str = response.read\(\)
conn.close\(\)
return response\_str
def send_sms(text, phone):
"""
能用接口发短信
"""
params = {'account': account, 'password' : password, 'msg': urllib.quote\(text\), 'phone':phone, 'report' : 'false'}
params=json.dumps\(params\)
headers = {"Content-type": "application/json"}
conn = httplib.HTTPConnection\(host, port=port, timeout=30\)
conn.request\("POST", sms\_send\_uri, params, headers\)
response = conn.getresponse\(\)
response\_str = response.read\(\)
conn.close\(\)
return response\_str
if __name__ == '__main__':
phone = "187****3161"
#设置您要发送的内容：其中“【】”中括号为运营商签名符号，多签名内容前置添加提交
text = "【253云通讯】您的验证码是1234"
\#查账户余额
print\(get\_user\_balance\(\)\)
\#调用智能匹配模版接口发短信
print\(send\_sms\(text, phone\)\)
java DEMO
功能说明：默认发送验证码短信免审，其他类型短信发送需要提前报备，报备审核通过之后下发免审，否则进入人工审核导致短信收到慢。签名请使用报备过后的签名下发，若账号有默认签名，下发不带签名会自动匹配到账号默认签名；务必不要不带签名或使用未报备的签名下发。
import com.alibaba.fastjson.JSONObject;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import com.alibaba.fastjson.JSONObject;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;
public class Sms {
public static void main(String[] args) {
//短信下发
String sendUrl = "https://smssh1.253.com/msg/v1/send/json";
Map map = new HashMap();
map.put("account","N*******");//API账号
map.put("password","************");//API密码
map.put("msg","【253云通讯】您好，您的验证码是******");//短信内容
map.put("phone","15300000000");//手机号
map.put("report","true");//是否需要状态报告
map.put("extend","123");//自定义扩展码
JSONObject js = (JSONObject) JSONObject.toJSON(map);
System.out.println(sendSmsByPost(sendUrl,js.toString()));
//查询余额
String balanceUrl = "https://smssh1.253.com/msg/balance/json";
Map map1 = new HashMap();
map1.put("account","N*******");
map1.put("password","************");
JSONObject js1 = (JSONObject) JSONObject.toJSON(map1);
System.out.println(sendSmsByPost(balanceUrl,js1.toString()));
}
public static String sendSmsByPost(String path, String postContent) {
URL url = null;
try {
url = new URL(path);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestMethod("POST");
httpURLConnection.setConnectTimeout(10000);
httpURLConnection.setReadTimeout(10000);
httpURLConnection.setDoOutput(true);
httpURLConnection.setDoInput(true);
httpURLConnection.setRequestProperty("Charset", "UTF-8");
httpURLConnection.setRequestProperty("Content-Type", "application/json");
httpURLConnection.connect();
OutputStream os=httpURLConnection.getOutputStream();
os.write(postContent.getBytes("UTF-8"));
os.flush();
StringBuilder sb = new StringBuilder();
int httpRspCode = httpURLConnection.getResponseCode();
if (httpRspCode == HttpURLConnection.HTTP_OK) {
BufferedReader br = new BufferedReader(
new InputStreamReader(httpURLConnection.getInputStream(), "utf-8"));
String line = null;
while ((line = br.readLine()) != null) {
sb.append(line);
}
br.close();
return sb.toString();
}
} catch (Exception e) {
e.printStackTrace();
}
return null;
}
}
普通接口
相同内容单、群发接口
应用场景
验证码短信
接口可以实现给指定手机号发验证码短信，用短信验证码来验证操作者的身份，来确保是本人操作，或者是经由本人授权操作。
通知短信
短信在实用工具功能和修辞性事功能基础上又衍生出新的功能形态—文化评判与社会参与功能，而且在这种传媒体的引导和推动下，这种功能日益得到彰显和强化。
营销短信
发送一般用于不同行业、不同领域的企事业单位、团体组织机构对于自身产品的推广和介绍，达到加快速或加深沟通联系；提高服务质量；加快工作效率（包括商业销售效率）的手段
准备工作
使用我司接口，需要先注册我司账号，提交营业执照-即可正式使用，使用之前，建议先完成签名以及模板报备方便测试。（发送短信之前，必须提交签名;模板,不提交的话会进入人工审核，延长发送短信的时间）
附注：因运营商政策，请先在后台完成报备签名、模板及做相关设置(详见接入引导)，再开发 API。
终端接入方式推荐 https 协议使用接口,短信请求务必采用 IP 鉴权（IP 白名单）验证提交
请求参数
URL：https://smssh1.253.com/msg/v1/send/json
请求方式：json 格式封装的字符串，采用 post 方式提交请求
请求协议：http，https
编码格式：utf-8
Content-Type：application/json
| 参数名称 | 类型 | 是否必传 | 描述 | 示例 |
|---|
| account | string | 是 | API 账号，登录云通讯获取 | "account":"N9000123" |
| password | string | 是 | API 密码，登录云通讯获取 | "password":"Chuanglan253" |
| msg | String | 是 | 此处填写审核通过的签名和模板，中文括号是代表短信签名。内容总长度在1000个字以内。用营销账号提交短信时最末尾需带上“拒收请回复R”，否则营销短信将进入人工审核，退订语现在只支持“拒收请回复R”。 | "msg":"【253 云通讯】创蓝 253 云通讯欢迎您的测试，祝您体验愉快" |
| phone | string | 是 | 接收的手机号；多个手机号使用英文逗号间隔，一次不要超过 1000 个； | 批量群发"phone":"15800000000,15300000000" |
| sendtime | string | 否 | 定时发送时间，*≤*当前时间则立即发送；只能定时 7 天内，格式为 yyyyMMddHHmm | "sendtime":"201805241420" |
| report | string | 否 | 如需状态报告则传"true",默认"false" | "report":"true" |
| extend | string | 否 | 下发短信号码扩展码，用于匹配上行回复。一般1-3 位(只支持传数字，具体能传几位需询问商务) | "extend":"253" |
| uid | string | 否 | 自定义参数，如订单号或短信发送记录流水号，64 位。 | "uid":"2018abc" |
请求示例
{
"account":"N6000001",
"password":"123456",
"msg":"【253云通讯】您的验证码是：2530",
"phone":"15800000000",
"sendtime":"202311260950",
"report":"true",
"extend":"555",
"uid":"321abc"
}
响应说明
{
"code":"0",
"msgId":"23112615065227118",
"time":"20231126150652",
"errorMsg":""
}
| 参数名称 | 类型 | 描述 | 示例 |
|---|
| code | string | 提交响应状态码，返回“0”表示提交成功（详细参考提交响应状态码） | "code":"0" |
| msgId | string | 消息 id（32 位纯数字） | "msgId":"24073116453300902203000007708373" |
| time | string | 响应时间 | "time":"20240731164533" |
| errorMsg | string | 状态码说明（提交成功返回空） | "errorMsg":"" |
实现业务逻辑
生成短信内容，调用发送接口传入（账号、密码、手机号、内容等参数）发送短信。
短信内容前面为，签名需要通过审核才能使用，模板如不匹配接口会进入人工审核，延缓发送速度。报错记录可以在管理后台查看
按需开发功能
对短信发送状态做实时监控
如果您需要通过程序对短信的发送状态做实时监控，可以开发“推送/获取状态报告”接口。 如果只是想了解短信发送状态，无实时监控需求，"云通讯管理控制台—数据统计 " 可以看到实时及历史的到达率、发送量、接口失败原因等报表。
·短信平台/代理类客户 如果您是短信平台/代理，需要管理众多客户的签名及模板。您可能需要“签名提交 API”、“模板管理 API”、“账户 API”。 从而通过 API 接口轻松管理签名、模板、账户。
·获取上行短信如果您的业务中，需获取用户回复的上行短信，可以开发“回送上行短信 API”。通过这个接口，如果用户回复了您的短信，云通讯会第一时间推送给您
不同内容单、群发接口
应用场景
用于验证码通知短信和营销短信内容里含有变量的短信的发送，丰富了短信使用的种类。
准备工作
使用我司接口，需要先注册我司账号，提交营业执照之后，即可正式使用，使用之前，建议先完成签名以及模板的报备，方便之后测试。（发送短信之前，必须提交签名；模板可以不提交发送短信，但是不提交的话会进入人工审核，延长发送短信的时间）。
附注：因运营商政策，请先在后台完成报备签名、模板及做相关设置(详见接入引导)，再开发 API。
终端接入方式推荐 https 协议使用接口,短信请求务必采用 IP 鉴权（IP 白名单）验证提交
请求参数
URL：https://smssh1.253.com/msg/variable/json
请求方式：json 格式封装的字符串，采用 post 方式提交请求
请求协议：http，https
编码格式：utf-8
Content-Type：application/json
| 参数名称 | 类型 | 是否必传 | 描述 | 示例 |
|---|
| account | string | 是 | API 账号，登录云通讯获取 | "account":"N9000123" |
| password | string | 是 | API 密码，登录云通讯获取 | "password":"Chuanglan253" |
| msg | String | 是 | 此处填写审核通过的签名和模板，中文括号是代表短信签名。内容总长度在1000个字以内，变量符号固定使用{$var}，最多 20 个。用营销账号提交短信时最末尾需带上“拒收请回复R”否则营销短信将进入人工审核，退订语现在只支持“拒收请回复R”。 | "msg":"【253 云通讯】创蓝云通讯验证码是{$var}，祝您体验愉快" |
| params | string | 是 | 手机号码和变量参数，多组参数使用英文分号区分；此字段上限支持 1000 个参数组。格式不符的参数系统自动过滤掉 | 批量群发"phone":"15800000000,1234；15300000000,4321" |
| sendtime | string | 否 | 定时发送时间，*≤*当前时间则立即发送；只能定时 7 天内，格式为 yyyyMMddHHmm | "sendtime":"201805241420" |
| report | string | 否 | 如需状态报告则传"true",默认"false" | "report":"true" |
| extend | string | 否 | 下发短信号码扩展码，用于匹配上行回复。一般支持1-3位(只支持传数字，具体能传几位需询问商务) | "extend":"253" |
| uid | string | 否 | 自定义参数，如订单号或短信发送记录流水号，64 位。 | "uid":"2018abc" |
请求实例
{
"account":"N6****",
"password":"1234***",
"msg":"【253云通讯】{$var}您的验证码是：{$var}",
"params":"15800000000,张先生,1234;13800000000,李小姐,4321",
"sendtime":"202311260950",
"report":"true",
"extend":"555",
"uid":"321abc"
}
PS：params 参数组的具体格式：参数组从左往右第一个为发送的手机号码，第二个为第一个变量，第三个为第二个变量，以此类推，变量的数目需要和内容里变量的数目（msg 里的{$var}）一一对应。
响应说明
{
"failNum":"0",
"time":"20230410103836",
"successNum":"1",
"msgId":"231126010383624511",
"errorMsg":"",
"code":"0"
}
| 参数名称 | 类型 | 描述 | 示例 |
|---|
| code | string | 提交响应状态码，返回“0”表示提交成功（详细参考提交响应状态码） | "code":"0" |
| failNum | string | 失败条数 | "failNum":"0" |
| successNum | string | 成功条数 | "successNum":"1" |
| msgId | string | 消息 id（32 位纯数字） | "msgId":"24073116453300902203000007708373" |
| time | string | 响应时间 | "time":"20240731164533" |
| errorMsg | string | 状态码说明（成功返回空） | "errorMsg":"" |
实现业务逻辑
生成短信内容，调用发送接口，传入账号、密码、手机号、内容等参数发送内容里有变量的短信。
短信内容中，签名需要通过审核才能使用，模板如不匹配接口会进入人工审核，延缓发送速度。报错记录可以在管理后台查看。
加密发送接口
提示：
- 因为运营商政策，请先登录云通讯后台报备签名以及模板后，再开发 API。
加密算法
- SIGN 生成规则：所有参数，按照 key（不包括 sign）值得 ASCII 码表升序，对 value 做拼接，最后拼接密码的 MD5（32 位小写）得到结果 values，对 values 再次 MD5 （32 位小写），得到结果即为 SIGN 参数，
- 对称加密规则：对传入参数做 3des 对称加密，加密秘钥为 密码 MD5(32 位小写)
加密算法工具类示例如下
package com.dragon.utils;
import com.alibaba.fastjson.JSONObject;
import com.alibaba.fastjson.TypeReference;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.codec.digest.DigestUtils;
import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import java.util.TreeMap;
public class DES3Utils {
private static final String CHARSET_NAME = "UTF-8";
private static final String DESEDE = "DESede";
private static final String DEFAULT_CIPHER_ALGORITHM = "DESede/ECB/PKCS5Padding";
public static void main(String[] args) throws Exception {
//加密普通短信
send();
//加密普通短信
variableSend();
}
public static String encryptBase64(String data, String key) throws Exception {
byte[] result = encrypt(data, key);
return Base64.encodeBase64String(result);
}
private static byte[] encrypt(String data, String key) throws Exception {
if (key == null || "".equals(key)) {
throw new Exception("key need to exists");
}
byte[] byteData = data.getBytes(CHARSET_NAME);
SecretKey secretKey = new SecretKeySpec(build3DesKey(key), DESEDE);
Cipher cipher = Cipher.getInstance(DEFAULT_CIPHER_ALGORITHM);
cipher.init(Cipher.ENCRYPT_MODE, secretKey);
return cipher.doFinal(byteData);
}
public static String decrypt(String data, String key) throws Exception {
if (key == null || "".equals(key)) {
throw new Exception("scretKey need to exists");
}
byte[] byteData = Base64.decodeBase64(data);
SecretKey secretKey = new SecretKeySpec(build3DesKey(key), DESEDE);
Cipher cipher = Cipher.getInstance(DEFAULT_CIPHER_ALGORITHM);
cipher.init(Cipher.DECRYPT_MODE, secretKey);
byte[] result = cipher.doFinal(byteData);
return new String(result, CHARSET_NAME);
}
private static byte[] build3DesKey(String keyStr) throws Exception {
// 3des定长密钥
byte[] key = new byte[24];
byte[] temp = keyStr.getBytes();
if (key.length > temp.length) {
System.arraycopy(temp, 0, key, 0, temp.length);
} else {
System.arraycopy(temp, 0, key, 0, key.length);
}
return key;
}
public static void send() throws Exception{
JSONObject json = new JSONObject();
String pwd = DigestUtils.md5Hex("a.1234567");
json.put("account","YZM4722127");
json.put("extend","1233");
json.put("msg","【创蓝CTU】您的验证码是：123456，请妥善保管");
json.put("phone",encryptBase64("18016290912",pwd));
json.put("report","true");
json.put("timestamp",System.currentTimeMillis());
json.put("uid","S5043203--71----0000336");
TreeMap<String ,Object> paramMap = JSONObject.parseObject(json.toJSONString(), new TypeReference<TreeMap<String, Object>>(){});
StringBuffer buffer1 = new StringBuffer();
paramMap.values().stream().forEach( obj->{
buffer1.append(obj.toString());
});
buffer1.append(pwd);
String sign = DigestUtils.md5Hex(buffer1.toString());
json.put("sign",sign);
// postJson(url,json.toJSONString())
System.out.println(json);
}
public static void variableSend() throws Exception{
JSONObject json = new JSONObject();
String pwd = DigestUtils.md5Hex("a.123456");
json.put("account","YZM4722127");
json.put("extend","1233");
json.put("msg","【创蓝】您的验证码是：{$var}，请妥善保管");
json.put("params",encryptBase64("15617436626,123456",pwd));
json.put("report","true");
json.put("timestamp",System.currentTimeMillis());
json.put("uid","S5043203--71----0000336");
TreeMap<String ,Object> paramMap = JSONObject.parseObject(json.toJSONString(), new TypeReference<TreeMap<String, Object>>(){});
StringBuffer buffer1 = new StringBuffer();
paramMap.values().stream().forEach( obj->{
buffer1.append(obj.toString());
});
buffer1.append(pwd);
String sign = DigestUtils.md5Hex(buffer1.toString());
json.put("sign",sign);
// postJson(url,json.toJSONString())
System.out.println(json);
}
}
相同内容加密接口
请求参数
URL：https://smssh1.253.com/msg/v1/send/encrypt/json
请求方式：json 格式封装的字符串，采用 post 方式提交请求
请求协议：http，https
编码格式：utf-8
Content-Type：application/json
| 字段 | 类型 | 必传 | 说明 |
|---|
| account | String | 是 | API 账号，登录云通讯获取 |
| sign | 签名 | 是 | 生成规则见红色标注部分 1 |
| msg | String | 是 | 此处填写审核通过的签名和模板，中文括号是代表短信签名。内容总长度在1000个字以内，用营销账号提交短信时最末尾需带上“拒收请回复R”否则营销短信将进入人工审核，退订语现在只支持“拒收请回复R”。示例：【253 云通讯】您的验证码是 123456。 |
| phone | String | 是 | 手机号码，多个手机号码使用英文逗号分隔，用 3des 加密，加密规则见目录的加密算法或者 DEMO |
| timestamp | String | 是 | 客户请求提交时间戳, 长度 13 的 long 类型时间戳 |
| sendtime | String | 否 | 定时短信时间，格式为 yyyyMMddHHmm，值小于或等于当前时间则立即发送，默认立即发送 |
| report | String | 否 | 如需状态报告则传 true（如需要状态报告和上行的拉取或者推送，必须为 true） |
| extend | String | 否 | 纯数字，需保证手机端口号加自定义扩展码总位数不超过 20 位，建议 1-3 位 |
| uid | String | 否 | 一般可以设置订单号或者短信发送记录流水号，用于区分短信业务，总位数不超过 64 位。 |
响应参数
| 字段 | 类型 | 描述 |
|---|
| time | String | 时间 |
| msgId | String | 创蓝短信 ID（32 位） |
| code | string | 状态码，0：成功 |
| erorMsg | String | 错误信息 |
请求示例
{
"account": "YZM4722127",
"extend": "1233",
"msg": "【签名】你的订单号：1214341退订回TD",
"phone": "H527T6T60/r9RQ9TQzr426NGQRPxKvMNv7C61+fuD6CNCQ63jlBKeQ==",
"report": "true",
"sendStamp": "1595434437467",
"uid": "S5043203--71----0000334",
"sign":"325fa8e6512776ec7c6f6caf7efba79b"
}
响应示例
{
"code": "130",
"msgId": "",
"time": "20200720095755",
"errorMsg": "请求参数错误"
}
"code": "0",为请求接口提交成功，非 0 为不成功，错误原因请参考"短信提交接口响应码说明"
一次提交 msgid 不得超过 100 个，单个 phones 不超过 100 个。
不同内容加密接口
请求参数
URL：https://smssh1.253.com/msg/v1/variable/encrypt/json
请求方式：json 格式封装的字符串，采用 post 方式提交请求
请求协议：http，https
编码格式：utf-8
Content-Type：application/json
| 字段 | 类型 | 必传 | 说明 |
|---|
| account | String | 是 | API 账号，登录云通讯获取 |
| Sign | 签名 | 是 | 生成规则见红色标注部分 1 |
| msg | String | 是 | 此处填写审核通过的签名和模板，中文括号是代表短信签名。变量符号固定使用:“{$var}”，内容总长度在1000个字以内。用营销账号提交短信时最末尾需带上“拒收请回复R”否则营销短信将进入人工审核，退订语现在只支持“拒收请回复R”。示例：【253 云通讯】您的验证码是 123456。 |
| params | String | 是 | 手机号码和变量参数，多组参数使用英文分号;区分，必填，使用 3des 加密，加密规则见目录的加密算法或者 DEMO |
| timestamp | String | 是 | 客户请求提交时间戳, 长度 13 的 long 类型时间戳 |
| sendtime | String | 否 | 定时短信时间，格式为 yyyyMMddHHmm，值小于或等于当前时间则立即发送，默认立即发送 |
| report | String | 否 | 如需状态报告则传 true（如需要状态报告和上行的拉取或者推送，必须为 true） |
| extend | String | 否 | 纯数字，需保证手机端口号加自定义扩展码总位数不超过 20 位，用于匹配上行回复。一般支持1-3位(只支持传数字，具体能传几位需询问商务) |
| uid | String | 否 | 一般可以设置订单号或者短信发送记录流水号，用于区分短信业务，总位数不超过 64 位 |
响应参数
| 字段 | 类型 | 必传 | 说明 |
|---|
| time | String | 时间 | |
| msgId | String | 创蓝短信 ID（32 位） | |
| code | string | 状态码，0：成功 | |
| erorMsg | String | 错误信息 | |
请求示例
{
"account": "YZM4722127",
"extend": "34",
"msg": "【这5是】{$var}这是一条",
"params": "H527T6T60/qvKAyEatxrV70bS0APMnxxKt0bCvtF5uuw5/+Y8JkAY9UQ2nBVjMRg74gF2A2OwpDs7/gsuljf7g==",
"report": "1",
"timestamp": "1594621872743",
"sendtime": "201908221416",
"uid": "uid-M2921317---002",
"sign":"48ed6674911d863ee31d56500bfcad0e"
}
响应示例
{
"code": "0",
"msgId": "",
"time": "20200720100327",
"errorMsg": ""
}
短信提交接口响应码说明
| 状态码 | 描述 | 问题处理人 |
|---|
| 0 | 提交成功 | 无 |
| 101 | 无此用户（account参数要传API账号不是登录后台的账号，如N111111；或API账号关停了需要联系官网客服解禁） | 技术支持 |
| 102 | 密码错（请确认密码是否一致正确，请直接复制避免手动输入错误） | 技术支持 |
| 103 | 提交过快（提交速度超过流速限制） | 技术支持 |
| 104 | 系统忙（因平台侧原因，暂时无法处理提交的短信） | 技术支持 |
| 105 | 敏感短信（短信内容包含敏感词） | 客服 |
| 106 | 消息长度错（>1036 或<=0） | 技术支持 |
| 107 | 包含错误的手机号码 | 技术支持 |
| 108 | 手机号码个数错（手机号包含了中文符号；手机号个数错了，群发>1000 或<=0） | 技术支持 |
| 109 | 无发送额度（当前使用的API账号下没有发送额度） | 商务 |
| 110 | 不在发送时间内（联系客服或商务解决) | 商务 |
| 111 | 超出该账户当月发送额度限制（联系客服或商务解决) | 商务 |
| 112 | 产品错误（通道出现异常，联系商务解决) | 商务 |
| 113 | 扩展码格式错（非数字或者长度不对） | 技术支持 |
| 114 | 可用参数组个数错误（msg参数的变量符号固定使用"{$var}"；变量符号在20个以内） | 技术支持 |
| 116 | 签名不合法或未带签名（短信签名需要报备通过后才能使用；重保签名不可用） | 客服 |
| 117 | IP 地址认证错（登录控制台在对应使用的API账号下加白ip） | 客服 |
| 118 | 用户没有相应的发送权限（账号被禁止发送，联系客服或商务解禁） | 客服 |
| 119 | 用户已过期 | 客服 |
| 120 | 违反防盗用策略(日发送限制，联系客服或商务解决) | 客服 |
| 123 | 发送类型错误（cmpp协议的账户不能使用https协议方式，请联系我方技术修改） | 技术支持 |
| 124 | 白模板匹配错误（接口传递的内容与报备的模板内容要完全一致，包括标点符号） | 客服 |
| 125 | 匹配驳回模板，提交失败（联系客服或商务解决） | 客服 |
| 127 | 定时发送时间格式错误（格式为 yyyyMMddHHmm） | 技术支持 |
| 128 | 内容编码失败 | 技术支持 |
| 129 | JSON 格式错误（header请求头是否生效：Content-Type：application/json；请求参数不是json格式） | 技术支持 |
| 130 | 请求参数错误（缺少必填参数；参数跟接口地址不匹配，例如变量参数请求普通短信接口地址） | 技术支持 |
| 132 | 消息长度错(>3500或<=0)，超过短信最大支持字数 | 技术支持 |
| 133 | 单一手机号错误 | 技术支持 |
| 134 | 违反防盗策略, 超过月发送限制（联系客服或商务解决) | 技术支持 |
| 135 | 超过同一手机号相同内容发送限制 | 技术支持 |
| 136 | 不可批量提交"验证码"短信 | 技术支持 |
| 139 | 超出安全发送时间（时间戳过期） | 技术支持 |
| 140 | 短信内容解密错误（秘钥没有使用正确） | 技术支持 |
| 144 | 产品未上线限制日发送数量（签名报备选择的未上线会日限100条，联系客服调整） | 客服 |
| 145 | 验签失败（验签不过，请参考对应接口的DEMO加签代码示例） | 技术支持 |
| 152 | MATERIAL_EXIST_ERROR （模板不存在） | 客服 |
| 153 | MESSAGE_LY_ERROR 消息长度错（>2000或者≤0） | 技术支持 |
| 154 | 长短信拼接错误 | 技术支持 |
| 155 | AIM_SEND_FAIL 转发失败 | 技术支持 |
| 158 | 退订语不符合规范，退订语现在只支持“拒收请回复R”。 | 技术支持 |
| 159 | 触发反轰炸策略 | 技术支持 |
没有更多了
