短信发送.md 18 KB
短信格式
注：正文可以包含链接、地址、换行等文案。退订语目前只支持“拒收请回复R”，不支持小写r，并且只能放在整个短信内容的最末尾，后续可能会随工信部政策调整。
| 短信类型 | 短信模板示例 | 短信格式 | 短信内容示例 |
|---|---|---|---|
| 验证码账号 | 您正在申请手机注册，验证码为：{s}，5分钟内有效！ | 【短信签名】+ 正文（只包含用于验证类的文案） | 向用户手机发送： 【创蓝云智】您正在申请手机注册，验证码为：123456，5分钟内有效！ |
| 通知短信账号 | 尊敬的客户，您购买的会员卡已于{s}正式到期。如您要继续使用，请于{s}前及时续费或重新购买。 | 【短信签名】+ 正文（除推广外的通知文案，例如物流通知） | 向用户手机发送： 【创蓝云智】尊敬的客户，您购买的会员卡已于11月29日正式到期。如您要继续使用，请于11月29日前及时续费或重新购买。 |
| 会员营销账号 | 双十一重磅来袭，晚20点满600送{s}！详见www.chuanglan.com{s}拒收请回复R | 【短信签名】+ 正文（推广类文案专用账号） + 退订语 | 向用户手机发送： 【创蓝云智】双十一重磅来袭，晚20点抢600送600！详见www.chuanglan.com/dsdf5162拒收请回复R |
发送时间限制
- 验证码(YZM开头)、通知(N开头)、会员营销（M开头）这三类账号没有限制，但M账号22点之后成功率会受到较大影响，会出现拦截，如有疑问请联系我方商务人员。
- 特殊类型账号发送时间默认是早8到晚8点，不在发送时间内提交短信，接口将会拦截您的请求并返回提交报错。如有时间上的调整，请联系我方商务人员。
发送短信接口
接口注意事项
- 如果您需要状态回执，请记得传入report参数，即"report"="true"，否则将无法获得状态回执。
- 如果调用短信接口后返回错误，您需要根据返回的响应码提示检查传入的请求参数及其取值是否正确。更多信息请见文档末尾提交响应码说明。
- 更多发送问题，请查阅短信发送FAQ
- 如您需要了解计费规则，请查阅计费说明。
- 账户有默认的余额提醒，详情查阅余额提醒文档。
模板Id发送方式接口
请求地址：
- 请求方式：json 格式封装的字符串，采用 post 方式提交请求
- Content-Type：application/json
- 编码格式：utf-8
- 请求地址：
https://smssh.253.com/msg/sms/v2/tpl/send
加密算法：
- 根据留存在创蓝的密钥md5Password与请求参数中的timestamp和nonce进行HmacSHA256Hex签名并生成makeSignature，并将此makeSignature通过Request Header传递。
- md5Password=API密码的MD5加密（32 位小写值），如：md5(password)
复制成功
// 第三方工具类，需引入以下Maven依赖
import com.alibaba.fastjson.JSONObject;
import org.apache.commons.codec.digest.DigestUtils;
import org.apache.commons.codec.digest.HmacUtils;
public String makeSignature(String md5Password, String timestamp, String nonce) {
String str = generateStr(md5Password, timestamp, nonce);
return HmacUtils.hmacSha256Hex(md5Password, str.replaceAll("\\s+", ""));
}
/**
* 签名待处理的字符串拼接
*/
public static String generateStr(String md5Password, String timestamp, String nonce){
String[] array = new String[] { md5Password, timestamp, nonce};
StringBuffer sb = new StringBuffer();
// 字符串排序
Arrays.sort(array);
for (int i = 0; i < 3; i++) {
sb.append(array[i]);
}
return sb.toString();
}
RequestHeader：
| 参数名称 | 类型 | 是否必传 | 描述 | 示例 |
|---|---|---|---|---|
| X-QA-Hmac-Signature | String | 可选 | 加密鉴权- 使用上述加密鉴权时，传递makeSignature的结果，无需传递password。 - 不加密鉴权时，该Header填空字符串""，body里password必传。 |
"nonce + md5Password(API密码的MD5的32位小写值)+ timestamp"(取决于排序结果) |
body参数：
| 参数名称 | 类型 | 是否必传 | 描述 | 示例 |
|---|---|---|---|---|
| account | String | 是 | API 账号 - 登录控制台获取，获取方式请查阅操作指引 |
"account":"N6000001" |
| password | String | 否 | API 密码 - 未开启加密鉴权时则为必传，登录控制台获取，操作指引 。 |
"password":"123456" |
| nonce | String | 是 | 32位随机字符串 - 自定义即可。 |
"nonce":"2e6eceb573" |
| timestamp | String | 是 | 秒级时间戳 - 时间戳1分钟过期 |
"timestamp":"1631865523" |
| phoneNumbers | String | 是 | 短信接收的手机号 - 号码格式无需添加区号或者+号，只填写11位手机号。 - 多个手机号使用英文逗号间隔，一次不要超过 1000 个。 |
批量群发： "phoneNumbers":"15800000000,15300000000" |
| templateParamJson | String | 否 | 变量参数值，JSON数组格式。 - 变量模板为必传。短信模板变量对应的实际值，多个手机号即传入多组JSON对象，且传入每组对象的键名个数要与模板变量个数一致。 - 键名用param1，param2、param3、param4以此类增，param1对应第一个变量{s}，param2对应第二个。 - 示例： 短信模板：尊敬的{s}，恭喜您成功充值{s}元。 templateParamJson：[{\"param1\":\"张三\",\"param2\":\"13\"},{\"param1\":\"李四\",\"param2\":\"88\"}] 填充后的第一个手机号内容：尊敬的张三，恭喜您成功充值13元。 填充后的第二个手机号内容：尊敬的李四，恭喜您成功充值88元。 |
"templateParamJson": "[ {\"param1\":\"张三\",\"param2\":\"13\"}, {\"param1\":\"李四\",\"param2\":\"88\"} ]" |
| templateId | String | 是 | 模版Id - 模板跟单个API账号为绑定关系，不可主子账号混淆传入。 - 可通过模板列表接口查询或登录控制台“模板管理”查看。 |
"templateId":"1111111" |
| signature | String | 否 | 短信签名 - 如果之前报备的模板没有选择关联签名，则为必传，需要通过此参数带上签名。 - 自25年7月起最新的模板报备中会选择关联签名，则可以不用传递此参数。 |
"signature":"【创蓝云智】" |
| report | String | 否 | 状态回执开关 - 需要传"true"，不传默认为"false"，则无法获取状态回执。 - 回执是判断短信是否成功接收的重要依据，回执详情请查阅状态回执文档。 |
"report":"true" |
| callbackUrl | String | 否 | 状态回执的回调地址 - 请传入完整带http协议头开头的地址，不传默认为空，请勿传入空格，否则会造成地址推送错误。 - 地址可通过接口入参传入，也可在控制台手动配置，可查看控制台操作指引。 |
"callbackUrl":"https://" |
| uid | String | 否 | 自定义参数 - 如订单号或短信发送记录流水号，状态回执会回传，最大支持256位。 |
"uid":"321abc" |
| extend | String | 否 | 下发短信号码扩展码 - 用于匹配上行回复，上行报告会回传。一般5位以内(只支持传数字)，不传默认为空。 |
"extend":"555" |
请求示例：
复制成功
{
"account":"N6000001",
"timestamp" :"1752143733",
"nonce": "x4zfk0y5foqwx6cbnw3bfmimy98abqs1",
"phoneNumbers":"17601337176,15100159057",
"templateId":"1021143438",
"templateParamJson":"[{\"param1\":\"张三\",\"param2\":\"13\"},{\"param1\":\"李四\",\"param2\":\"88\"}]",
"signature":"【创蓝云智】",
"report":"true",
"callbackUrl":"",
"uid":"test_001",
"extend":"01"
}
响应参数：
| 参数名称 | 类型 | 描述 | 示例 |
|---|---|---|---|
| code | String | 提交响应状态码，返回“0”表示提交成功（其他错误请参考提交响应码） | "code":"000000" |
| msgId | String | 消息 id（32 位纯数字） | "msgId":"25071516453300902203000007708373" |
| time | String | 响应时间 | "time":"20251204162433" |
| successNum | String | 提交成功数量，参数校验失败时不返回 | "successNum":"1" |
| failNum | String | 提交失败数量，参数校验失败时不返回 | "failNum":"0" |
| errorMsg | String | 提交响应状态码中文说明（提交成功返回空） | "errorMsg":"" |
响应示例：
复制成功
{
"code": "000000",
"failNum": "0",
"successNum": "2",
"msgId": "25071018345400902898000000000001",
"time": "20250710183454",
"errorMsg": ""
}
提交响应码说明
| 状态码 | 描述 | 问题处理人 |
|---|---|---|
| 000000 | 提交成功 | 无 |
| 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 | 超出安全发送时间（时间戳过期，时间戳时间跟请求接口的时间差异控制在30s以内） | 技术支持 |
| 140 | 短信内容解密错误（秘钥没有使用正确） | 技术支持 |
| 144 | 产品未上线限制日发送数量（签名报备选择的未上线会日限100条，联系客服调整） | 客服 |
| 145 | 验签失败（验签不过，请参考对应接口的DEMO加签代码示例） | 技术支持 |
| 152 | MATERIAL_EXIST_ERROR （模板不存在） | 客服 |
| 153 | MESSAGE_LY_ERROR 消息长度错（>2000或者≤0） | 技术支持 |
| 154 | 长短信拼接错误 | 技术支持 |
| 155 | AIM_SEND_FAIL 转发失败 | 技术支持 |
| 158 | 退订语不符合规范，退订语现在只支持“拒收请回复R”。 | 技术支持 |
| 159 | 触发反轰炸策略 | 技术支持 |