Message API
Basic Information
Usage Limits
Provides batch message sending via the API. Users can submit a list of uniqueId via the interface, with a size limit of 200 for the list. The default message sending limit per second for each mini-program is 200 messages. (If adjustments are needed, please contact the mini-program platform).
Provides message sending via files, which requires application. This feature is asynchronous, and there may be delays (approximately 5 minutes for processing 500,000 data).
Usage Guidelines
The API reference of the message platform primarily covers the request syntax of the interfaces, the meanings of related parameters, and request and response examples.
Error Codes
Code | Message | Description |
---|---|---|
2 | Request is too fast, and it is rate-limited! | The message sending limit for each mini-program is 200 messages per second. |
70001 | Mini-program is in the message blacklist | The mini-program platform does not allow rule-violating mini-programs to send messages. |
70002 | Registration of mini-program message information failed | Registration of mini-program message information has failed. |
70003 | Message information sending exceeded the limit | Message information sending exceeded the limit. There are temporary call limits for the interface. |
70004 | Message information does not exist | Message has not been registered on the message platform. |
70005 | Sending messages in this time period is not allowed | The platform specifies that sending messages is not allowed in this time period. Currently, there are no restrictions. |
70006 | The file for uniqueIds when sending messages via files does not exist | When sending messages via files, the file containing the required uniqueIds does not exist. |
70007 | Message signature is abnormal | Message signature is abnormal. |
70008 | Message permission is abnormal | Message permission is abnormal. |
70009 | Message query is abnormal | Message information query is abnormal. |
70010 | uniqueId does not match | When sending message information, the uniqueId does not match. |
70011 | User has turned off message push permission | When sending message information, the user has turned off message push permission. |
70012 | User has not recently visited the mini-program | When sending message information, the user has not recently visited the mini-program. |
70013 | User has been sent messages by this mini-program in the past three days! | When sending message information, the user has been sent messages by this mini-program in the past three days. |
Resource Terms
Name | Field Name | Description |
---|---|---|
Mini-program ID | miniappId | The unique ID of the mini-program, used for unique identification of the mini-program. |
Secret Key | accessKeySecret | AccessKeySecret is the key used by the user to encrypt the signature string and by the mini-program platform to verify the signature string. AccessKeySecret must be kept confidential. |
Signature Field | sign | The mini-program message platform's signature field. The mini-program platform server will verify the signature. The calculation method is to use the sha256 algorithm to encrypt the request parameters in conjunction with AccessKeySecret. |
Public HTTP Header Definitions
Name | Type | Description |
---|---|---|
Content-Type | String | application/json |
Accept-Timezone | String | Timezone. Only supports standard UTC timezone, e.g., UTC+0 |
Public Signature
1. Introduction
Signature required for accessing the mini-program message platform.
2. Code Example
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.TreeMap;
import java.util.Map;
public class SignDemo {
public static void main(String[] args) {
String miniappId = "1000083312531541234";
String operatorId = "1000083312531541234";
String timeStamp = "1677577964000";
// Custom business data. Parameters added in the 'data' are specific to your business fields. For example, in the registration message interface: {"title": "This is a message title","text": "This is a message body","linkUrl": "This is a message link","microMotionEffectStatus": "0"}
Map<String, Object> data = new TreeMap<>();
data.put("Custom business data parameter name in 'data'", "Custom business data parameter value in 'data'"); // For example: data.put("title", "This is a message title"); data.put("text", "This is a message body")
// Get 'secretAccessKey' from the operation platform
String secretAccessKey = "Your AccessKeySecret";
String requestStr = "miniappId=" + miniappId + "&operatorId=" + operatorId + "&data=" + JSON.toJSONString(data) + "&timeStamp=" + timeStamp;
String secretAccessKeySign = "&secretAccessKey=" + secretAccessKey;
requestStr = requestStr + secretAccessKeySign;
String sign = EncryptSha256Util.getSha256Str(requestStr).toUpperCase();
System.out.println(sign);
}
}
class EncryptSha256Util {
private EncryptSha256Util() {
throw new IllegalStateException("EncryptSha256Util class");
}
/**
* SHA-256 encryption
*
* @param str The string to be encrypted
* @return The encrypted string
*/
public static String getSha256Str(String str) {
MessageDigest messageDigest;
String encodeStr = "";
try {
messageDigest = MessageDigest.getInstance("SHA-256");
messageDigest.update(str.getBytes(StandardCharsets.UTF_8));
encodeStr = byte2Hex(messageDigest.digest());
} catch (NoSuchAlgorithmException e) {
System.out.printf("SHA-256 encryption failed! Message: %s%n", e.getMessage());
}
return encodeStr;
}
/**
* SHA-256 encryption: Convert bytes to hexadecimal
*
* @param bytes The byte array
* @return The encrypted string
*/
private static String byte2Hex(byte[] bytes) {
StringBuilder stringBuilder = new StringBuilder();
String tempStr;
for (byte aByte : bytes) {
tempStr = Integer.toHexString(aByte & 0xFF);
if (tempStr.length() == 1) {
// Add a '0' for the first digit
stringBuilder.append("0");
}
stringBuilder.append(tempStr);
}
return stringBuilder.toString();
}
}
Message Functionality
1. Message Configuration
1.1 Introduction
This interface is used to register message information configuration. Before sending a message to a specified user, it's necessary to generate the message configuration first.
1.2 API Documentation
1.2.1 API for Obtaining a Token to Upload Registered Rich Media Picture Context to OSS
Note: This upload token has a limited validity, currently set to 1200 seconds.
API Endpoint: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/registerMessageRichMediaPictureContext
Request Method: POST
Request Data Type: application/x-www-form-urlencoded,application/json
Response Data Type: */*
Request Parameters:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
miniappId | Mini App ID | TRUE | string |
operatorId | Operator's Custom ID | FALSE | string |
sign | Request Signature | TRUE | string |
timeStamp | Timestamp for Sending Message (in milliseconds) | FALSE | string |
data | Custom Business Data | TRUE | map |
Specific fields within the data
parameter:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
contentLength | File size, maximum limit of 500K | TRUE | integer |
contentType | File type (supports png, jpeg, jpg, bmp, webp) | TRUE | string |
fileName | File name (supports png, jpeg, jpg, bmp, webp) | TRUE | string |
Request Example:
{
"miniappId": "1000083312531541234", // Mini App ID
"operatorId": "1000083312531541234", // Custom operator ID
"timeStamp": "1677577964000", // Timestamp for sending message (milliseconds)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // Signature, please follow the common signature code for generation
"data": {
"contentType": "image/jpeg",
"contentLength": 169120, // File size (bytes)
"fileName": "xxx.jpeg" // File name
}
}
Response Status:
HTTP Status Code | Description |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
Response Parameters:
Parameter Name | Description | Type |
---|---|---|
code | Error status code | integer(int32) |
message | Error message | string |
sign | Return parameter signature information. Calculation method is the same as generating the signature | string |
data | Response data | json |
Details of the data
parameter in the response:
Parameter Name | Description | Type |
---|---|---|
miniappId | Mini App ID | string |
fileName | File name generated by the Mini App platform | string |
accessUrl | Link to download the uploaded file. This link has a limited validity of 1 hour by default | string |
storageType | Storage type. Default is OSS | string |
uploadMethod | Upload method. Supports PUT only | string |
uploadUrl | URL for uploading the file | string |
uploadHeader | Request headers required during upload | object |
Details of the uploadHeader
parameter:
Parameter Name | Description | Type |
---|---|---|
authorization | Authorization string | string |
x-oss-date | Token acquisition time (UTC+0) | string |
Host | OSS service domain address | string |
x-oss-security-token | OSS service access token | string |
Content-Length | File size | string |
Content-Type | File type | string |
Response Example:
{
"code": 0,
"message": null,
"data": {
"uploadHeader": {
"authorization": "xxx",
"x-oss-date": "Tue, 28 Feb 2023 10:39:23 GMT",
"Host": "xxx",
"x-oss-security-token": "xxx",
"Content-Length": "169120",
"Content-Type": "image/jpeg"
},
"uploadMethod": "PUT",
"accessUrl": "https://xxx",
"uploadUrl": "https://xxx",
"storageType": "oss",
"fileName": "xxx.jpeg"
},
"sign": "EB72203BB81DB4DBF94C54631C8BCBA320AF68B6102A5D0E90AB5E904DB8C574"
}
1.2.2 Upload Registered Rich Media Picture Files to OSS API
API Endpoint: This can be obtained from the uploadUrl
field in the API 1.2.1
for obtaining a token to upload registered rich media picture context to OSS.
Request Method: PUT
Response Data Type: */*
Request Header Parameters:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
authorization | Authorization string | TRUE | string |
x-oss-date | Token acquisition time (UTC+0) | TRUE | string |
Host | OSS service domain address | TRUE | string |
x-oss-security-token | OSS service access token | TRUE | string |
Content-Type | File type | TRUE | string |
Request Example:
// Import the following jar
<!-- https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp -->
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>4.10.0</version>
</dependency>
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import java.io.File;
import java.io.IOException;
public class HttpClientUploadDemo {
/**
* Upload a file
*/
public static void main(String[] args) {
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("Content-Type obtained in step 1.2.1");
RequestBody body = RequestBody.create(new File("Your file address"), mediaType);
Request request = new Request.Builder()
.url("UploadUrl obtained in step 1.2.1")
.put(body)
.addHeader("authorization", "Authorization obtained in step 1.2.1")
.addHeader("x-oss-date", "x-oss-date obtained in step 1.2.1")
.addHeader("Host", "Host obtained in step 1.2.1")
.addHeader("x-oss-security-token", "x-oss-security-token obtained in step 1.2.1")
.addHeader("Content-Length", "Content-Length obtained in step 1.2.1")
.addHeader("Content-Type", "Content-Type obtained in step 1.2.1")
.build();
Response response = null;
try {
response = client.newCall(request).execute();
} catch (IOException e) {
e.printStackTrace();
}
System.out.println("Response content: " + response);
}
}
Response Status:
HTTP Status Code | Description |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
1.2.3 Register Message API
API Endpoint: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/registerMessage
Request Method: POST
Request Data Type: application/x-www-form-urlencoded,application/json
Response Data Type: */*
Request Parameters:
Parameter Name | Description | Required | Data Type | Schema |
---|---|---|---|---|
miniappId | Mini App ID | TRUE | string | |
operatorId | Custom Operator ID | FALSE | string | |
sign | Request Signature | TRUE | string | |
timeStamp | Timestamp for Sending Message (in milliseconds) | FALSE | string | |
data | Custom Business Data | TRUE | map | RegisterMessageInfoRequestDTO |
Specific fields within the data
parameter:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
linkUrl | Message redirect link | TRUE | string |
text | Message body text | FALSE | string |
title | Message title | TRUE | string |
microMotionEffectStatus | Micro motion effect display status ("0": not needed, "1": needed) | FALSE | string |
richMediaPictureType | Rich media picture display type (1: image, 2: video) | FALSE | string |
richMediaPictureFileNames | List of rich media picture file names (Maximum 3 when rich media picture type is 1, maximum 1 when rich media picture type is 2) | FALSE | array |
Request Example:
{
"miniappId": "1000083312531541234", // Mini App ID
"operatorId": "1000083312531541234", // Custom operator ID
"timeStamp": "1677577964000", // Timestamp for sending message (milliseconds)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // Signature, please follow the common signature code for generation
"data": {
"title": "This is a message title",
"text": "This is a message body",
"linkUrl": "This is a message link",
"microMotionEffectStatus": "0", // No need to display desktop micro motion effect
"richMediaPictureType": "1", // Image type
"richMediaPictureFileNames": ["6bc061fe27664e319fc12f0d799018bd.jpeg"] // List of displayed images
}
}
Response Status:
HTTP Status Code | Description |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
Response Parameters:
Parameter Name | Description | Type |
---|---|---|
code | Error status code | integer(int32) |
message | Error message | string |
sign | Return parameter signature information. Calculation method is the same as generating the signature | string |
data | Response data | json |
Details of the data
parameter in the response:
Parameter Name | Description | Type |
---|---|---|
messageId | Mini App message ID | string |
miniappId | Mini App ID | string |
Response Example:
{
"code": 0,
"message": null,
"data": {
"miniappId": "1000083312531541234",
"messageId": "100008331253154123420230228093159187"
},
"sign": "72B9C5CBF004636DB1CF057D2F9355F3EF9BD9D0E26CC67617F1AE4FDEE60C67"
}
2. Message Sending API
2.1 Introduction
Note: This API has usage restrictions. Through this interface, you can synchronously send messages to specified uniqueIds
. The list size of uniqueIds
is limited to 200. The default message sending limit for each mini program is 200 messages per second. If you need to adjust this limit, please contact the mini program platform.
This interface is suitable for scenarios where you need to send messages to a small batch of uniqueIds
.
2.2 API Documentation
API Endpoint: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/sendMessage
Request Method: POST
Request Data Type: application/x-www-form-urlencoded,application/json
Response Data Type: */*
Request Parameters:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
miniappId | Mini App ID | TRUE | string |
operatorId | Custom Operator ID | FALSE | string |
sign | Request Signature | TRUE | string |
timeStamp | Timestamp for Sending Message (in milliseconds) | FALSE | string |
data | Custom Business Data | TRUE | map |
Specific fields within the data
parameter:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
messageId | Message ID | TRUE | string |
uniqueIds | List of uniqueIds | TRUE | array |
Request Example:
{
"miniappId": "1000083312531541234", // Mini App ID
"operatorId": "1000083312531541234", // Custom Operator ID
"timeStamp": "1677577964000", // Timestamp for sending message (milliseconds)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // Signature, please follow the common signature code for generation
"data": {
"messageId": "100008331253154123420230228093159187",
"uniqueIds": [
"d8ae2bcd1e448394e606359d1d03aa910f6e4978fe01d2381971a058be0c767d",
"a9b2b1c5ec1cfd0e232069f820097c1cba0fcb93f90d1110cddb305fd8293ebe"
]
}
}
Response Status:
HTTP Status Code | Description |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
Response Parameters:
Parameter Name | Description | Type |
---|---|---|
code | Error status code | integer(int32) |
sign | Return parameter signature information. Calculation method is the same as generating the signature | string |
data | Response data | json |
Details of the data
parameter in the response:
Parameter Name | Description | Type |
---|---|---|
sendFailedUniqueInfos | array | array |
uniqueId | uniqueId | string |
failCode | Sending failed business code | string |
failDesc | Reason for sending failure business remarks | string |
Response Example:
{
"code": 0,
"message": null,
"data": {
"sendFailedUniqueInfos": [
{
"uniqueId": "xxxx",
"failCode": "70013",
"failDesc": "User has not recently visited this mini program"
}
]
},
"sign": "A05A50E851C4C256127480B227AABD0BFEBA0C7D2E395458DCC6BA93B4CB4A38"
}
3. Sending Messages (File)
3.1 Introduction
Note:
- The maximum size of the uploaded
uniqueId
file is 50MB (each line in the file represents auniqueId
, with line breaks as\r\n
). - This feature requires developers to apply for permission from the mini program platform.
By using uniqueId
files, you can asynchronously send messages to specific users, suitable for sending messages to a large number of users. This feature requires developers to perform three steps: obtaining the upload context, uploading the uniqueId
file, and calling the send message API.
3.2 API Documentation
3.2.1 Get Token for Uploading to OSS
Note: This upload token has an expiration time, currently set to 1200 seconds.
API Endpoint: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/sendMessageByFileContext
Request Method: POST
Request Data Type: application/x-www-form-urlencoded,application/json
Response Data Type: */*
Request Parameters:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
miniappId | Mini App ID | TRUE | string |
operatorId | Custom Operator ID | FALSE | string |
sign | Request Signature | TRUE | string |
timeStamp | Timestamp for Sending Message (in milliseconds) | FALSE | string |
data | Custom Business Data | TRUE | map |
Details of the data
parameter:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
contentLength | File size (in bytes), maximum limit is 50MB | TRUE | integer |
contentType | File type | TRUE | string |
fileName | File name | TRUE | string |
messageId | Message ID | TRUE | string |
Request Example:
{
"miniappId": "1000083312531541234", // Mini App ID
"operatorId": "1000083312531541234", // Custom Operator ID
"timeStamp": "1677577964000", // Timestamp for sending message (milliseconds)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // Signature, please follow the common signature code for generation
"data": {
"contentType": "text/plain",
"contentLength": 33000000, // File size (in bytes)
"fileName": "uniqueId.txt", // File name
"messageId": "100008331253154123420230228093159187"
}
}
Response Status:
HTTP Status Code | Description |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
Response Parameters:
Parameter Name | Description | Type |
---|---|---|
code | Error status code | integer(int32) |
data | Response data | json |
sign | Return parameter signature information. Calculation method is the same as generating the signature | string |
Details of the data
parameter in the response:
Parameter Name | Description | Type |
---|---|---|
miniappId | Mini App ID | string |
fileName | File name generated by the mini program platform | string |
accessUrl | Link to download the uploaded file. This link has a time limit, default is 1 hour | string |
storageType | Storage type. Default is OSS | string |
uploadMethod | Upload method. Only supports PUT | string |
uploadUrl | URL for uploading the file | string |
uploadHeader | Request headers to be carried during upload | object |
Details of uploadHeader
:
Parameter Name | Description | Type |
---|---|---|
authorization | Authorization string | string |
x-oss-date | Time to obtain the token (UTC+0) | string |
Host | OSS service domain address | string |
x-oss-security-token | OSS service access token | string |
Content-Length | File size | string |
Content-Type | File type | string |
Response Example:
{
"code": 0,
"message": null,
"data": {
"uploadHeader": {
"authorization": "xxx",
"x-oss-date": "Tue, 28 Feb 2023 10:39:23 GMT",
"Host": "xxx",
"x-oss-security-token": "xxx",
"Content-Length": "33000000",
"Content-Type": "text/plain"
},
"uploadMethod": "PUT",
"accessUrl": "https://xxx",
"uploadUrl": "https://xxx",
"storageType": "oss",
"fileName": "xxx.txt"
},
"sign": "EB72203BB81DB4DBF94C54631C8BCBA320AF68B6102A5D0E90AB5E904DB8C574"
}
3.2.2 Upload uniqueId
File to OSS
API Endpoint: The value of the uploadUrl
field obtained from the API 3.2.1 Get Token for Uploading to OSS
.
Request Method: PUT
Response Data Type: */*
Request Header Parameters:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
authorization | Authorization string | TRUE | string |
x-oss-date | Time to obtain the token (UTC+0) | TRUE | string |
Host | OSS service domain address | TRUE | string |
x-oss-security-token | OSS service access token | TRUE | string |
Content-Type | File type | TRUE | string |
Content-Length | File size | TRUE | string |
Request Example (Java):
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import java.io.File;
import java.io.IOException;
public class HttpClientUploadDemo {
/**
* Upload file
*/
public static void main(String[] args) {
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("Content-Type obtained in step 3.2.1");
RequestBody body = RequestBody.create(new File("Your file address"), mediaType);
Request request = new Request.Builder()
.url("UploadUrl obtained in step 3.2.1")
.put(body)
.addHeader("authorization", "Authorization obtained in step 3.2.1")
.addHeader("x-oss-date", "x-oss-date obtained in step 3.2.1")
.addHeader("Host", "Host obtained in step 3.2.1")
.addHeader("x-oss-security-token", "x-oss-security-token obtained in step 3.2.1")
.addHeader("Content-Length", "Content-Length obtained in step 3.2.1")
.addHeader("Content-Type", "Content-Type obtained in step 3.2.1")
.build();
Response response = null;
try {
response = client.newCall(request).execute();
} catch (IOException e) {
e.printStackTrace();
}
System.out.println("Response content : " + response);
}
}
Response Status:
HTTP Status Code | Description |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
3.2.3 Sending Messages via File
This API is for asynchronous invocation, and data task processing may have a delay.
API Endpoint: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/sendMessageByFile
Request Method: POST
Request Data Type: application/x-www-form-urlencoded,application/json
Response Data Type: */*
Request Parameters:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
miniappId | Mini App ID | TRUE | string |
operatorId | Custom Operator ID | FALSE | string |
sign | Request Signature | TRUE | string |
timeStamp | Timestamp for Sending Message (in milliseconds) | FALSE | string |
data | Custom Business Data | TRUE | map |
Request parameters within the data
:
Parameter Name | Description | Required | Data Type |
---|---|---|---|
messageFileName | The file name of the uniqueId . ⚠️ Note: This file name is the one generated by the mini program platform and obtained from the context retrieval interface. | TRUE | string |
messageId | Message ID | TRUE | string |
Request Example:
{
"miniappId": "1000083312531541234", // Mini App ID
"operatorId": "1000083312531541234", // Custom Operator ID
"timeStamp": "1677577964000", // Timestamp for sending message (milliseconds)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // Signature, please follow the common signature code for generation
"data": {
"messageFileName": "2183d1173dd341fea0ba60234fe56ce2.txt", // Note: This file name is obtained from the context retrieval interface, generated by the mini program platform.
"messageId": "100008331253154123420230228093159187"
}
}
Response Status:
HTTP Status Code | Description |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
Response Parameters:
Parameter Name | Description | Type |
---|---|---|
code | Error status code | integer(int32) |
message | Error message | string |
sign | Return parameter signature information. Calculation method is the same as generating the signature | string |
data | Response data | json |
Details of the data
parameter in the response:
Parameter Name | Description | Type |
---|---|---|
success | Whether the operation is successful | boolean |
Response Example:
{
"code": 0,
"message": null,
"data": {
"success": true
},
"sign": "881706EBAAB6BBA03676BD422420431F744887B5EDB81F2306153E2CD2D271B3"
}