HomeDocs
Skip to main content

Message API

Basic Information

Usage Limits

  1. 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).

  2. 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

CodeMessageDescription
2Request is too fast, and it is rate-limited!The message sending limit for each mini-program is 200 messages per second.
70001Mini-program is in the message blacklistThe mini-program platform does not allow rule-violating mini-programs to send messages.
70002Registration of mini-program message information failedRegistration of mini-program message information has failed.
70003Message information sending exceeded the limitMessage information sending exceeded the limit. There are temporary call limits for the interface.
70004Message information does not existMessage has not been registered on the message platform.
70005Sending messages in this time period is not allowedThe platform specifies that sending messages is not allowed in this time period. Currently, there are no restrictions.
70006The file for uniqueIds when sending messages via files does not existWhen sending messages via files, the file containing the required uniqueIds does not exist.
70007Message signature is abnormalMessage signature is abnormal.
70008Message permission is abnormalMessage permission is abnormal.
70009Message query is abnormalMessage information query is abnormal.
70010uniqueId does not matchWhen sending message information, the uniqueId does not match.
70011User has turned off message push permissionWhen sending message information, the user has turned off message push permission.
70012User has not recently visited the mini-programWhen sending message information, the user has not recently visited the mini-program.
70013User 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

NameField NameDescription
Mini-program IDminiappIdThe unique ID of the mini-program, used for unique identification of the mini-program.
Secret KeyaccessKeySecretAccessKeySecret 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 FieldsignThe 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

NameTypeDescription
Content-TypeStringapplication/json
Accept-TimezoneStringTimezone. 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 NameDescriptionRequiredData Type
miniappIdMini App IDTRUEstring
operatorIdOperator's Custom IDFALSEstring
signRequest SignatureTRUEstring
timeStampTimestamp for Sending Message (in milliseconds)FALSEstring
dataCustom Business DataTRUEmap

Specific fields within the data parameter:

Parameter NameDescriptionRequiredData Type
contentLengthFile size, maximum limit of 500KTRUEinteger
contentTypeFile type (supports png, jpeg, jpg, bmp, webp)TRUEstring
fileNameFile name (supports png, jpeg, jpg, bmp, webp)TRUEstring

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 CodeDescription
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

Response Parameters:

Parameter NameDescriptionType
codeError status codeinteger(int32)
messageError messagestring
signReturn parameter signature information. Calculation method is the same as generating the signaturestring
dataResponse datajson

Details of the data parameter in the response:

Parameter NameDescriptionType
miniappIdMini App IDstring
fileNameFile name generated by the Mini App platformstring
accessUrlLink to download the uploaded file. This link has a limited validity of 1 hour by defaultstring
storageTypeStorage type. Default is OSSstring
uploadMethodUpload method. Supports PUT onlystring
uploadUrlURL for uploading the filestring
uploadHeaderRequest headers required during uploadobject

Details of the uploadHeader parameter:

Parameter NameDescriptionType
authorizationAuthorization stringstring
x-oss-dateToken acquisition time (UTC+0)string
HostOSS service domain addressstring
x-oss-security-tokenOSS service access tokenstring
Content-LengthFile sizestring
Content-TypeFile typestring

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 NameDescriptionRequiredData Type
authorizationAuthorization stringTRUEstring
x-oss-dateToken acquisition time (UTC+0)TRUEstring
HostOSS service domain addressTRUEstring
x-oss-security-tokenOSS service access tokenTRUEstring
Content-TypeFile typeTRUEstring

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 CodeDescription
200OK
201Created
401Unauthorized
403Forbidden
404Not 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 NameDescriptionRequiredData TypeSchema
miniappIdMini App IDTRUEstring
operatorIdCustom Operator IDFALSEstring
signRequest SignatureTRUEstring
timeStampTimestamp for Sending Message (in milliseconds)FALSEstring
dataCustom Business DataTRUEmapRegisterMessageInfoRequestDTO

Specific fields within the data parameter:

Parameter NameDescriptionRequiredData Type
linkUrlMessage redirect linkTRUEstring
textMessage body textFALSEstring
titleMessage titleTRUEstring
microMotionEffectStatusMicro motion effect display status ("0": not needed, "1": needed)FALSEstring
richMediaPictureTypeRich media picture display type (1: image, 2: video)FALSEstring
richMediaPictureFileNamesList of rich media picture file names (Maximum 3 when rich media picture type is 1, maximum 1 when rich media picture type is 2)FALSEarray

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 CodeDescription
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

Response Parameters:

Parameter NameDescriptionType
codeError status codeinteger(int32)
messageError messagestring
signReturn parameter signature information. Calculation method is the same as generating the signaturestring
dataResponse datajson

Details of the data parameter in the response:

Parameter NameDescriptionType
messageIdMini App message IDstring
miniappIdMini App IDstring

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 NameDescriptionRequiredData Type
miniappIdMini App IDTRUEstring
operatorIdCustom Operator IDFALSEstring
signRequest SignatureTRUEstring
timeStampTimestamp for Sending Message (in milliseconds)FALSEstring
dataCustom Business DataTRUEmap

Specific fields within the data parameter:

Parameter NameDescriptionRequiredData Type
messageIdMessage IDTRUEstring
uniqueIdsList of uniqueIdsTRUEarray

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 CodeDescription
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

Response Parameters:

Parameter NameDescriptionType
codeError status codeinteger(int32)
signReturn parameter signature information. Calculation method is the same as generating the signaturestring
dataResponse datajson

Details of the data parameter in the response:

Parameter NameDescriptionType
sendFailedUniqueInfosarrayarray
uniqueIduniqueIdstring
failCodeSending failed business codestring
failDescReason for sending failure business remarksstring

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:

  1. The maximum size of the uploaded uniqueId file is 50MB (each line in the file represents a uniqueId, with line breaks as \r\n).
  2. 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 NameDescriptionRequiredData Type
miniappIdMini App IDTRUEstring
operatorIdCustom Operator IDFALSEstring
signRequest SignatureTRUEstring
timeStampTimestamp for Sending Message (in milliseconds)FALSEstring
dataCustom Business DataTRUEmap

Details of the data parameter:

Parameter NameDescriptionRequiredData Type
contentLengthFile size (in bytes), maximum limit is 50MBTRUEinteger
contentTypeFile typeTRUEstring
fileNameFile nameTRUEstring
messageIdMessage IDTRUEstring

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 CodeDescription
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

Response Parameters:

Parameter NameDescriptionType
codeError status codeinteger(int32)
dataResponse datajson
signReturn parameter signature information. Calculation method is the same as generating the signaturestring

Details of the data parameter in the response:

Parameter NameDescriptionType
miniappIdMini App IDstring
fileNameFile name generated by the mini program platformstring
accessUrlLink to download the uploaded file. This link has a time limit, default is 1 hourstring
storageTypeStorage type. Default is OSSstring
uploadMethodUpload method. Only supports PUTstring
uploadUrlURL for uploading the filestring
uploadHeaderRequest headers to be carried during uploadobject

Details of uploadHeader:

Parameter NameDescriptionType
authorizationAuthorization stringstring
x-oss-dateTime to obtain the token (UTC+0)string
HostOSS service domain addressstring
x-oss-security-tokenOSS service access tokenstring
Content-LengthFile sizestring
Content-TypeFile typestring

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 NameDescriptionRequiredData Type
authorizationAuthorization stringTRUEstring
x-oss-dateTime to obtain the token (UTC+0)TRUEstring
HostOSS service domain addressTRUEstring
x-oss-security-tokenOSS service access tokenTRUEstring
Content-TypeFile typeTRUEstring
Content-LengthFile sizeTRUEstring

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 CodeDescription
200OK
201Created
401Unauthorized
403Forbidden
404Not 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 NameDescriptionRequiredData Type
miniappIdMini App IDTRUEstring
operatorIdCustom Operator IDFALSEstring
signRequest SignatureTRUEstring
timeStampTimestamp for Sending Message (in milliseconds)FALSEstring
dataCustom Business DataTRUEmap

Request parameters within the data:

Parameter NameDescriptionRequiredData Type
messageFileNameThe 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.TRUEstring
messageIdMessage IDTRUEstring

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 CodeDescription
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

Response Parameters:

Parameter NameDescriptionType
codeError status codeinteger(int32)
messageError messagestring
signReturn parameter signature information. Calculation method is the same as generating the signaturestring
dataResponse datajson

Details of the data parameter in the response:

Parameter NameDescriptionType
successWhether the operation is successfulboolean

Response Example:

{
"code": 0,
"message": null,
"data": {
"success": true
},
"sign": "881706EBAAB6BBA03676BD422420431F744887B5EDB81F2306153E2CD2D271B3"
}
Privacy agreementDeveloper agreementcontact us: developer_service.mi@transsion.com © 2024 MiniApp. All Rights Reserved.