文档首页 > > API参考> 发送短信API

发送短信API

分享
更新时间: 2019/09/11 GMT+08:00

接口功能

该接口用于客户请求短信业务平台向指定用户发送短信。

使用说明

  • 前提条件
    1. 创建短信应用,获取APP_Key、APP_Secret和APP接入地址(国际短信还需获取通道号)。
    2. (仅国内短信)已申请短信签名,获取签名通道号。
    3. 申请短信模板,获取模板ID。
  • 注意事项
    1. 群发短信时,如果“to”参数携带的号码中包含除数字和+之外的其他字符,则无法向该参数携带的所有号码发送短信。如果“to”参数携带的所有号码只包含数字和+,但部分号码不符合号码规则要求,则在响应消息中会通过状态码标识发送失败的号码,不影响其他正常号码的短信发送。号码之间以英文逗号分隔,每个号码最大长度为21位,最多允许携带1000个号码。如果携带超过1000个号码,则全部号码都会发送失败。
    2. 根据短信内容的长度,一条长短信可能会被拆分为多条短信发送,拆分规则详见短信发送规则
    3. 通过X-WSSE方式鉴权时,生成随机数的时间不能与发送请求时的本地时间相差太大(具体差值请与管理员确认),否则会导致鉴权失败。
    4. 请求body中的参数需要进行urlencode。

接口类型

表1 接口类型说明

请求方法

POST

访问URI

/sms/batchSendSms/v1

通信协议

HTTPS

请求参数

表2 请求Headers参数

参数名称

是否必选

参数类型

默认值

说明

Content-Type

String

固定填application/x-www-form-urlencoded。

Authorization

String

取值为WSSE realm="SDP",profile="UsernameToken",type="Appkey"。

X-WSSE

String

取值为UsernameToken Username="app_key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
  • PasswordDigest:根据PasswordDigest = Base64 (SHA256 (Nonce + Created + Password))生成,直接使用Nonce、Created、Password拼接后的字符串进行SHA256加密即可,字符串中无需包含+号和空格。其中,Password为app_secret的值。
  • Nonce:客户发送请求时生成的一个随机数,长度为1~128位,可包含数字和大小写字母。例如:66C92B11FF8A425FB8D4CCFE0ED9ED1F。
  • Created:随机数生成时间。采用标准UTC格式,例如:2018-02-12T15:30:20Z。不同编程语言中的时间格式转换方式不同,部分语言可参考表3
表3 不同编程语言的时间格式

编程语言

时间格式

Java

yyyy-MM-dd'T'HH:mm:ss'Z'

PHP

Y-m-d\TH:i:s\Z

Python

%Y-%m-%dT%H:%M:%SZ

C#

yyyy-MM-ddTHH:mm:ssZ

Node.js

toISOString().replace(/.[0-9]+\Z/, 'Z')

注:Node.js中,使用toISOString()转换后的时间格式去除毫秒后即为本接口要求的时间格式。

表4 请求Body参数说明

参数名称

是否必选

参数类型

默认值

说明

from

String(1-21)

短信发送方的号码。

  • 国内短信填写为短信平台为短信签名分配的通道号码,请在申请短信签名时获取签名通道号,如:csms100000001,且通道号码对应的签名类型和模板ID对应的模板类型必须相同。
  • 国际/港澳台短信填写为创建短信应用时分配的通道号,如:csms100000001。

to

String(1-21999)

短信接收方的号码,号码格式为:+{国家码}{地区码}{终端号码},当接收方号码为手机号码时,{地区码}可选,如:+8613112345678。

如果“+{国家码}”不存在,则默认国家码为+86,如:13112345678。

如果携带多个接收方号码,则以英文逗号分隔。每个号码最大长度为21位,最多允许携带1000个号码。

templateId

String(1-32)

短信模板ID,用于唯一标识短信模板,请在申请短信模板时获取模板ID。

“templateId”需要与“templateParas”参数配合使用。

国内短信通道号码对应的签名类型和模板ID对应的模板类型必须相同。

templateParas

String[]

注:当使用无变量模板时,可不带templateParas参数。

短信模板的变量值列表,用于依次填充“templateId”参数指定的模板内容中的变量,该参数需填写为JSONArray格式。请参考模板和变量规范

列表中变量值的个数及长度必须和“templateId”对应模板内容中定义的变量个数及长度保持一致,例如“templateId”对应的模板内容有2个变量且变量长度分别为5和6,则此处需要设置2个变量值且内容长度分别小于等于5和6。

如模板内容为“您有${NUM_2}件快递请到${TXT_32}领取”时,该参数可填写为["3","人民公园正门"]。

statusCallback

String(1-1024)

客户的回调地址,用于接收短信状态报告,如:http://my.com/receiveSMSReport。

  • 如果设置了该字段,则该消息的状态报告将通过“接收状态报告”接口直接通知客户。
  • 如果未设置该字段,则短信平台收到运营商短信中心返回的状态报告不会推送给客户,该状态报告将在短信平台中保存1个小时,超时后系统会自动删除。
  • 回调地址推荐使用域名。

extend

String(1-128)

扩展参数,在状态报告中会原样返回。

不允许携带以下字符:“{”,“}”(即大括号)。

signature

String(0-32)

签名名称,必须是已审核通过的,与模板类型一致的签名名称。

仅在templateId指定的模板类型为通用模板时生效且必填,用于指定在通用模板短信内容前面补充的签名。

国际/港澳台短信无需关注此参数。

响应参数

表5 响应结果参数

参数名称

是否必选

参数类型

默认值

说明

code

String(1-7)

请求返回的结果码。

description

String(1-512)

请求返回的结果码描述。

result

SmsID[1-1000]

短信ID列表,当目的号码存在多个时,每个号码都会返回一个SmsID。

当返回异常响应时不携带此字段。

表6 SmsID定义

参数名称

是否必选

参数类型

默认值

说明

smsMsgId

String(1-50)

短信的唯一标识。

from

String(1-21)

短信发送方的号码。

originTo

String(1-21)

短信接收方的号码。

status

String(1-7)

短信状态码,请参考API错误码

  • 000000:短信平台处理请求成功
  • E200015:待发送短信数量太大
  • E200028:模板变量校验失败
  • E200029:模板类型校验失败
  • E200030:模板未激活
  • E200031:协议校验失败
  • E200033:模板类型不正确

createTime

String(1-20)

短信资源的创建时间,即短信平台接收到客户发送短信请求的时间,为UTC时间。

格式为:yyyy-MM-dd'T'HH:mm:ss'Z'。

结果码说明

表7 响应结果码

响应码

结果码

英文描述

中文描述

处理方法

200

000000

Success.

发送请求成功。

无需处理。

400

E000000

System error.

系统异常。

请先对照代码样例检查templateParas参数设置是否正确。若排查代码后仍未解决问题,请联系管理员处理。

E000001

Authorization not contained in the HTTP header.

HTTP消息头未找到Authorization字段。

请检查HTTP消息头中是否携带了Authorization字段。

E000002

realm not contained in Authorization.

Authorization字段中未找到realm属性。

请检查Authorization字段中的是否携带了realm属性。

E000003

profile not contained in Authorization.

Authorization字段中未找到profile属性。

请检查Authorization字段中的是否携带了profile属性。

E000004

The value of realm in Authorization must be SDP.

Authorization中realm属性值应该为“SDP”。

请检查Authorization字段中的realm属性值是否为“SDP”

E000005

The value of profile in Authorization must be UsernameToken.

Authorization中profile属性值应该为“UsernameToken”。

请检查Authorization字段中的profile属性值是否为“UsernameToken”

E000006

The value of type in Authorization must be app_key.

Authorization中type属性值应该为“Appkey”。

请检查Authorization字段中的type属性值是否为Appkey

E000007

type not contained in Authorization.

Authorization字段中未找到type属性。

请检查Authorization字段中是否携带了type属性。

E000008

WSSE not contained in Authorization.

Authorization中没有携带WSSE。

请检查Authorization字段中是否携带了WSSE。

E000020

X-WSSE not contained in the HTTP header.

HTTP头未找到X-WSSE字段。

请检查HTTP消息头中是否携带了X-WSSE字段。

E000021

UserName not contained in X-WSSE.

X-WSSE字段中未找到UserName属性。

请检查X-WSSE字段中的是否携带了UserName属性。

E000022

Nonce not contained in X-WSSE.

X-WSSE字段中未找到Nonce属性。

请检查X-WSSE字段中的是否携带了Nonce属性。

E000023

Created not contained in X-WSSE.

X-WSSE字段中未找到Created属性。

请检查X-WSSE字段中的是否携带了Created属性。

E000024

PasswordDigest not contained in X-WSSE.

X-WSSE字段中未找到PasswordDigest属性。

请检查X-WSSE字段中的是否携带了PasswordDigest属性。

E000025

The format of Created is incorrect.

Created属性格式错误。

请检查X-WSSE字段中的Created属性格式是否正确。

E000026

UsernameToken not contained in X-WSSE.

X-WSSE字段中未找到UsernameToken属性。

请检查X-WSSE字段中的是否携带了UsernameToken属性。

E000027

Invalid request.

非法请求。

根据API接口文档的参数描述和要求,检查请求携带的参数是否都合法。

E000040

The value of ContentType must be application/x-www-form-urlencoded.

ContentType值应该为application/x-www-form-urlencoded。

请检查ContentType头域的取值是否为“application/x-www-form-urlencoded”

E000503

The parameter format is incorrect.

参数格式错误。

请检查参数格式是否正确。

E000510

The SMS fails to be sent. For details, see status.

短信发送失败,描述见参数status。

查看响应参数中的status确认发送失败的原因,修改后重新发送。

E000623

Number of SMSs sent by the SP reached the limit.

SP短信发送量达到限额。

请联系运营经理协商调整SP短信发送量最大限额。

401

E000101

Authentication failed.

鉴权失败。

请检查Authorization和X-WSSE参数的填写是否正确。

E000102

Invalid app_key.

app_key无效。

请检查请求携带的app_key填写是否正确。

E000103

The status of the app_key is unavailable.

app_key不可用。

请联系管理员确认该app_key状态是否正常。

E000104

Invalid app_secret.

app_secret无效。

请检查请求携带的app_secret填写是否正确。

E000105

Invalid digest.

digest无效。

请检查请求携带的digest填写是否正确。

E000106

The app_key is not allowed to invoke this API.

app_key没有调用本API的权限。

请联系管理员确认该app_key是否具有“短信能力开放”能力。

E000109

The user status is deactivated.

用户状态未激活。

请联系管理员激活用户。

E000110

Time out limit.

时间超出限制。

请确认X-WSSE鉴权时,生成随机数的时间与发送请求时的本地时间不能相差太大(具体差值请与管理员确认)。

E000111

Inccorect username or password.

用户名或密码错误。

系统找不到app_key对应的用户信息,请联系管理员处理。

E000112

The subsriber status is frozen.

用户状态已冻结。

请联系管理员解冻用户。

403

E000620

The app client ip is not in ip white list.

对端app IP不在白名单列表中。

联系管理员检查IP白名单是否配置正确。

接口示例

  • 请求示例
    POST /sms/batchSendSms/v1 HTTP/1.1
    x-real-ip: 10.10.10.168 
    x-real-port: 10443 
    host: ompap.inner
    content-length: 184 
    date: Fri, 13 Apr 2018 06:31:39 GMT
    authorization: WSSE realm="SDP",profile="UsernameToken",type="Appkey"
    x-wsse: UsernameToken Username="ZRBRz4bAXoFgEH7o4Ew308eXc1RA",PasswordDigest="NDA1MWIwNjI2ZTkyNWFlM2FhMTE5NDE1YTk5NjU1YWE4NjNlZTY1MmRhYzkxZGViNzczZjdjMjkzZWQ4ZjAwNA==",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
    accept: application/json
    content-type: application/x-www-form-urlencoded
    
    from=1069031221280012&to=%2B8615512345678&templateId=abcdefghabcdefghabcdefghabcdefgh&templateParas=%5B%22520520%22%5D&statusCallback=http%3A%2F%2F205%2E145%2E111%2E168%3A9330%2Freport
  • 响应示例
    HTTP/1.1 200 OK
    Date: Fri, 13 Apr 2018 06:29:08 GMT
    Server: WebServer
    Content-Type: application/json;charset=UTF-8
    Content-Length: 220
    
    {"result":[{"originTo":"+8615512345678","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"d6e3cdd0-522b-4692-8304-a07553cdf591_8539659","status":"000000"}],"code":"000000","description":"Success"}

相关推荐

相关文档

相关产品

语音通话

隐私保护通话

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区