Help Center/ Message & SMS/ API Reference/ APIs/ SMS Sending and Receiving APIs/ Batch SMS Sending API
Updated on 2024-10-25 GMT+08:00
View PDF
Share

Batch SMS Sending API

Function

This API is used for the Message & SMS platform to send different SMSs to different users as requested.

Prerequisites

Notes

  • An SMS can be sent to a maximum of 500 numbers separated by commas (,). Each number contains a maximum of 21 characters. If there are more than 500 numbers, the SMS fails to be sent to any of the numbers.
  • When X-WSSE authentication is used, the difference between the time when a random number is generated and the local time when the request is sent cannot exceed 24 hours. Otherwise, the authentication will fail.
  • When AK/SK authentication is used, the difference between the time when a random number is generated and the local time when the request is sent cannot exceed 15 minutes. Otherwise, the authentication will fail.

Type

Table 1 API type

Method

POST

URI

/sms/batchSendDiffSms/v1

Communications Protocol

HTTPS/HTTP

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Default Value

Description

Content-Type

Yes

String

None

The fixed value is application/json.

Authorization

Yes

String

None
  • If AK/SK authentication is used, the value is

SDK-HMAC-SHA256 Access="Value of app_key", SignedHeaders="Headers used for signature (lowercase)", Signature="Value calculated using the signature algorithm".

For details, see Adding the Signature to the Request Header.

  • If X-WSSE authentication is used, the value is WSSE realm="SDP", profile="UsernameToken", type="Appkey".

X-WSSE

No (mandatory for X-WSSE authentication)

String

None
The value is UsernameToken Username="Value of app_key", PasswordDigest="Value of PasswordDigest", Nonce="Random string", Created="Time when the random string is generated".
  • PasswordDigest: The value is generated based on Base64 (SHA256 (Nonce + Created + Password)). The string consisting of Nonce, Created, and Password is SHA256 encrypted and does not contain plus signs (+) or spaces. Password indicates the value of application secret.
  • Nonce: When a platform user sends a request, a 1–128 character string with letters and digits is generated, for example, 66C92B11FF8A425FB8D4CCFE0ED9ED1F.
  • Created: indicates the time when the random string is generated. Standard UTC is used, for example, 2018-02-12T15:30:20Z. The time formats vary by programming language. For details, see Table 3.

X-Sdk-Date

No (mandatory for AK/SK authentication)

String

None

Format: yyyyMMdd'T'HHmmss'Z'.

Host

No

String

None

Destination address of API calling for AK/SK authentication, for example, smsapi.cn-north-4.myhuaweicloud.com:443.
Table 3 Time formats in different programming languages

Programming Language

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

Node.js

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

Note: In Node.js, delete ms from the time format converted by using toISOString().

Go

2006-01-02T15:04:05Z
Table 4 Request body parameters

Parameter

Mandatory

Type

Default Value

Description

from

Yes

String (1 to 21 characters)

None

Number from which an SMS is sent.

  • For international SMSs, set this parameter to the channel number allocated when the SMS application is created, for example, isms100000001.
  • For Chinese mainland SMSs, set this parameter to the channel number allocated by the platform to the SMS signature. The channel number is obtained when you apply for the SMS signature. An example channel number is csms100000001. The signature type corresponding to the channel number must be the same as the template type corresponding to the template ID.

statusCallback

No

String (1 to 1,024 characters)

None

Callback address of the user for receiving the SMS status report, for example http://my.com/receiveSMSReport.

  • If this parameter is specified, the SMS status report is sent to the user using the Status Report Receiving API.
  • If this parameter is not specified, the Message & SMS platform does not push the SMS status report returned by the carrier SMS center to the user. The SMS status report is saved in the platform for 1 hour and is automatically deleted when it times out.
  • You are advised to set the callback address to the domain name.

smsContent

Yes

SmsContent[]

None

Content of an SMS notification. Its size cannot exceed 64 KB.

extend

No

String (1 to 128 characters)

None

Extended parameter returned in the status report.

Spaces and braces {} are not allowed.
Table 5 Definition of SmsContent

Parameter

Mandatory

Type

Default Value

Description

to

Yes

String[] (1 to 21,999 characters)

None

SMS recipient numbers for group sending. The standard format is +{Country code}{Area code}{Terminal number}.

  • If an SMS is sent to recipients in countries or regions outside the Chinese mainland, all recipient numbers must be in the standard format, for example, +2412000000 (a Gabon number).
  • If an SMS is sent to recipients in the Chinese mainland and +{Country code} does not exist, the default country code +86 is used; if the recipient number is a mobile number, {Area code} is optional, for example, +8613112345678.

Separate multiple recipient numbers with commas (,). Each number contains a maximum of 21 characters, and a maximum of 500 numbers are supported.

templateId

Yes

String (1 to 32 characters)

None

Unique SMS template ID. Obtain the template ID when applying for an SMS template.

templateId must be used together with the templateParas parameter.

The signature type corresponding to the Chinese mainland SMS channel number must be the same as the template type corresponding to the template ID.

templateParas

No

String

None

Optional when a non-variable template is used.

List of SMS template variables, used to configure the variables specified in templateId. This parameter is in the JSONArray format. For details, see Template and Variable Specifications.

The number and the length of variables must be consistent with those defined in the template specified by the templateId parameter. For example, if the template specified by templateId contains two variables with lengths of 5 and 6, the variable list must contain two corresponding variables with lengths not exceeding 5 and 6, respectively.

If the template content is "You have ${NUM_5} parcels delivered to ${TXT_6}, this parameter can be set to '["3","Gate of People's Park"]'.

signature

No

String (0 to 32 characters)

None

(For Chinese mainland SMSs only)

SMS signature name, which must be approved and consistent with the template type.

This parameter is valid and must be specified only when a general template is specified. It specifies the signature before the SMS content in the general template.

NOTE:
  • If the template specified by templateId is a general template, the from field is optional.
  • If the template specified by templateId is not a general template, the from field is mandatory.

Response Parameters

Table 6 Parameters in a response

Parameter

Mandatory

Type

Default Value

Description

code

Yes

String (1 to 7 characters)

None

Result code returned after the request is sent.

description

Yes

String (1 to 512 characters)

None

Description of the result code.

result

No

SmsID[]

None

SMS body. A response does not contain this parameter when an error occurs.
Table 7 Definition of SmsID

Parameter

Mandatory

Type

Default Value

Description

smsMsgId

Yes

String (1 to 50 characters)

None

Unique SMS ID.

from

Yes

String (1 to 21 characters)

None

Number from which an SMS is sent.

originTo

Yes

String (1 to 21 characters)

None

Number to which an SMS is sent.

status

Yes

String (1 to 7 characters)

None

SMS status code. The following describes some SMS status codes. For details about the handling suggestions, see API 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

Yes

String (1 to 20 characters)

None

Time when the SMS resource was created, that is, the UTC time when the Message & SMS platform received an SMS request from a user.

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

countryId

No

String (1 to 3 characters)

None

Country code of the SMS recipient number.

total

No

Integer

None

Number of split SMSs.

Result Codes

Table 8 Result codes in responses

Response Code

Result Code

Message

Description

Solution

200

000000

Success.

The request is sent successfully.

No action is required.

400

E000000

System error.

The system is abnormal.

Check whether the templateParas parameter is set correctly according to the code example. If the problem persists, contact the administrator.

E000001

Authorization not contained in the HTTP header.

Authorization is not contained in the HTTP header.

Check whether the HTTP message header contains the Authorization field.

E000002

realm not contained in Authorization.

realm is not contained in Authorization.

Check whether the Authorization field contains the realm attribute.

E000003

profile not contained in Authorization.

profile is not contained in Authorization.

Check whether the Authorization field contains the profile attribute.

E000004

The value of realm in Authorization must be SDP.

The value of realm in Authorization must be SDP.

Check whether the value of realm in the Authorization field is SDP.

E000005

The value of profile in Authorization must be UsernameToken.

The value of profile in Authorization must be UsernameToken.

Check whether the value of profile in the Authorization field is UsernameToken.

E000006

The value of type in Authorization must be app_key.

The value of type in Authorization must be Appkey.

Check whether the value of type in the Authorization field is Appkey.

E000007

type not contained in Authorization.

type is not contained in Authorization.

Check whether the Authorization field contains the type attribute.

E000008

WSSE not contained in Authorization.

WSSE is not contained in Authorization.

Check whether the Authorization field contains WSSE.

E000020

X-WSSE not contained in the HTTP header.

X-WSSE is not contained in the HTTP header.

Check whether the HTTP message header contains the X-WSSE field.

E000021

UserName not contained in X-WSSE.

UserName is not contained in X-WSSE.

Check whether the X-WSSE field contains the UserName attribute.

E000022

Nonce not contained in X-WSSE.

Nonce is not contained in X-WSSE.

Check whether the X-WSSE field contains the Nonce attribute.

E000023

Created not contained in X-WSSE.

Created is not contained in X-WSSE.

Check whether the X-WSSE field contains the Created attribute.

E000024

PasswordDigest not contained in X-WSSE.

PasswordDigest is not contained in X-WSSE.

Check whether the X-WSSE field contains the PasswordDigest attribute.

E000025

The format of Created is incorrect.

The format of Created is incorrect.

Check whether the format of the Created attribute in the X-WSSE field is correct.

E000026

UsernameToken not contained in X-WSSE.

UsernameToken is not contained in X-WSSE.

Check whether the X-WSSE field contains the UsernameToken attribute.

E000027

Invalid request.

The request is invalid.

Check whether the parameters in the request are valid based on the parameter description and requirements in the API reference.

E000041

X-Sdk-Date header is empty.

X-Sdk-Date is empty.

For special AK/SK authentication, check the value of X-Sdk-Date in the HTTP message header.

E000042

The format of X-Sdk-Date header is invalid.

Incorrect X-Sdk-Date format.

For special AK/SK authentication, check the format of X-Sdk-Date in the HTTP message header. The format is yyyyMMdd'T'HHmmss'Z'.

E000043

The format of Authorization header is incorrect.

Incorrect Authorization format.

For special AK/SK authentication, check the format of Authorization in the HTTP message header.

E000044

X-Sdk-Date is expired.

X-Sdk-Date expires.

For special AK/SK authentication, check the time of X-Sdk-Date in the HTTP header. The difference between the time and the local time when the request is sent cannot exceed 15 minutes. Otherwise, the authentication fails.

E000045

Authorization verify failed.

Authorization verification failed.

For special AK/SK authentication, check the Signature field in Authorization of the HTTP message header.

E000503

The parameter format is incorrect.

The parameter format is incorrect.

Check whether the parameter format is correct.

E000510

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

Failed to send the SMS. For details, see the description of the status parameter.

Check the value of status in the response parameter to determine the cause of the failure, modify the parameter value, and resend the SMS.

401

E000101

Authentication failed.

Authentication failed.

Check whether the values of Authorization and X-WSSE are correct.

E000102

Invalid app_key.

app_key is invalid.

Check whether app_key in the request is correct.

If app_key is correct, check whether the application access address (obtained from the Application Management page on the console) is correct.

E000103

The status of the app_key is unavailable.

app_key is unavailable.

Contact the administrator to check whether the app_key status is normal.

E000104

Invalid app_secret.

app_secret is invalid.

Check whether app_secret in the request is correct.

E000105

Invalid digest.

PasswordDigest is invalid.

Check whether PasswordDigest in the request is correct.

E000106

The app_key is not allowed to invoke this API.

The app_key does not have the permission to call this API.

Contact the administrator to check whether the application corresponding to the app_key supports SMS capability exposure.

E000109

The user status is deactivated.

The user is deactivated.

Contact the administrator to activate the user.

E000110

Time out limit.

The time exceeds the limit.

When X-WSSE authentication is used, make sure that there is not too much difference between the time when the random string is generated and the local time when the request is sent. For details, contact the administrator.

E000111

Incorrect username or password.

Incorrect username or password.

The user information corresponding to app_key cannot be found. Contact the administrator.

E000112

The subscriber status is frozen.

The user is frozen.

If the account is frozen due to arrears, top up the account by referring to Topping Up an Account (Prepaid Direct Customers). Then, the account is automatically unfrozen.

If the account is frozen due to violation, modify the service and contact the operations manager to apply for account unfreezing.

403

E000620

The app client ip is not in ip white list.

The peer application IP address is not in the whitelist.
  • It takes about 10 to 15 minutes for the IP address whitelist configuration to take effect. This error may be reported if the configuration does not take effect in time.
  • The IP address whitelist configuration is incorrect. On the console, choose Application Management, click Modify, and check and modify the configured IP address whitelist, or add a correct IP address whitelist (when it is configured by the platform administrator).

E000623

Number of SMSs sent by the SP reached the limit.

Number of SMSs sent by the SP reached the limit.

Contact the operations manager to increase the maximum number of SMSs sent by the SP.

E000630

Number of SMSs sent by the SP reached the country/region limit.

Number of SMSs sent by the SP reached the country/region limit.

You can set a limit for the number of accumulated SMSs sent to a country or region.

When this limit is reached, new SMSs will fail to be sent.

You can modify or delete the limit on the general setting page by referring to Traffic Threshold. Contact the operations manager to increase the maximum number of SMSs sent by the SP.

API Example

  • Example request 1 (X-WSSE authentication) 
    POST /sms/batchSendDiffSms/v1 HTTP/1.1
x-real-ip: 10.10.10.168
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="NDA1MWIwNjI2ZTkyNWFlM2FhMTE5NDE1YTk5NjU1YWE4NjNlZTY1MmRhYzkxZGViNzczZjdjMjkzZWQ4ZjAwNA==",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
accept: application/json
content-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"}
  • Example request 2 (AK/SK authentication) 
    POST /sms/batchSendDiffSms/v1 HTTP/1.1
Host: smsapi.cn-north-4.myhuaweicloud.com:443
X-Sdk-Date: 20230519T005038Z
Authorization: SDK-HMAC-SHA256 Access=uxOF5yvM0H3C0t5G0xc272g7hA2I, SignedHeaders=content-type;host;x-sdk-date, Signature=082f05bcd561e291a7469939980c022f721a581967cc30eb3725c7aea4bd634d
content-length: 315
Content-Type: application/json
 
{"from":"1069********0012","smsContent":[{"to":["+86155****5678","+86155****5679"],"templateId":"abcdefghabcdefghabcdefghabcdefgh","templateParas":["062569"]},{"to":["+86155****45680"],"templateId":"hgfedcbahgfedcbahgfedcbahgfedcba","templateParas":["605623"]}],"statusCallback":"http://205.145.111.168:9330/report"}
  • Response Example 
     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: 622

{"result":[{"originTo":"+8615512345678","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_52","status":"000000","countryId":"CN","total":2},{"originTo":"+8615512345679","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_53","status":"000000","countryId":"CN","total":2},{"originTo":"+8615512345680","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_54","status":"000000","countryId":"CN","total":2}],"code":"000000","description":"Success"}

Demos

Download the following demos to quickly develop applications: