接收上行短信API_消息&短信 MSGSMS_API参考_华为云

(1)

API 参考

文档版本 13

发布日期 2022-01-24

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

华为技术有限公司

地址：深圳市龙岗区坂田华为总部办公楼邮编：518129 网址：

https://www.huawei.com

客户服务邮箱：

[email protected]

客户服务电话：4008302118

(3)

1 ^概述

欢迎使用消息&短信服务（Message&SMS）。消息&短信是华为云携手全球多家优质运营商和渠道，为企业用户提供的通信服务。企业调用API或使用群发助手，即可使用验证码、通知短信服务。

本文档提供了消息&短信API的描述、参数说明及示例等内容。支持的全部操作请参见 API接口使用说明。

在调用API之前，请确保已经充分了解消息&短信相关概念，详细信息请参见消息&短信“产品介绍”。

(5)

2 短信 API 使用说明

API 列表

发送短信接收状态报告接收上行短信

● 3 发送短信API：向单 个或多个用户发送相同内容的短信

● 4 发送分批短信API：

向多个用户发送不同内容的短信

5 接收状态报告API：用于

接收短信发送状态报告 6 接收上行短信API：用于 接收用户回复的短信

API 请求地址

API请求地址不区分区域、省份，中国站-短信服务使用同一地址。API请求地址由

“APP接入地址”和“访问URI”组成，数据来源如下：

参数来源示例

APP接入地址登录管理控制台，从国内短信

“应用管理”或国际/港澳台短信“应用管理”页面获取。

https://smsapi.cn-

north-4.myhuaweicloud.com:

443 访问URI 从3 发送短信API/4 发送分批短

信API页面中的“接口类型”介

绍部分获取。

发送短信：/sms/

batchSendSms/v1 发送分批短信：/sms/

batchSendDiffSms/v1

综上，API请求地址示例如下：

● 发送短信

https://smsapi.cn-north-4.myhuaweicloud.com:443/sms/batchSendSms/v1

● 发送分批短信

https://smsapi.cn-north-4.myhuaweicloud.com:443/sms/batchSendDiffSms/v1

(6)

API 样例

下载Demo，快速开发应用：

● Java

● PHP

● Python

● C#

● Node.js

● Go

(7)

3 ^{发送短信 API}

接口功能

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

使用说明

● 前提条件

a. 已创建短信应用，获取APP_Key、APP_Secret和APP接入地址（国际短信还需获取通道号）。

b. （仅国内短信）已申请短信签名，获取签名通道号。

c. 已申请短信模板，获取模板ID。

● 注意事项

a. 群发短信时，如果“to”参数携带的号码中包含除数字和+之外的其他字符，

则无法向该参数携带的所有号码发送短信。如果“to”参数携带的所有号码只包含数字和+，但部分号码不符合号码规则要求，则在响应消息中会通过状态码标识发送失败的号码，不影响其他正常号码的短信发送。号码之间以英文逗号分隔，每个号码最大长度为21位，最多允许携带1000个号码。如果携带超过1000个号码，则全部号码都会发送失败。

b. 根据短信内容的长度，一条长短信可能会被拆分为多条短信发送，拆分规则详见短信发送规则。

c. 通过X-WSSE方式鉴权时，生成随机数的时间不能与发送请求时的本地时间相差太大（具体差值请与管理员确认），否则会导致鉴权失败。

d. 请求body中的参数需要进行urlencode。

接口类型

表3-1 接口类型说明 请求方

法 POST

访问URI /sms/batchSendSms/v1

(8)

通信协

议 HTTPS

请求参数

表3-2 请求 Headers 参数 参数名称是否

必选参数类型默认值说明 Content-

Type 是 String 无固定填application/x-www-form- urlencoded。

Authoriza

tion 是 String 无取值为WSSE

realm="SDP",profile="UsernameToken",ty pe="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位，可包含数字和大小写字母。例如：

66C92B11FF8A425FB8D4CCFE0ED9ED1 F。

● Created：随机数生成时间。采用标准 UTC格式，例如：

2018-02-12T15:30:20Z。不同编程语言中的时间格式转换方式不同，部分语言可参考表3-3。

表3-3 不同编程语言的时间格式

编程语言时间格式

Java yyyy-MM-dd'T'HH:mm:ss'Z' PHP Y-m-d\TH:i:s\Z

(9)

Python %Y-%m-%dT%H:%M:%SZ C# yyyy-MM-ddTHH:mm:ssZ

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

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

Go 2006-01-02T15:04:05Z

表3-4 请求 Body 参数说明 参数名称是否

必选

参数类型默认值

说明

from 是 String(1-2

1) 无短信发送方的号码。

● 国内短信填写为短信平台为短信签名分配的通道号码，请在申请短信签名时获取签名通道号，如：csms100000001，

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

● 国际/港澳台短信填写为创建短信应用时分配的通道号，如：isms100000001。

请在短信控制台“国内短信>签名管理”内查看签名的通道号，签名和模板为对应关系，模板所属签名可在“国内短信>模板管理”查看。

to 是 String(1-2

1999) 无短信接收方的号码，标准号码格式为：+{国家码}{地区码}{终端号码}。

● 发送国内短信，如果“+{国家码}”不存在，则默认为+86，如果接收方号码为手机号码，则{地区码}可选。如：

+86131****5678。

● 发送国际/港澳台短信：不区分接收号码类型，所填号码都必须符合标准号码格式。示例：+2412****00（加蓬号码）

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

(10)

参数名称是否必选

说明

templateI

d 是 String(1-3

2) 无短信模板ID，用于唯一标识短信模板，请在

申请短信模板时获取模板ID。

“templateId”需要与“templateParas”

参数配合使用。

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

请在短信控制台“国内短信>模板管理”内查看模板的模板ID。

template

Paras 否 String[] 无 ^说明

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

短信模板的变量值列表，用于依次填充

“templateId”参数指定的模板内容中的变量，该参数需填写为JSONArray格式。请参考模板和变量规范。

列表中变量值的个数及长度必须和

“templateId”对应模板内容中定义的变量个数及长度保持一致，例如“templateId”

对应的模板内容有2个变量且变量长度分别为5和6，则此处需要设置2个变量值且内容长度分别小于等于5和6。

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

statusCall

back 否 String(1-1

024) 无客户的回调地址，用于接收短信状态报告，

如：http://my.com/receiveSMSReport。

● 如果设置了该字段，则该消息的状态报告将通过“接收状态报告”接口直接通知客户。

● 如果未设置该字段，则短信平台收到运营商短信中心返回的状态报告不会推送给客户，该状态报告将在短信平台中保存1个小时，超时后系统会自动删除。

● 回调地址推荐使用域名。

extend 否 String(1-1

28) 无扩展参数，在状态报告中会原样返回。

不允许赋空值，不允许携带以下字符：

“{”，“}”（即大括号）。

signature 否 String(0-3

2) 无签名名称，必须是已审核通过的，与模板类

型一致的签名名称。

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

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

(11)

响应参数

表3-5 响应结果参数 参数名称是否

必选

说明

code 是 String(1-7

) 无请求返回的结果码。

descriptio

n 是 String(1-5

12) 无请求返回的结果码描述。

result 否 SmsID[1-

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

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

表3-6 SmsID 定义 参数名称是否必选

说明

smsMsgId 是 String(1-5

0) 无短信的唯一标识。

from 是 String(1-2

originTo 是 String(1-2

1) 无短信接收方的号码。

status 是 String(1-7

) 无短信状态码，请参考API错误码。

● 000000：短信平台处理请求成功

● E200015：待发送短信数量太大

● E200028：模板变量校验失败

● E200029：模板类型校验失败

● E200030：模板未激活

● E200031：协议校验失败

● E200033：模板类型不正确

● E200041：同一短信内容接收号码重复 createTim

e 是 String(1-2

0) 无短信资源的创建时间，即短信平台接收到客

户发送短信请求的时间，为UTC时间。

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

(12)

结果码说明

表3-7 响应结果码 响应

码

结果码

英文描述中文描述处理方法

200 0000

00 Success. 发送请求成功。无需处理。

400 E000

000 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 UsernameTok en.

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

请检查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。

(13)

响应码

结果码

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 PasswordDige st not

contained in X-WSSE.

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

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

E000025 The format of Created is incorrect.

Created属性格

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

E000026 UsernameTok en not

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

请检查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确认发送失败的原因，修改后重新发送。

(14)

响应码

结果码

E000623 Number of SMSs sent by the SP reached the limit.

SP短信发送量达

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

401 E000

101 Authenticatio

n failed. 鉴权失败。请检查Authorization和X-WSSE 参数的填写是否正确。

E000102 Invalid

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

如app_key填写正确，建议检查 app接入地址是否正确（从控制台“应用管理”获取）。

E000103 The status of the app_key is unavailable.

app_key不可

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

E000104 Invalid

app_secret. app_secret无

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

E000105 Invalid digest. PasswordDigest 无效。

请检查请求携带的

PasswordDigest填写是否正确。

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 Incorrect username or password.

用户名或密码错

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

E000112 The subscriber status is frozen.

用户状态已冻结。

请联系管理员解冻用户。

403 E000

620 The app client ip is not in ip white list.

对端app IP不在

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

(15)

接口示例

● 请求示例

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="NDA1MWIwNjI2ZTkyNWFlM2FhM TE5NDE1YTk5NjU1YWE4NjNlZTY1MmRhYzkxZGViNzczZjdjMjkzZWQ4ZjAwNA==",Nonce="ac1c911c47 92492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"

accept: application/json

content-type: application/x-www-form-urlencoded from=1069********0012&to=

%2B86155****5678&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":"+86155****5678","createTime":"2018-05-25T16:34:34Z","from":"1069********0012","smsMs gId":"d6e3cdd0-522b-4692-8304-

a07553cdf591_8539659","status":"000000"}],"code":"000000","description":"Success"}

语音通话

隐私保护通话

(16)

4 发送分批短信 API

接口功能

该接口用于客户请求短信平台向不同用户发送不同的短信。

使用说明

● 前提条件

a. 已创建短信应用，获取APP_Key、APP_Secret和APP接入地址（国际短信还需获取通道号）。

b. （仅国内短信）已申请短信签名，获取签名通道号。

c. 已申请短信模板，获取模板ID。

● 注意事项

a. 单条短信最多允许携带1000个号码，号码之间以英文逗号分隔，每个号码最大长度为21位。如果单条短信携带超过1000个号码，则该单条短信全部号码都会发送失败。

b. 通过X-WSSE方式鉴权时，生成随机数的时间不能与发送请求时的本地时间相差太大（具体差值请与管理员确认），否则会导致鉴权失败。

接口类型

法 POST

访问URI /sms/batchSendDiffSms/v1

通信协

议 HTTPS

(17)

请求参数

必选

说明

Content-

Type 是 String 无固定填application/json。

Authoriza

tion 是 String 无取值为WSSE

realm="SDP",profile="UsernameToken",ty pe="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位，可包含数字和大小写字母。例如：

66C92B11FF8A425FB8D4CCFE0ED9ED1 F。

● Created：随机数生成时间。采用标准 UTC格式，例如：

2018-02-12T15:30:20Z。不同编程语言中的时间格式转换方式不同，部分语言可参考表4-3。

表4-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

(18)

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

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

Go 2006-01-02T15:04:05Z

必选

说明

from 是 String(1-2

● 国内短信填写为短信平台为短信签名分配的通道号码，请在申请短信签名时获取签名通道号，如：csms100000001，且通道号码对应的签名类型和模板ID对应的模板类型必须相同。

● 国际/港澳台短信填写为创建短信应用时分配的通道号，如：isms100000001。

请在短信控制台“国内短信>签名管理”内查看签名的通道号，签名和模板为对应关系，模板所属签名可在“国内短信>模板管理”查看。

statusCall

back 否 String(1-1

024) 无客户的回调地址，用于接收短信状态报告，

如：http://my.com/receiveSMSReport。

● 如果设置了该字段，则该消息的状态报告将通过“接收状态报告”接口直接通知客户。

● 如果未设置该字段，则短信平台收到运营商短信中心返回的状态报告不会推送给客户，该状态报告将在短信平台中保存1个小时，超时后系统会自动删除。

● 回调地址推荐使用域名。

smsConte

nt 是 SmsCont

ent[] 无发送的通知短信内容，短信内容不能超过

64KB。

28) 无扩展参数，在状态报告中会原样返回。

不允许赋空值，不允许携带以下字符：

“{”，“}”（即大括号）。

(19)

表4-5 SmsContent 定义 参数名

称

是否必选

说明

to 是 String[]

(1-21999 )

无群发短信接收方的号码，标准号码格式为：+

{国家码}{地区码}{终端号码}。

● 发送国内短信，如果“+{国家码}”不存在，则默认为+86，如果接收方号码为手机号码，则{地区码}可选。如：

+86131****5678。

● 发送国际/港澳台短信：不区分接收号码类型，所填号码都必须符合标准号码格式。

示例：+2412****00（加蓬号码）

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

templat

eId 是 String(1-

32) 无短信模板ID，用于唯一标识短信模板，请在申

请短信模板时获取模板ID。

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

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

请在短信控制台“国内短信>模板管理”内查看模板的模板ID。

templat

eParas 否 String[] 无注：当使用无变量模板时，可不带 templateParas参数。

短信模板的变量值列表，用于依次填充

“templateId”参数指定的模板内容中的变量，该参数需填写为JSONArray格式。请参考

模板和变量规范。

列表中变量值的个数及长度必须和

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

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

"]。

signatur

e 否 String(0-

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

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

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

(20)

响应参数

表4-6 响应结果参数 参数名称是否

必选

说明

code 是 String(1-7

) 无请求返回的结果码。

descriptio

n 是 String(1-5

12) 无请求返回的结果码描述。

result 否 SmsID[] 无短信结构体，当返回响应出现异常时不包含此字段。

表4-7 SmsID 定义 参数名称是否必选

说明

0) 无短信的唯一标识。

from 是 String(1-2

originTo 是 String(1-2

1) 无短信接收方的号码。

) 无短信状态码，请参考API错误码。

● 000000：短信平台处理请求成功

● E200015：待发送短信数量太大

● E200028：模板变量校验失败

● E200029：模板类型校验失败

● E200030：模板未激活

● E200031：协议校验失败

● E200033：模板类型不正确

● E200041：同一短信内容接收号码重复 createTim

e 是 String(1-2

0) 无短信资源的创建时间，即短信平台接收到客

户发送短信请求的时间，为UTC时间。

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

(21)

结果码说明

表4-8 响应结果码 响应

码

结果码

200 0000

00 Success. 发送请求成功。无需处理。

400 E000

000 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 UsernameTok en.

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

请检查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。

(22)

响应码

结果码

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 PasswordDige st not

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

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

E000025 The format of Created is incorrect.

Created属性格

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

E000026 UsernameTok en not

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

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

E000027 Invalid

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

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短信发送量最大限额。

(23)

响应码

结果码

401 E000

101 Authenticatio

n failed. 鉴权失败。请检查Authorization和X-WSSE 参数的填写是否正确。

E000102 Invalid

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

如app_key填写正确，建议检查 app接入地址是否正确（从控制台“应用管理”获取）。

E000103 The status of the app_key is unavailable.

app_key不可

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

E000104 Invalid

app_secret. app_secret无效。

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

E000105 Invalid digest. PasswordDigest 无效。

请检查请求携带的

PasswordDigest填写是否正确。

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 Incorrect username or password.

用户名或密码错误。

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

E000112 The subscriber status is frozen.

用户状态已冻结。

请联系管理员解冻用户。

403 E000

620 The app client ip is not in ip white list.

对端app IP不在

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

接口示例

● 请求示例

POST /sms/batchSendDiffSms/v1 HTTP/1.1 x-real-ip: 10.10.10.168

(24)

x-real-port: 10443 host: ompap.inner content-length: 315

date: Fri, 13 Apr 2018 06:48:35 GMT

authorization: WSSE realm="SDP",profile="UsernameToken",type="Appkey"

x-wsse: UsernameToken

Username="ZRBRz4bAXoFgEH7o4Ew308eXc1RA",PasswordDigest="NDA1MWIwNjI2ZTkyNWFlM2FhM TE5NDE1YTk5NjU1YWE4NjNlZTY1MmRhYzkxZGViNzczZjdjMjkzZWQ4ZjAwNA==",Nonce="ac1c911c47 92492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"

accept: application/json content-type: application/json

{"from":"1069********0012","smsContent":[{"to":

["+86155****5678","+86155****5679"],"templateId":"abcdefghabcdefghabcdefghabcdefgh","templatePa ras":["062569"]},{"to":

["+86155****45680"],"templateId":"hgfedcbahgfedcbahgfedcbahgfedcba","templateParas":

["605623"]}],"statusCallback":"http://205.145.111.168:9330/report"}

● 响应示例

HTTP/1.1 200 OK

Date: Fri, 13 Apr 2018 06:46:04 GMT Server: WebServer

Content-Type: application/json;charset=UTF-8 Content-Length: 541

{"result":

[{"originTo":"+86155****5678","createTime":"2018-05-25T16:34:34Z","from":"1069********0012","smsMs gId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_52","status":"000000"},

{"originTo":"+86155****5679","createTime":"2018-05-25T16:34:34Z","from":"1069********0012","smsMsg Id":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_53","status":"000000"},

{"originTo":"+86155****5680","createTime":"2018-05-25T16:34:34Z","from":"1069********0012","smsMsg Id":"5963c5be-f189-4c0c-

ab2e-7cab0c42c798_54","status":"000000"}],"code":"000000","description":"Success"}

语音通话

隐私保护通话

(25)

5 接收状态报告 API

接口功能

该接口用于客户接收短信平台主动发送的短信状态报告，状态报告中的回调地址在

“发送短信”与“发送分批短信”接口中的“statusCallback”字段中设置。

说明

● 若“statusCallback”字段已设置，则使用该字段的取值作为短信状态报告的回调地址。

● 若“statusCallback”字段未设置，则客户无法接收短信平台主动发送的状态报告。

使用说明

● 前提条件

客户对短信平台推送的状态报告免鉴权。

客户服务器若有IP白名单配置，请联系运营经理获取短信平台IP地址并加入白名单。

● 注意事项

短信平台发送短信成功后，最多72小时会推送状态报告给客户。

接口类型

法 POST

访问URI “发送消息”、“发送分批短信”接口中指定的客户回调地址。

通信协议

HTTPS

(26)

请求参数

必选

说明

Content-

必选

说明

0) 无发送短信成功时返回的短信唯一标识。

total 否 String(1-2

) 无长短信拆分后的短信条数。

当短信未拆分时该参数取值为1。

sequence 否 String(1-2

) 无长短信拆分后的短信序号，当total参数取值大于1时，该参数才有效。

当短信未拆分时该参数取值为1。

) 无短信状态报告枚举值，常见取值请参考表

5-4，处理方法请参考状态报告错误码。

source 否 String(枚

举) 无短信状态报告来源：

● 1：短信平台自行产生的状态报告。

● 2：短信中心返回的状态报告。

● 3：短信安全管控产生的状态报告。

updateTi

me 否 String(1-2

0) 无短信资源的更新时间，通常为短信平台接收

短信状态报告的时间，为UTC时间，格式为：yyyy-MM-dd'T'HH:mm:ss'Z'，该时间会通过urlencode转义为%3a。

当短信平台未收到短信中心上报的状态报告时，会自行构造状态报告，该状态报告中不携带“updateTime”参数。

orgCode 否 String(1-7

) 无透传南向网元状态码，仅国际/港澳台短信状

态报告携带，国内短信不涉及。

当南向网元未返回状态码时不携带该参数。

28) 无扩展字段，由客户在发送短信的请求中携带。若客户发送短信时未携带extend参数，

则状态报告中也不会携带extend参数。

(27)

参数名称是否必选

说明

to 否 String(1-2

1) 无本条状态报告对应的短信的接收方号码，仅

当状态报告中携带了extend参数时才会同时携带该参数。

表5-4 status 常见取值

取值含义

DELIVRD 用户已成功收到短信。

EXPIRED 短信已超时。

DELETED 短信已删除。

UNDELIV 短信递送失败。

ACCEPTD 短信已接收。

UNKNOWN 短信状态未知。

REJECTD 短信被拒绝。

E200018 国内短信发送方通道校验失败。

E200019 国内短信发送方匹配通道失败。

E200020 国内短信签名通道校验失败。

E200021 国内短信签名匹配通道失败。

E200022 国内短信接收方通道校验失败。

E200023 国内短信接收方匹配通道失败。

E200024 没有国际短信能力。

E200025 国际短信接收方通道校验失败。

E200026 国际短信接收方匹配通道失败。

E200027 匹配网关失败。

E200032 短信需要模板。

E200034 短信重传超时。

E200035 短信协议字段替换失败。

E200036 南向速率管控配置为0。

E200038 接收长短信超时。

MILIMIT 号码达到分钟下发限制。

(28)

取值含义

LIMIT 号码达到下发限制。

BEYONDN

KEYWORD 短信关键字拦截。

BLACK 号码黑名单。

MBBLACK

DJ:0255 运营商拦截，一般是因为短信内容不允许发送。

1 此类错误码多为手机号码问题，如手机为空号，关机，停

24 机等。

MK:xxxx MN:xxxx LT:0001

MA:xxxx SMSC未返回响应消息。

MB:xxxx SMSC返回错误响应消息。

MC:xxxx 未从SMSC处接收到状态报告。

CA:xxxx SCP未返回响应消息。

CB:xxxx SCP返回错误响应消息。

DA:xxxx DSMP未返回响应消息。

DB:xxxx DSMP返回错误响应消息。

SA:xxxx SP未返回响应消息。

SB:xxxx SP返回错误响应消息。

IA:xxxx 下一级ISMG未返回响应消息。

IB:xxxx 下一级ISMG返回错误响应消息。

IC:xxxx 没有从下一级ISMG处接收到状态报告。

SC:0001 人工审核拦截

SC:0002 人工审核告警拦截

SC:0003 黑名单拦截

SC:0004 红名单拦截

SC:0005 投诉黑名单

SC:0006 禁用关键字拦截

SC:0007 特征关键字拦截

(29)

取值含义

SC:0008 管控关键字拦截

SC:0009 缺失必备关键字

SC:0010 短信超频拦截

SC:0011 时段管控拦截

SC:0012 人工审核超时处理

SC:0013 签名黑名单拦截

SC:0014 免审核模板匹配

SC:0015 拦截模板匹配

SC:0016 退订黑名单拦截

SC:0017 非报备模板拦截

SC:0018 非报备签名拦截

响应参数

客户可以返回任意响应消息给短信平台，短信平台不会对响应消息处理。

接口示例

● 请求示例

POST /report HTTP/1.1 Host: 205.145.111.168:9330

Content-Type: application/x-www-form-urlencoded Connection: close

Pooltype: approxy

Ompsid: 7f540777fe4b40dfb3c21d10f48781e3 TerminalIP: ******

TrcModule: AP UserTrace: application TraceHandle: DMZ_818405

sequence=1&total=1&orgCode=000&updateTime=2018-04-13T06%3A31%3A46Z&source=2&smsMsgId

=b9d9b4fe-ad0e-4a2a-a2c7-445505b674ac_6&status=DELIVRD

● 响应示例

HTTP/1.1 200 OK

Date: Fri, 13 Apr 2018 06:31:45 GMT

Content-Type: application/JSON; charset=UTF-8 Content-Length: 43

{"returnCode":0,"returnCodeDesc":"Success"}

(30)

语音通话

隐私保护通话

(31)

6 接收上行短信 API

接口功能

该接口用于客户接收短信平台主动发送的上行短信通知，接收该通知的上行短信接收地址在创建短信应用时配置。

注：国际/港澳台短信暂不支持上行短信功能。

使用说明

前提条件

已在创建短信应用时填写上行短信接收地址。

客户服务器若有IP白名单配置，请联系运营经理获取短信平台IP地址并加入白名单。

接口类型

法

POST

访问URI 客户接收上行短信的地址。

通信协议

HTTPS

(32)

请求参数

必选

说明

Content-

必选

说明

0) 无上行短信的唯一标识。

from 是 String(1-2

1) 无上行短信发送方的号码。

to 是 String[]

(1-21) 无上行短信接收方的号码。

body 是 String(1-1

60) 无上行短信发送的内容。

响应参数

客户可以返回任意响应消息给短信平台，短信平台不会对响应消息处理。

接口示例

● 请求示例

POST /smsRecive HTTP/1.1 Host: 205.145.111.168:9330

Content-Type: application/x-www-form-urlencoded Connection: close

Pooltype: approxy

Ompsid: 56514cc1880e40638f16c7c674265658 TerminalIP: 205.141.112.17

TrcModule: AP UserTrace: application TraceHandle: DMZ_818405

from=%2B86155****5172&to=201804131431201234&body=********&smsMsgId=9692b5be- c427-4525-8e73-cf4a6ac5b3f7

● 响应示例

HTTP/1.1 200 OK

Date: Fri, 13 Apr 2018 06:31:48 GMT

Content-Type: application/JSON; charset=UTF-8 Content-Length: 43

{"returnCode":0,"returnCodeDesc":"Success"}

(33)

状态回执错误码

语音通话

隐私保护通话

(34)

7 ^{文档修订记录}

发布日期更新内容

2019/10/16 发送短信API/发送分批短信API：响应参数status新增取值 E200041。

接收状态报告API：请求参数status和orgCode状态码归一。具体变更如下：

● 请求参数status删除取值RTE_ERR。

● 请求参数orgCode取值合入status。其中，请求参数status 新增取值E200018-E200027、E200032、E200034- E200036、E200038，删除原orgCode参数取值E200040、

E200041、E200042、E200045。

● 请求参数orgCode仅在国际/港澳台短信状态报告中携带，

用于透传南向网元状态码。国内短信不涉及。

2019/09/05 接收状态报告API：请求参数status新增取值SC:0016-SC:

0018。

2019/06/30 发送短信API/发送分批短信API：结果码E200037变更为 E000510。

接收状态报告API：请求参数status新增取值SC:0013-SC:

0015。

2019/03/30 接收状态报告API：

● 请求参数source新增取值3。

● 请求参数status新增取值SC:0001-SC:0012。

2019/01/18 接收状态报告API：请求参数orgCode新增取值E200040、

E200041、E200042、E200045。

2018/12/24 发送短信API/发送分批短信API：新增请求参数signature，对应通用模板功能。

2018/09/30 发送短信API/发送分批短信API：新增结果码E200037。

接收状态报告API：请求参数orgCode新增取值E200038。

(35)

发布日期更新内容

2018/08/17 发送短信API/发送分批短信API：

● 新增请求参数extend。

● 响应参数status新增取值E200031。

● 新增结果码E000027。

接收状态报告API：

● 新增请求参数extend、to。

● 请求参数orgCode新增取值E200034、E200035、

E200036。

接收上行短信API_消息&短信 MSGSMS_API参考_华为云

API 参考

华为技术有限公司

https://www.huawei.com

[email protected]

目 录

1 概述...1

2 短信 API 使用说明... 2

3 发送短信 API...4

4 发送分批短信 API...13

5 接收状态报告 API...22

6 接收上行短信 API...28

7 文档修订记录...31

1 概述

2 短信 API 使用说明

API 列表

API 请求地址

信API页面中的“接口类型”介

API 样例

3 发送短信 API

接口功能

使用说明

接口类型

请求参数

申请短信模板时获取模板ID。

响应参数

结果码说明

接口示例

相关推荐

语音通话

隐私保护通话

4 发送分批短信 API

接口功能

使用说明

接口类型

请求参数

请短信模板时获取模板ID。

模板和变量规范。

响应参数

结果码说明

接口示例

相关推荐

语音通话

隐私保护通话

5 接收状态报告 API

接口功能

使用说明

接口类型

请求参数

响应参数

接口示例

相关推荐

语音通话

隐私保护通话

6 接收上行短信 API

接口功能

使用说明

接口类型

请求参数

响应参数

接口示例

相关推荐

状态回执错误码

语音通话

隐私保护通话

7 文档修订记录

目录

1 ^概述

3 ^{发送短信 API}

7 ^{文档修订记录}