APIs - support.huaweicloud.com€¦ · The purchased products, services and features are stipulated...
Transcript of APIs - support.huaweicloud.com€¦ · The purchased products, services and features are stipulated...
Message & SMS
APIs
Issue 05
Date 2020-05-15
HUAWEI TECHNOLOGIES CO., LTD.
Copyright © Huawei Technologies Co., Ltd. 2020. All rights reserved.
No part of this document may be reproduced or transmitted in any form or by any means without priorwritten consent of Huawei Technologies Co., Ltd. Trademarks and Permissions
and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.All other trademarks and trade names mentioned in this document are the property of their respectiveholders. NoticeThe purchased products, services and features are stipulated by the contract made between Huawei andthe customer. All or part of the products, services and features described in this document may not bewithin the purchase scope or the usage scope. Unless otherwise specified in the contract, all statements,information, and recommendations in this document are provided "AS IS" without warranties, guaranteesor representations of any kind, either express or implied.
The information in this document is subject to change without notice. Every effort has been made in thepreparation of this document to ensure accuracy of the contents, but all statements, information, andrecommendations in this document do not constitute a warranty of any kind, express or implied.
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. i
Contents
1 SMS API Usage......................................................................................................................... 1
2 SMS Sending API......................................................................................................................3
3 Batch SMS Sending API........................................................................................................15
4 Status Report Receiving API............................................................................................... 27
5 Uplink SMS Receiving API................................................................................................... 34
Message & SMSAPIs Contents
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. ii
1 SMS API Usage
API ListSending Same SMSs inBatches
Receiving StatusReports
Receiving Uplink SMSs
● SMS Sending API:used to send SMSs ofthe same content toone or more users.
● Batch SMS SendingAPI: used to sendSMSs of differentcontents to differentusers.
Status Report ReceivingAPI: used to receive SMSsending status reports.
Uplink SMS ReceivingAPI: used to receiveSMSs replied by users.This API supports onlyChinese mainland SMSs.
API Request AddressThe API request address does not differentiate regions and provinces. The HUAWEICLOUD, international station, and SMS service use the same address. The APIrequest address consists of the Application Access Address and URI. The datasources are as follows:
Parameter Source Example
ApplicationAccessAddress
Log in to the Message&SMSconsole, and chooseInternational SMS >Application Management orchoose Chinese MainlandSMS > ApplicationManagement to open theApplication Managementpage.
https://rtcsms.ap-southeast-1.myhuaweicloud.com:443
Message & SMSAPIs 1 SMS API Usage
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 1
Parameter Source Example
URI Obtain the value from "APIType" in SMS Sending API orBatch SMS Sending API.
For SMS sending: /sms/batchSendSms/v1For batch SMS sending: /sms/batchSendDiffSms/v1
Two example API request addresses are as follows:
● For SMS sendinghttps://rtcsms.ap-southeast-1.myhuaweicloud.com:443/sms/batchSendSms/v1
● For batch SMS sendinghttps://rtcsms.ap-southeast-1.myhuaweicloud.com:443/sms/batchSendDiffSms/v1
API ExamplesDownload the following demos to quickly develop applications:
● Java● PHP● Python● C#● Node.js
Message & SMSAPIs 1 SMS API Usage
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 2
2 SMS Sending API
API FunctionThis API is used to have the SMS platform send SMSs to specified users.
Instructions● Prerequisites
a. An SMS application has been created. Application Key, ApplicationSecret, Application Access Address, and Channel No. (except thechannel No. of SMS in Chinese Mainland) have been obtained.
b. (Mandatory only for Chinese mainland) You have applied for an SMSsignature and obtained a channel No.
c. You have applied for an SMS template and obtained the template ID.● Notes
a. When an SMS is sent to a group of recipients, if the numbers in the toparameter contain characters other than digits and plus signs (+), theSMS cannot be sent to any of the numbers. If the to parameter includesonly numbers and plus signs (+) but some of the numbers are invalid forother reasons, status codes will be used to identify which numbers wereinvalid and cannot be sent to, but the SMSs sent to the remaining, validnumbers will be unaffected. For group SMSs, the numbers must beseparated by commas (,). Each number can include a maximum of 21characters. A maximum of 1,000 numbers are supported. If there aremore than 1,000 numbers, the SMS fails to be sent to any of thenumbers.
b. A long SMS may be split into multiple short messages with a fixedlength. For details about how an SMS is split, see SMS Sending Rules.
c. When X-WSSE authentication is used, there cannot be too muchdifference between the local time when the request is sent and the timewhen the random string was generated. Otherwise, the authenticationwill fail.
d. Parameters in the request body must be converted using urlencode.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 3
API Type
Table 2-1 API type
Method
POST
URI /sms/batchSendSms/v1
CommunicationsProtocol
HTTPS
Request Parameters
Table 2-2 Parameters in the request headers
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
Content-Type
Mandatory
String None
It has a fixed value of application/x-www-form-urlencoded.
Authorization
Mandatory
String None
The parameter value is WSSE realm toSDP, profile to UsernameToken, andtype to Appkey.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 4
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
X-WSSE Mandatory
String None
The parameter value is UsernameTokenUsername=Value of app_key,PasswordDigest=Value ofPasswordDigest, Nonce=Randomnumber, Created=Time when therandom number is generated.● PasswordDigest: The value of this
parameter is generated based onPasswordDigest = Base64 (SHA256(Nonce + Created + Password)). Thecharacter string consisting of Nonce,Created, and Password is used forSHA256 encryption. The string doesnot contain plus signs (+) or spaces.Password indicates the value ofapp_secret.
● Nonce: When a platform user sends arequest, a random, all-caps,alphanumeric string of 1-128characters is generated, for example,66C92B11FF8A425FB8D4CCFE0ED9ED1F.
● Created: The time when a randomcharacter string is generated. StandardUTC is used, for example,2018-02-12T15:30:20Z. The timeformat conversion mode used dependson the programming language. Fordetails, see Table 2-3.
Table 2-3 Time formats in different programming languages
ProgrammingLanguage
Time Format
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
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 5
ProgrammingLanguage
Time Format
Node.js toISOString().replace(/.[0-9]+\Z/, 'Z')Note: In Node.js, delete ms from the time format converted byusing toISOString().
Table 2-4 Parameters in the request body
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
from Mandatory
String(1-21)
None
The number an SMS was sent from.● For international SMSs, set this
parameter to the channel numberallocated when the SMS application iscreated, for example, isms100000001.
● For Chinese mainland SMSs, set thisparameter to the channel numberallocated by the SMS platform to theSMS signature. The channel number isobtained when you apply for the SMSsignature. An example channelnumber is csms100000001. Thesignature type corresponding to thechannel number must be the same asthe template type corresponding to thetemplate ID.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 6
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
to Mandatory
String(1-21999)
None
Number of the SMS recipient. Thestandard format is +{Country code}{Areacode}{Terminal number}.● If a short message is sent to
subscribers in countries or regionsoutside China, all subscriber numbersmust be in the standard format, forexample, +2412000000 (a Gabonnumber).
● If a short message is sent to asubscriber in Chinese mainland and +{country code} does not exist, thedefault country code +86 is used; if thesubscriber number is a mobile number,the {area code} is optional, forexample: +8613112345678.
If multiple recipient numbers are included,they must be separated with commas (,).Each number can contain a maximum of21 characters, and a maximum of 1,000numbers are supported.
templateId
Mandatory
String(1-32)
None
The SMS template ID. Obtain thetemplate ID when Template andVariable Specifications.This parameter must be used togetherwith the templateParas parameter.The signature type corresponding to theChinese mainland SMS channel numbermust be the same as the template typecorresponding to the template ID.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 7
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
templateParas
Optional
String[] None
If a non-variable template is used, thetemplateParas parameter is not required.This parameter specifies the list ofvariables in an SMS template. Thevariable list is used to configure thevariables specified in templateId. Thisparameter is in the JSONArray format. Fordetails, see Template and VariableSpecifications.The number and the length of variablesmust be consistent with those defined inthe template specified by the templateIdparameter. For example, if the templatespecified by templateId contains twovariables with lengths of 5 and 6, thevariable list must contain twocorresponding variables with lengths notexceeding 5 and 6, respectively.If the template content is "You have ${NUM_2} parcels delivered to ${TXT_32},this parameter can be set to ['3', 'Gate ofPeople's Park'].
statusCallback
Optional
String(1-1024)
None
The callback address of the platform userfor receiving the SMS status report, suchas http://my.com/receiveSMSReport.● If this parameter is specified, the SMS
status report is sent to the platformuser using the Status Report ReceivingAPI.
● If this parameter is not specified, theSMS platform does not push the SMSstatus report returned by the SMSC tothe platform user. The SMS statusreport is saved in the SMS platform for1 hour and is automatically deletedafter this time elapses.
● You are advised to set the callbackaddress to the domain name.
extend Optional
String(1-128)
None
This is an extended parameter, which isreturned in the status report.Spaces and braces {} are not allowed.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 8
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
signature Optional
String(0-32)
None
This parameter is available only forChinese mainland SMSs.This parameter specifies the SMSsignature name, which must be approvedand consistent with the template type.It is valid and must be specified onlywhen univesalTemplate is set to 1. Itspecifies the signature that is addedbefore the SMS content in the commontemplate.
Response Parameters
Table 2-5 Parameters in a response
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
code Mandatory
String(1-7)
None
The result code returned after the requestis sent.
description
Mandatory
String(1-512)
None
A description of the result code.
result Optional
SmsID[1-1000]
None
The SMS ID list. When multiple recipientnumbers are required, the SMS platformreturns an SMS ID to each recipientnumber.This parameter is not included when aresponse exception occurs.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 9
Table 2-6 Definition of SmsID
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
smsMsgId Mandatory
String(1-50)
None
The unique SMS ID.
from Yes String(1-21)
None
The number an SMS was sent from.
originTo Mandatory
String(1-21)
None
The number an SMS was sent to.
status Mandatory
String(1-7)
None
The status code of the SMS. For details,see API Calling Error Codes.● 000000: Request succeeded.● E200015: Too many SMSs are waiting
to be sent.● E200028: Failed to verify the template.● E200029: Failed to verify the template
type.● E200030: The template is not
activated.● E200031: Failed to verify the protocol.● E200033: The template type is
incorrect.● E200041: The recipient numbers of the
same SMS are duplicate.
createTime
Mandatory
String(1-20)
None
The time when the SMS resource wascreated, that is, the time when the SMSplatform received an SMS request fromthe platform user.Format: yyyy-MM-dd'T'HH:mm:ss'Z'
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 10
Result Code Description
Table 2-7 Result codes in responses
ResponseCode
ResultCode
Description Solution
200 000000 Success. No action is required.
400 E000000
System error. Check whether the templateParasparameter is set correctly according tothe code example. If the problempersists, contact the administrator.
E000001
Authorization notcontained in theHTTP header.
Check whether the HTTP messageheader includes the Authorizationfield.
E000002
realm notcontained inAuthorization.
Check whether the Authorization fieldincludes the realm attribute.
E000003
profile notcontained inAuthorization.
Check whether the Authorization fieldincludes the profile attribute.
E000004
The value of realmin Authorizationmust be SDP.
Check whether the attribute value ofrealm in the Authorization field isSDP.
E000005
The value ofprofile inAuthorizationmust beUsernameToken.
Check whether the attribute value ofprofile in the Authorization field isUsernameToken.
E000006
The value of typein Authorizationmust be app_key.
Check whether the attribute value oftype in the Authorization field isAppkey.
E000007
type not containedin Authorization.
Check whether the Authorization fieldincludes the type attribute.
E000008
WSSE notcontained inAuthorization.
Check whether the Authorization fieldincludes the WSSE field.
E000020
X-WSSE notcontained in theHTTP header.
Check whether the HTTP messageheader includes the X-WSSE field.
E000021
UserName notcontained in X-WSSE.
Check whether the X-WSSE fieldincludes the UserName attribute.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 11
ResponseCode
ResultCode
Description Solution
E000022
Nonce notcontained in X-WSSE.
Check whether the X-WSSE fieldincludes the Nonce attribute.
E000023
Created notcontained in X-WSSE.
Check whether the X-WSSE fieldincludes the Created attribute.
E000024
PasswordDigestnot contained inX-WSSE.
Check whether the X-WSSE fieldincludes the PasswordDigest attribute.
E000025
The format ofCreated isincorrect.
Check whether the format of theCreated attribute in the X-WSSE field iscorrect.
E000026
UsernameTokennot contained inX-WSSE.
Check whether the X-WSSE fieldincludes the UsernameToken attribute.
E000027
Invalid request. Check whether the parameters in therequest are valid based on theparameter description and requirementsin the API document.
E000040
The value ofContentType mustbe application/x-www-form-urlencoded.
Check whether the value of theContentType header field isapplication/x-www-form-urlencoded.
E000503
The parameterformat is incorrect.
Check whether the parameter format iscorrect.
E000510
The SMS fails tobe sent. Fordetails, see status.
Check the value of status in theresponse parameter to determine thecause of the failure, modify theparameter value, and resend the SMS.
E000623
Number of SMSssent by the SPreached the limit.
Contact the operation manager toincrease the maximum number of SMSssent by the SP.
401 E000101
Authenticationfailed.
Check whether the values ofAuthorization and X-WSSE are correct.
E000102
Invalid app_key. Check whether app_key included in therequest is correct.
E000103
The status of theapp_key isunavailable.
Contact the administrator to checkwhether the status of app_key isnormal.
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 12
ResponseCode
ResultCode
Description Solution
E000104
Invalid app_secret. Check whether app_secret included inthe request is correct.
E000105
Invalid digest. Check whether PasswordDigestincluded in the request is correct.
E000106
The app_key is notallowed to invokethis API.
Contact the administrator to checkwhether the application correspondingto the app_key supports SMS capabilityexposure.
E000109
The user status isdeactivated.
Contact the administrator to activatethe user.
E000110
Time out limit. When X-WSSE authentication is used,make sure that there is not too muchdifference between the time when therandom string is generated and thelocal time when the request is sent. Fordetails, contact the administrator.
E000111
Inccorectusername orpassword.
The user information corresponding toapp_key cannot be found. Contact theadministrator.
E000112
The subsriberstatus is frozen.
Contact the administrator to unfreezethe user.
403 E000620
The app client ip isnot in ip white list.
Contact the administrator to checkwhether IP whitelist settings are correct.
API Example● Request example
POST /sms/batchSendSms/v1 HTTP/1.1x-real-ip: 10.10.10.168 x-real-port: 10443 host: ompap.innercontent-length: 184 date: Fri, 13 Apr 2018 06:31:39 GMTauthorization: WSSE realm="SDP",profile="UsernameToken",type="Appkey"x-wsse: UsernameToken Username="ZRBRz4bAXoFgEH7o4Ew308eXc1RA",PasswordDigest="NDA1MWIwNjI2ZTkyNWFlM2FhMTE5NDE1YTk5NjU1YWE4NjNlZTY1MmRhYzkxZGViNzczZjdjMjkzZWQ4ZjAwNA==",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"accept: application/jsoncontent-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
● Response exampleHTTP/1.1 200 OKDate: Fri, 13 Apr 2018 06:29:08 GMT
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 13
Server: WebServerContent-Type: application/json;charset=UTF-8Content-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"}
Message & SMSAPIs 2 SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 14
3 Batch SMS Sending API
API FunctionThis API is used to have the SMS platform send different SMSs to different users.
Instructions● Prerequisites
a. An SMS application has been created. Application Key, ApplicationSecret, Application Access Address, and Channel No. (except thechannel No. of SMS in Chinese Mainland) have been obtained.
b. (Mandatory only for Chinese mainland) You have applied for an SMSsignature and obtained a channel No.
c. You have applied for an SMS template and obtained the template ID.● Notes
a. A single SMS can include a maximum of 1,000 numbers separated bycommas (,). Each number can include a maximum of 21 characters. If anSMS includes more than 1000 numbers, the SMS fails to be sent to any ofthe numbers.
b. When X-WSSE authentication is used, there cannot be too muchdifference between the local time when the request is sent and the timewhen the random string was generated. Otherwise, the authenticationwill fail.
API Type
Table 3-1 API type
Method
POST
URI /sms/batchSendDiffSms/v1
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 15
CommunicationsProtocol
HTTPS
Request Parameters
Table 3-2 Parameters in the request headers
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
Content-Type
Mandatory
String None
It has a fixed value of application/json.
Authorization
Mandatory
String None
The parameter value is WSSE realm toSDP, profile to UsernameToken, andtype to Appkey.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 16
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
X-WSSE Mandatory
String None
The parameter value is UsernameTokenUsername=Value of app_key,PasswordDigest=Value ofPasswordDigest, Nonce=Randomnumber, Created=Time when therandom number is generated.● PasswordDigest: The value of this
parameter is generated based onPasswordDigest = Base64 (SHA256(Nonce + Created + Password)). Thecharacter string consisting of Nonce,Created, and Password is used forSHA256 encryption. The string doesnot contain plus signs (+) or spaces.Password indicates the value ofapp_secret.
● Nonce: When a platform user sends arequest, a random, all-caps,alphanumeric string of 1-128characters is generated, for example,66C92B11FF8A425FB8D4CCFE0ED9ED1F.
● Created: The time when a randomcharacter string is generated. StandardUTC is used, for example,2018-02-12T15:30:20Z. The timeformat conversion mode used dependson the programming language. Fordetails, see Table 3-3.
Table 3-3 Time formats in different programming languages
ProgrammingLanguage
Time Format
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
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 17
ProgrammingLanguage
Time Format
Node.js toISOString().replace(/.[0-9]+\Z/, 'Z')Note: In Node.js, delete ms from the time format converted byusing toISOString().
Table 3-4 Parameters in the request body
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
from Mandatory
String(1-21)
None
The number an SMS was sent from.● For international SMSs, set this
parameter to the channel numberallocated when the SMS application iscreated, for example, isms100000001.
● For Chinese mainland SMSs, set thisparameter to the channel numberallocated by the SMS platform to theSMS signature. The channel number isobtained when you apply for the SMSsignature. An example channelnumber is csms100000001. Thesignature type corresponding to thechannel number must be the same asthe template type corresponding to thetemplate ID.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 18
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
statusCallback
Optional
String(1-1024)
None
The callback address of the platform userfor receiving the SMS status report, suchas http://my.com/receiveSMSReport.● If this parameter is specified, the SMS
status report is sent to the platformuser using the Status Report ReceivingAPI.
● If this parameter is not specified, theSMS platform does not push the SMSstatus report returned by the SMSC tothe platform user. The SMS statusreport is saved in the SMS platform for1 hour and is automatically deletedafter this time elapses.
● You are advised to set the callbackaddress to the domain name.
smsContent
Mandatory
SmsContent[]
None
The content of SMS notification. The sizeof SMS content cannot exceed 64 KB.
extend Optional
String(1-128)
None
This is an extended parameter, which isreturned in the status report.Spaces and braces {} are not allowed.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 19
Table 3-5 Definition of SmsContent
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
to Mandatory
String[](1-21999)
None
Group subscriber numbers to which ashort message is sent. The standardformat is +{Country code}{Area code}{Terminal number}.● If a short message is sent to
subscribers in countries or regionsoutside China, all subscriber numbersmust be in the standard format, forexample, +2412000000 (a Gabonnumber).
● If a short message is sent tosubscribers in Chinese mainland and +{country code} does not exist, thedefault country code +86 is used; ifsubscriber numbers are mobilenumbers, the {area code} is optional,for example: +8613112345678.
If multiple recipient numbers are included,they must be separated with commas (,).Each number can contain a maximum of21 characters, and a maximum of 1,000numbers are supported.
templateId
Mandatory
String(1-32)
None
The SMS template ID. Obtain thetemplate ID when applying for an SMStemplate.This parameter must be used togetherwith the templateParas parameter.The signature type corresponding to theChinese mainland SMS channel numbermust be the same as the template typecorresponding to the template ID.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 20
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
templateParas
Optional
String[] None
If a non-variable template is used, thetemplateParas parameter is not required.This parameter specifies the list ofvariables in an SMS template. Thevariable list is used to configure thevariables specified in templateId. Thisparameter is in the JSONArray format. Fordetails, see Template and VariableSpecifications.The number and the length of variablesmust be consistent with those defined inthe template specified by the templateIdparameter. For example, if the templatespecified by templateId contains twovariables with lengths of 5 and 6, thevariable list must contain twocorresponding variables with lengths notexceeding 5 and 6, respectively.If the template content is "You have ${NUM_2} parcels delivered to ${TXT_32},this parameter can be set to ['3', 'Gate ofPeople's Park'].
signature Optional
String(0-32)
None
This parameter is available only forChinese mainland SMSs.This parameter specifies the SMSsignature name, which must be approvedand consistent with the template type.It is valid and must be specified onlywhen univesalTemplate is set to 1. Itspecifies the signature that is addedbefore the SMS content in the commontemplate.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 21
Response Parameters
Table 3-6 Parameters in a response
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
code Mandatory
String(1-7)
None
The result code returned after the requestis sent.
description
Mandatory
String(1-512)
None
A description of the result code.
result Optional
SmsID[] None
The SMS body. This parameter is notincluded when an error is returned.
Table 3-7 Definition of SmsID
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
smsMsgId Mandatory
String(1-50)
None
The unique SMS ID.
from Yes String(1-21)
None
The number an SMS was sent from.
originTo Mandatory
String(1-21)
None
The number an SMS was sent to.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 22
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
status Mandatory
String(1-7)
None
The status code of the SMS. For details,see API Calling Error Codes.● 000000: Request succeeded.● E200015: Too many SMSs are waiting
to be sent.● E200028: Failed to verify the template.● E200029: Failed to verify the template
type.● E200030: The template is not
activated.● E200031: Failed to verify the protocol.● E200033: The template type is
incorrect.● E200041: The recipient numbers of the
same SMS are duplicate.
createTime
Mandatory
String(1-20)
None
The time when the SMS resource wascreated, that is, the time when the SMSplatform received an SMS request fromthe platform user.Format: yyyy-MM-dd'T'HH:mm:ss'Z'
Result Code Description
Table 3-8 Result codes in responses
ResponseCode
ResultCode
Description Solution
200 000000 Success. No action is required.
400 E000000
System error. Check whether the templateParasparameter is set correctly according tothe code example. If the problempersists, contact the administrator.
E000001
Authorization notcontained in theHTTP header.
Check whether the HTTP messageheader includes the Authorizationfield.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 23
ResponseCode
ResultCode
Description Solution
E000002
realm notcontained inAuthorization.
Check whether the Authorization fieldincludes the realm attribute.
E000003
profile notcontained inAuthorization.
Check whether the Authorization fieldincludes the profile attribute.
E000004
The value of realmin Authorizationmust be SDP.
Check whether the attribute value ofrealm in the Authorization field isSDP.
E000005
The value ofprofile inAuthorizationmust beUsernameToken.
Check whether the attribute value ofprofile in the Authorization field isUsernameToken.
E000006
The value of typein Authorizationmust be app_key.
Check whether the attribute value oftype in the Authorization field isAppkey.
E000007
type not containedin Authorization.
Check whether the Authorization fieldincludes the type attribute.
E000008
WSSE notcontained inAuthorization.
Check whether the Authorization fieldincludes the WSSE field.
E000020
X-WSSE notcontained in theHTTP header.
Check whether the HTTP messageheader includes the X-WSSE field.
E000021
UserName notcontained in X-WSSE.
Check whether the X-WSSE fieldincludes the UserName attribute.
E000022
Nonce notcontained in X-WSSE.
Check whether the X-WSSE fieldincludes the Nonce attribute.
E000023
Created notcontained in X-WSSE.
Check whether the X-WSSE fieldincludes the Created attribute.
E000024
PasswordDigestnot contained inX-WSSE.
Check whether the X-WSSE fieldincludes the PasswordDigest attribute.
E000025
The format ofCreated isincorrect.
Check whether the format of theCreated attribute in the X-WSSE field iscorrect.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 24
ResponseCode
ResultCode
Description Solution
E000026
UsernameTokennot contained inX-WSSE.
Check whether the X-WSSE fieldincludes the UsernameToken attribute.
E000027
Invalid request. Check whether the parameters in therequest are valid based on theparameter description and requirementsin the API document.
E000503
The parameterformat is incorrect.
Check whether the parameter format iscorrect.
E000510
The SMS fails tobe sent. Fordetails, see status.
Check the value of status in theresponse parameter to determine thecause of the failure, modify theparameter value, and resend the SMS.
E000623
Number of SMSssent by the SPreached the limit.
Contact the operation manager toincrease the maximum number of SMSssent by the SP.
401 E000101
Authenticationfailed.
Check whether the values ofAuthorization and X-WSSE are correct.
E000102
Invalid app_key. Check whether app_key included in therequest is correct.
E000103
The status of theapp_key isunavailable.
Contact the administrator to checkwhether the status of app_key isnormal.
E000104
Invalid app_secret. Check whether app_secret included inthe request is correct.
E000105
Invalid digest. Check whether PasswordDigestincluded in the request is correct.
E000106
The app_key is notallowed to invokethis API.
Contact the administrator to checkwhether the application correspondingto the app_key supports SMS capabilityexposure.
E000109
The user status isdeactivated.
Contact the administrator to activatethe user.
E000110
Time out limit. When X-WSSE authentication is used,make sure that there is not too muchdifference between the time when therandom string is generated and thelocal time when the request is sent. Fordetails, contact the administrator.
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 25
ResponseCode
ResultCode
Description Solution
E000111
Inccorectusername orpassword.
The user information corresponding toapp_key cannot be found. Contact theadministrator.
E000112
The subsriberstatus is frozen.
Contact the administrator to unfreezethe user.
403 E000620
The app client ip isnot in ip white list.
Contact the administrator to checkwhether IP whitelist settings are correct.
API Example● Request example
POST /sms/batchSendDiffSms/v1 HTTP/1.1x-real-ip: 10.10.10.168x-real-port: 10443host: ompap.innercontent-length: 315date: Fri, 13 Apr 2018 06:48:35 GMTauthorization: WSSE realm="SDP",profile="UsernameToken",type="Appkey"x-wsse: UsernameToken Username="ZRBRz4bAXoFgEH7o4Ew308eXc1RA",PasswordDigest="NDA1MWIwNjI2ZTkyNWFlM2FhMTE5NDE1YTk5NjU1YWE4NjNlZTY1MmRhYzkxZGViNzczZjdjMjkzZWQ4ZjAwNA==",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"accept: application/jsoncontent-type: application/json
{"from":"1069031221280012","smsContent":[{"to":["+8615512345678","+8615512345679"],"templateId":"abcdefghabcdefghabcdefghabcdefgh","templateParas":["062569"]},{"to":["+8615512345680"],"templateId":"hgfedcbahgfedcbahgfedcbahgfedcba","templateParas":["605623"]}],"statusCallback":"http://205.145.111.168:9330/report"}
● Response example HTTP/1.1 200 OKDate: Fri, 13 Apr 2018 06:46:04 GMTServer: WebServerContent-Type: application/json;charset=UTF-8Content-Length: 541
{"result":[{"originTo":"+8615512345678","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_52","status":"000000"},{"originTo":"+8615512345679","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_53","status":"000000"},{"originTo":"+8615512345680","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_54","status":"000000"}],"code":"000000","description":"Success"}
Message & SMSAPIs 3 Batch SMS Sending API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 26
4 Status Report Receiving API
API FunctionThis API is used to receive SMS status reports from the SMS platform. You can setthe SMS status report callback address by specifying the statusCallback field overthe SMS Sending API and Batch SMS Sending API.
● If the statusCallback field is set, the system uses its value as the SMS status reportcallback address.
● If the statusCallback field is not set, the platform user cannot receive status reportssent by the SMS platform.
Instructions● Prerequisites
The status report pushed by the SMS platform is not authenticated.● Notes
After the SMS platform successfully sends an SMS, it sends status reports tothe platform user within 72 hours.
API Type
Table 4-1 API type
Method
POST
URI Callback address specified in the SMS Sending API and Batch SMSSending API
CommunicationsProtocol
HTTPS
Message & SMSAPIs 4 Status Report Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 27
Request Parameters
Table 4-2 Parameters in the request headers
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
Content-Type
Mandatory
String None
It has a fixed value of application/x-www-form-urlencoded.
Table 4-3 Parameters in the request body
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
smsMsgId Mandatory
String(1-50)
None
The unique SMS identifier returned afteran SMS is successfully sent.
total Optional
String(1-2)
None
The number of SMSs that are split from along SMS.If the SMS is not split, set this parameterto 1.
sequence Optional
String(1-2)
None
The sequence number after a long SMS issplit. This parameter is valid only whenthe value of total is greater than 1.If the SMS is not split, set this parameterto 1.
status Mandatory
String(1-7)
None
The enumeration values of an SMS statusreport. For details about the values, seeTable 4-4. For details about how to rectifythe faults, see Status Report Errors.
Message & SMSAPIs 4 Status Report Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 28
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
source Optional
String(enumeration type)
None
The source of the SMS status report.● 1: The status report is generated by the
SMS platform.● 2: The status report is returned by the
SMSC.● 3: The status report is returned due to
SMS security control.
updateTime
Optional
String(1-20)
None
The SMS resource update time, which isgenerally the time when the SMSplatform receives the SMS status report.The value is in the format of yyyy-MM-dd'T'HH:mm:ss'Z'. The time is convertedto %3a using urlencode.When the SMS platform does not receivethe SMS status report from the SMSC, theSMS platform constructs a status reportthat does not contain the updateTimeparameter.
orgCode Optional
String(1-7)
None
Status codes of southbound NEs aretransparently transmitted. This parameteris contained only in status reports ofinternational, Hong Kong, Macao, andTaiwan SMSs.When the status code is not returned, theparameter is not used.
extend Optional
String(1-128)
None
Extended field, which is included in therequest sent by the platform user. If theSMS sent by a platform user does notinclude the extend parameter, the statusreport does not include the extendparameter.
to Optional
String(1-21)
None
The recipient number of the SMScorresponding to the status report. Thisparameter is included only when thestatus report contains the extendparameter.
Message & SMSAPIs 4 Status Report Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 29
Table 4-4 Values of status
Value Description
DELIVRD The user has received the SMS.
EXPIRED The SMS times out.
DELETED The SMS has been deleted.
UNDELIV The SMS fails to be delivered.
ACCEPTD The SMS has been accepted.
UNKNOWN The SMS status is unknown.
REJECTD The SMS has been rejected.
E200018 Failed to verify the sender channel of Chinese mainlandSMS.
E200019 Failed to match the sender channel of Chinesemainland SMS.
E200020 Failed to verify the signature channel of Chinesemainland SMS.
E200021 Failed to match the signature channel of Chinesemainland SMS.
E200022 Failed to verify the recipient channel of Chinesemainland SMS.
E200023 Failed to match the recipient channel of Chinesemainland SMS.
E200024 International SMS is not supported.
E200025 Failed to verify the recipient channel of internationalSMS.
E200026 Failed to match the recipient channel of internationalSMS.
E200027 Failed to match the SMSGW.
E200032 An SMS template is required.
E200034 The SMS retransmission times out.
E200035 Failed to replace the SMS protocol field.
E200036 The southbound rate control configuration is 0.
E200038 Long SMS receiving times out.
MILIMIT Reached the maximum number of SMSs sent to arecipient number per minute.
Message & SMSAPIs 4 Status Report Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 30
Value Description
LIMIT Reached the maximum number of SMSs sent to arecipient number.
BEYONDN
KEYWORD The SMS keyword was intercepted.
BLACK The number is blocked.
MBBLACK
DJ:0255 The carrier intercepted the SMS. The SMS content isnot allowed to send.
1 The phone numbers are dead, powered off, orsuspended.
24
MK:xxxx
MN:xxxx
LT:0001
MA:xxxx The SMSC does not return a response.
MB:xxxx The SMSC returns an error response.
MC:xxxx The OMP does not receive a status report from theSMSC.
CA:xxxx The SCP does not return a response.
CB:xxxx The SCP returns an error response.
DA:xxxx The DSMP does not return a response.
DB:xxxx The DSMP returns an error response.
SA:xxxx The SP does not return a response.
SB:xxxx The SP returns an error response.
IA:xxxx The ISMG does not return a response.
IB:xxxx The ISMG returns an error response.
IC:xxxx No status report is received from the ISMG.
SC:0001 The SMS is intercepted due to manual review.
SC:0002 The SMS is intercepted due to the manual reviewalarm.
SC:0003 The SMS is intercepted due to the blacklist.
SC:0004 The SMS is intercepted due to the redlist.
SC:0005 The SMS is intercepted due to the complaint blacklist.
Message & SMSAPIs 4 Status Report Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 31
Value Description
SC:0006 The SMS is intercepted due to forbidden keywords.
SC:0007 The SMS is intercepted due to feature keywords.
SC:0008 The SMS is intercepted due to control keywords.
SC:0009 The SMS is intercepted due to lack of mandatorykeywords.
SC:0010 The SMS is intercepted due to the very frequent SMSfunction.
SC:0011 The SMS is intercepted due to period control.
SC:0012 Manual review times out.
SC:0013 The SMS is intercepted due to the signature blacklist.
SC:0014 The SMS matches with the approval-free template.
SC:0015 The SMS matches with the interception template.
SC:0016 The SMS is intercepted due to the unsubscriptionblacklist.
SC:0017 The SMS is intercepted due to the non-registrationtemplate.
SC:0018 The SMS is intercepted due to the non-registrationsignature.
Response ParametersThe platform user can send any response to the SMS platform, where the responseis not processed.
API Example● Request example
POST /report HTTP/1.1Host: 205.145.111.168:9330Content-Type: application/x-www-form-urlencodedConnection: closePooltype: approxyOmpsid: 7f540777fe4b40dfb3c21d10f48781e3TerminalIP: 205.141.112.18TrcModule: APUserTrace: applicationTraceHandle: 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
● Response exampleHTTP/1.1 200 OKDate: Fri, 13 Apr 2018 06:31:45 GMTContent-Type: application/JSON; charset=UTF-8Content-Length: 43
Message & SMSAPIs 4 Status Report Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 32
{"returnCode":0,"returnCodeDesc":"Success"}
Message & SMSAPIs 4 Status Report Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 33
5 Uplink SMS Receiving API
API FunctionThis API is used to receive uplink SMS notifications sent by the SMS platform. Theaddress for receiving SMS notifications must be set when an SMS application iscreated.
Note: Only Chinese mainland SMSs support the uplink SMS function.
InstructionsPrerequisites
Uplink SMS Destination has been set when an SMS application is created.
If the AK/SK authentication for uplink SMSs is required, the platform user needs toinform the administrator of the purpose and provide the AK/SK in advance. Ifauthentication is not required for uplink SMSs sent by the SMS platform, theplatform user does not need to provide the AK/SK.
API Type
Table 5-1 API type
Method
POST
URI Address used by the user to receive uplink SMSs
CommunicationsProtocol
HTTPS
Message & SMSAPIs 5 Uplink SMS Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 34
Request Parameters
Table 5-2 Parameters in the request headers
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
Content-Type
Mandatory
String None
It has a fixed value of application/x-www-form-urlencoded.
Table 5-3 Parameters in the request body
Parameter Name
MandatoryorOptional
Type DefaultValue
Description
smsMsgId Mandatory
String(1-50)
None
The unique uplink SMS ID.
from Mandatory
String(1-21)
None
The number an uplink SMS was sentfrom.
to Mandatory
String[](1-21)
None
The number an uplink SMS was sent to.
body Mandatory
String(1-160)
None
The content of the uplink SMS.
Response ParametersThe platform user can send any response to the SMS platform. The SMS platformdoes not process these responses.
API Example● Request example
POST /smsRecive HTTP/1.1Host: 205.145.111.168:9330
Message & SMSAPIs 5 Uplink SMS Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 35
Content-Type: application/x-www-form-urlencodedConnection: closePooltype: approxyOmpsid: 56514cc1880e40638f16c7c674265658TerminalIP: 205.141.112.17TrcModule: APUserTrace: applicationTraceHandle: DMZ_818405
from=%2B8615502795172&to=201804131431201234&body=********&smsMsgId=9692b5be-c427-4525-8e73-cf4a6ac5b3f7
● Response exampleHTTP/1.1 200 OKDate: Fri, 13 Apr 2018 06:31:48 GMTContent-Type: application/JSON; charset=UTF-8Content-Length: 43
{"returnCode":0,"returnCodeDesc":"Success"}
Message & SMSAPIs 5 Uplink SMS Receiving API
Issue 05 (2020-05-15) Copyright © Huawei Technologies Co., Ltd. 36