Follow these API specifications when you develop a third-party SMS platform for the user marketing module.
General parameters for SMS requests
URL parameter | Description | Example |
timestamp | UNIX timestamp in seconds | 1631865523 |
nonce | 32-character random string | 2e6eceb5737b473284c930c8ef79090e |
Request URL example:
{URL of all third-party SMS APIs}?timestamp=1631865523&nonce=2e6eceb5737b473284c930c8ef79090eHeader | Description | Notes |
X-QA-Hmac-Signature | Authentication signature | This header is used when authentication is enabled. For more information about the authentication method, see the following section. If authentication is disabled, set this header to an empty string (""). |
SMS request authentication
If authentication is required for text messages, enable authentication and enter a key when you configure the third-party SMS API. For more information, see Create a third-party SMS platform API.
QuickAudience uses the key you provide, along with the `timestamp` and `nonce` URL parameters, to generate an HmacSHA256Hex signature. This signature is sent in the request header. When your service receives the request, it performs the same HmacSHA256Hex encryption using the URL parameters and the key configured for the webhook channel. If the calculated value matches the signature from the request header, the request is authenticated.
Parameter | Description | Example |
key | The key configured for the webhook | 123456789 |
Signature algorithm example:
public String makeSignature(String key, String timestamp, String nonce) {
String str = generateStr(key, timestamp, nonce);
return HmacUtils.hmacSha256Hex(key, str.replaceAll("\\s+", ""));
}
/**
* Concatenates the strings to be signed.
*/
public static String generateStr(String key, String timestamp, String nonce){
String[] array = new String[] { key, timestamp, nonce};
StringBuffer sb = new StringBuffer();
// Sorts the strings.
Arrays.sort(array);
for (int i = 0; i < 3; i++) {
sb.append(array[i]);
}
return sb.toString();
}SMS template review API
API Reference | SMS template review | |||
URL | ${prefix}/sms/smsTemplate?timestamp=&nonce= | |||
Method | post | |||
Request type | application/json | |||
Return type | */* | |||
Parameter name | Data type | Parameter type | Required | Description |
1.remark | string | body | Yes | The description for the SMS template request. Describe your business scenario in the description. The description must be 1 to 100 characters in length. |
2.templateContent | string | Yes | The content of the template. The content must be 1 to 500 characters in length. | |
3.templateName | string | Yes | The name of the template. The name must be 1 to 30 characters in length. | |
4.templateSubject | string | No | The subject of the template. The subject must be 1 to 20 characters in length. | |
5.templateType | integer(int32) | Yes | The type of the text message.
| |
Status code | Description | Notes | ||
200 | OK | The request is successful. | ||
401 | Unauthorized | The request is not authorized. | ||
403 | Forbidden | The request is denied. | ||
404 | Not Found | The requested resource does not exist. | ||
Returned Property Name | Type | Description | ||
1.platformName | string | The name of the SMS service provider. This is the same as the API name that you entered during configuration. | ||
2.code | string | The status code of the request. A value of 200 or OK indicates that the request is successful. | ||
3.message | string | The description of the status code. | ||
4.requestId | string | The request ID. | ||
5.templateCode | string | The code of the SMS template. Use this code to check the status and result of the template request. | ||
Example | ||||
Request parameters | -d '{"remark":"string","templateContent":"string","templateName":"string","templateSubject":"string","templateType":0}' | |||
Return value | {"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"} | |||
SMS template modification API
Description | Modify an SMS template | |||
URL | ${prefix}/sms/smsTemplate/{templateCode}?timestamp=&nonce= | |||
Method | Put | |||
Request type | application/json | |||
Return type | */* | |||
Parameter name | Data type | Parameter type | Required | Description |
1.remark | string | body | No | The description for the SMS template request. Describe your business scenario in the description. The description must be 1 to 100 characters in length. |
2.templateContent | string | No | The content of the template. The content must be 1 to 500 characters in length. | |
3.templateName | string | No | The name of the template. The name must be 1 to 30 characters in length. | |
4.templateSubject | string | No | The subject of the template. The subject must be 1 to 20 characters in length. | |
5.templateType | integer(int32) | No | The type of the text message.
| |
Status code | Description | Notes | ||
200 | OK | The request is successful. | ||
401 | Unauthorized | The request is not authorized. | ||
403 | Forbidden | The request is denied. | ||
404 | Not Found | The requested resource does not exist. | ||
Return property | Type | Description | ||
1.platformName | string | The name of the SMS service provider. This is the same as the API name that you entered during configuration. | ||
2.code | string | The status code of the request. A value of 200 or OK indicates that the request is successful. | ||
3.message | string | The description of the status code. | ||
4.requestId | string | The request ID. | ||
5.templateCode | string | The code of the SMS template. Use this code to check the status and result of the template request. | ||
Example | ||||
Request parameters | -d '{"remark":"string","templateContent":"string","templateName":"string","templateSubject":"string","templateType":0}' | |||
Return value | {"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"} | |||
SMS signature review status query API
Description | Query the review status of an SMS signature | |||
URL | ${prefix}/sms/smsSign/{signName}?timestamp=&nonce= | |||
Method | GET | |||
Request type | application/json | |||
Return type | */* | |||
Parameter name | Data type | Parameter type | Required | Description |
1.signName | string | path | Yes | The SMS signature. |
Status code | Description | Notes | ||
200 | OK | The request is successful. | ||
401 | Unauthorized | The request is not authorized. | ||
403 | Forbidden | The request is denied. | ||
404 | Not Found | The requested resource does not exist. | ||
Return property name | Type | Description | ||
1.platformName | string | The name of the SMS service provider. This is the same as the API name that you entered during configuration. | ||
2.code | string | The status code of the request. A value of 200 or OK indicates that the request is successful. | ||
3.createDate | string | The date and time when the SMS signature was created. For example: 2019-01-08 16:44:13. | ||
4.message | string | The description of the status code. | ||
5.reason | string | The review notes. If the review status is Approved or Pending review, the Reason parameter displays "No review notes". If the review status is Rejected, the Reason parameter displays the specific reason for rejection. | ||
6.requestId | string | The request ID. | ||
7.signName | string | The SMS signature. | ||
8.signStatus | integer(int32) | The review status of the signature.
| ||
Example | ||||
Request parameters | No example | |||
Return value | {"reason":"string","code":"string","signName":"string","requestId":"string","signStatus":0,"platformName":"string","message":"string","createDate":"string"} | |||
SMS template review status query API
Description | Query the review status of an SMS template | |||
URL | ${prefix}/sms/smsTemplate/{templateCode}?timestamp=&nonce= | |||
Method | GET | |||
Request type | application/json | |||
Return type | */* | |||
Parameter name | Data type | Parameter type | Required | Description |
1.templateCode | string | path | Yes | The template code. |
Status code | Description | Notes | ||
200 | OK | The request is successful. | ||
401 | Unauthorized | The request is not authorized. | ||
403 | Forbidden | The request is denied. | ||
404 | Not Found | The requested resource does not exist. | ||
Return Property Name | Type | Description | ||
1.platformName | string | The name of the service provider. This is the same as the API name that you entered during configuration. | ||
2.code | string | The status code of the request. A value of 200 or OK indicates that the request is successful. | ||
3.createDate | string | The date and time when the template was created. For example: 2019-01-08 16:44:13. | ||
4.message | string | The description of the status code. | ||
5.reason | string | The review notes. If the review status is Approved or Pending review, the Reason parameter displays "No review notes". If the review status is Rejected, the Reason parameter displays the specific reason for rejection. | ||
6.requestId | string | The request ID. | ||
7.templateCode | string | The template code. | ||
8.templateContent | string | The content of the template. | ||
9.templateName | string | The name of the template. | ||
10.templateStatus | integer(int32) | The review status of the template.
| ||
11.templateType | integer(int32) | The type of the SMS template.
| ||
Example | ||||
Request parameters | No example | |||
Return value | {"templateStatus":0,"templateType":0,"reason":"string","code":"string","templateName":"string","requestId":"string","templateContent":"string","platformName":"string","templateCode":"string","message":"string","createDate":"string"} | |||
SMS sending API (single message)
Description | Send a single text message | |||
URL | ${prefix}/sms/send?timestamp=&nonce= | |||
Method | POST | |||
Request type | application/json | |||
Return type | */* | |||
Parameter name | Data type | Parameter type | Required | Description |
1.limit | integer(int64) | body | No | The maximum number of recipients. |
2.outId | string | Yes | The external transaction extension field. | |
3.phoneNumbers | string | Yes | The mobile phone number that receives the text message. For Domestic SMS, use an 11-digit mobile phone number, such as 159********. For international messages or messages to Hong Kong (China), Macao (China), and Taiwan (China), use the format: [area code][number], such as 85200******. | |
4.signName | string | Yes | The name of the SMS signature. | |
5.templateCode | string | Yes | The template code. | |
6.templateParam | string | No | The actual values for the variables in the SMS template, in JSON format. For example: `[{"name":"TemplateParamJson","age":"age"}]`. The number of parameter sets must be the same as the number of phone numbers. An error is returned if the numbers do not match. | |
Status code | Description | Notes | ||
200 | OK | The request is successful. | ||
401 | Unauthorized | The request is not authorized. | ||
403 | Forbidden | The request is denied. | ||
404 | Not Found | The requested resource does not exist. | ||
Return Property Name | Type | Description | ||
1.bizId | string | The delivery receipt ID. | ||
2.platformName | string | The name of the service provider. This is the same as the API name that you entered during configuration. | ||
3.code | string | The status code of the request. A value of 200 or OK indicates that the request is successful. | ||
4.message | string | The description of the status code. | ||
5.requestId | string | The request ID. | ||
Example | ||||
Request parameters | -d '{"limit":0,"outId":"string","phoneNumbers":"string","signName":"string","templateCode":"string","templateParam":"string"}' | |||
Return value | {"bizId":"string","platformName":"string","code":"string","message":"string","requestId":"string"} | |||
SMS sending API (batch sending)
Description | Send text messages in batches | |||
URL | ${prefix}/sms/sendBatch?timestamp=&nonce= | |||
Method | post | |||
Request type | application/json | |||
Return type | */* | |||
Parameter name | Data type | Parameter type | Required | Description |
1.limit | integer(int64) | body | No | The maximum number of recipients. |
2.outId | string | Yes | The external transaction extension field. | |
3.phoneOssUrl | string | Yes | The OSS path of the file that contains the mobile phone numbers of the recipients. The file must be in the TXT format. For Domestic SMS, use 11-digit mobile phone numbers, such as `159********`. For international messages or messages to Hong Kong (China), Macao (China), and Taiwan (China), use the format: `[area code][number]`, such as `85200******`. Each number must be on a new line. For variable messages, add the variable names and their replacement values after each mobile phone number. For example: `{"name":"TemplateParamJson","age":"age"}` | |
4.signName | string | Yes | The name of the SMS signature. | |
5.templateCode | string | Yes | The template code. | |
6.isVariable | integer(int64) | Yes | Specifies whether the message contains variables.
| |
Status code | Description | Notes | ||
200 | OK | The request is successful. | ||
401 | Unauthorized | The request is not authorized. | ||
403 | Forbidden | The request is denied. | ||
404 | Not Found | The requested resource does not exist. | ||
Returned property name | Type | Description | ||
1.bizId | string | The delivery receipt ID. | ||
2.platformName | string | The name of the service provider. This is the same as the API name that you entered during configuration. | ||
3.code | string | The status code of the request. A value of 200 or OK indicates that the request is successful. | ||
4.message | string | The description of the status code. | ||
5.requestId | string | The request ID. | ||
Example | ||||
Request parameters | -d '{"limit":0,"outId":"string","phoneOssUrl":"string","signName":"string","templateCode":"string","isVariable":"string"}' | |||
Return value | {"bizId":"string","platformName":"string","code":"string","message":"string","requestId":"string"} | |||
SMS sending details query API
Description | Query the details of sent text messages | |||
URL | ${prefix}/sms/sendDetails?timestamp=&nonce= | |||
Method | POST | |||
Request type | application/json | |||
Return type | */* | |||
Parameter | Data type | Parameter type | Required | Description |
1.outId | string | body | Yes | The external transaction extension field. |
2.currentPage | integer(int64) | Yes | The current page number of the paginated sending records. | |
3.pageSize | integer(int64) | Yes | The number of text message records to display on each page. Valid values: 1 to 1000. | |
4.startDate | string | Yes | The start time. The time range between the start and end time cannot exceed 30 days. Format: yyyy-MM-dd HH:mm:ss. | |
5.endDate | string | Yes | The end time. The time range between the start and end time cannot exceed 30 days. Format: yyyy-MM-dd HH:mm:ss. | |
Status code | Description | Notes | ||
200 | OK | The request is successful. | ||
401 | Unauthorized | The request is not authorized. | ||
403 | Forbidden | The request is denied. | ||
404 | Not Found | The requested resource does not exist. | ||
Returned property name | Type | Description | ||
1.platformName | string | The name of the SMS service provider. This is the same as the API name that you entered during configuration | ||
2.code | string | The status code of the request. A value of 200 or OK indicates that the request is successful. | ||
3.message | string | The description of the status code. | ||
4.requestId | string | The request ID. | ||
5.sendDetailDTOs | array:SmsSendDetailDTO | The details of sent text messages. | ||
5.1.content | string | The content of the text message. | ||
5.2.errCode | string | The status code from the carrier. `DELIVERED` indicates that the message was sent successfully. If the message failed to be sent, an error code is returned. | ||
5.3.outId | string | The external transaction extension field. | ||
5.4.phoneNum | string | The mobile phone number that receives the text message. | ||
5.5.receiveDate | string | The date and time when the message was received. | ||
5.6.sendDate | string | The date and time when the message was sent. | ||
5.7.sendStatus | integer(int64) | The sending status of the text message.
| ||
5.8.templateCode | string | The ID of the SMS template. | ||
6.totalCount | integer(int32) | The total number of sent text messages. | ||
Example | ||||
Request parameters | -d '{"outId":"string","currentPage":0,"pageSize":0,"startDate":"string","endDate":"string"}' | |||
Return value | {"platformName":"string","code":"string","message":"string","totalCount":0,"requestId":"string","sendDetailDTOs":[{"content":"string","errCode":"string","outId":"string","phoneNum":"string","receiveDate":"string","sendDate":"string","sendStatus":0,"templateCode":"string"}]} | |||