HomeDocs
跳到主要内容

消息 API

基础信息​

使用限制​

  1. 提供以接口方式批量发送消息。用户可以通过接口传入 uniqueId 列表,列表大小限制为 200,每个小程序每秒可发送的消息条数限制为 200 条(默认值,如需调整,请联系小程序平台)。

  2. 提供以文件方式的发送消息,该功能需申请。该功能为异步处理,任务存在延时(50w 数据大约延时 5 分钟)

使用说明​

消息平台的 API 参考主要介绍接口的请求语法、相关参数含义以及请求和返回示例。

错误码​

codemessage说明
2请求过快,被限流了!每个小程序每秒可发送的消息条数限制为 200 条
70001小程序在消息黑名单中小程序的平台不允许违规小程序发送消息
70002注册小程序消息信息失败注册小程序消息信息失败
70003消息信息发送超过限制消息信息发送超过限制。暂时接口调用有次数限制
70004消息信息不存在消息未在消息平台注册
70005该时间段不允许发送消息平台指定的时间段不允许发送消息。目前无限制。
70006通过文件发送消息的 uniqueIds 文件不存在通过文件发送消息时,需要发送的 uniqueId 的文件不存在
70007消息签名异常消息签名异常
70008消息权限异常消息权限异常
70009消息查询异常message 信息查询异常
70010uniqueId 不匹配发送 message 信息时 uniqueId 不匹配
70011用户已关闭消息推送权限发送 message 信息时,用户已关闭消息推送权限
70012用户最近未访问过该小程序发送 message 信息时,发送的用户最近未访问过该小程序
70013用户近三天内已经被该小程序发送过消息!发送 message 信息时,该用户近三天内已经被该小程序发送过消息

资源术语​

名称字段名描述
小程序 IDminiappId小程序的唯一 Id,用于唯一识别小程序。
密钥字段accessKeySecretAccessKeySecret 是用户用于加密签名字符串和小程序平台用来验证签名字符串的密钥,AccessKeySecret 必须保密。
签名字段sign小程序消息平台签名字段。小程序平台服务端会校验签名。计算方式为:结合 AccessKeySecret 对请求参数进行 sha256 算法加密。

公共 HTTP 头定义​

名称类型描述
Content-Type字符串application/json
Accept-Timezone字符串时区。仅支持标准 UTC 时区。比如 UTC+0

公共签名​

1. 简介​

接入小程序消息平台需要的签名。

2. 代码示例​

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";
// 自定义业务数据。data中添加的参数为自定义业务字段中的字段。比如注册消息接口中的{"title": "这是个消息标题","text": "这是个消息正文","linkUrl": "这是个消息链接","microMotionEffectStatus": "0"}
Map<String, Object> data = new TreeMap<>();
data.put("自定义业务数据data中的参数名称","自定义业务数据data中的参数的值"); // 比如:data.put("title", "这是个消息标题");data.put("text", "这是个消息正文")
// secretAccessKey从运营平台获取
String secretAccessKey = "你的 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");
}

/**
* sha256加密
*
* @param str 要加密的字符串
* @return 加密后的字符串
*/
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("进行sha256加密失败!massage: %s%n", e.getMessage());
}
return encodeStr;
}

/**
* sha256加密 将byte转为16进制
*
* @param bytes 字节码
* @return 加密后的字符串
*/
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) {
//第一位的进行补0操作
stringBuilder.append("0");
}
stringBuilder.append(tempStr);
}
return stringBuilder.toString();
}
}

消息功能​

1. 消息配置​

1.1 简介​

注册消息信息配置接口。在发送消息给指定用户之前,需要优先生成消息。

1.2 接口文档​

1.2.1 获取上传注册消息的富文本图片文件至 oss 的 token 的接口​

注意:此上传 token 具有有效期,目前有效期 1200s

接口地址: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/registerMessageRichMediaPictureContext

请求方式: POST

请求数据类型: application/x-www-form-urlencoded,application/json

响应数据类型: */*

请求参数:

参数名称参数说明是否必须数据类型
miniappId小程序 idTRUEstring
operatorId操作者自定义 IdFALSEstring
sign请求签名TRUEstring
timeStamp发送消息的时间戳(毫秒)FALSEstring
data自定义业务数据TRUEmap

data 参数具体字段:

参数名称参数说明是否必须数据类型
contentLength文件大小,最大限制 500KTRUEinteger
contentType文件类型(只支持 png,jpeg,jpg,bmp,webp 格式)TRUEstring
fileName文件名称(只支持 png,jpeg,jpg,bmp,webp 格式)TRUEstring

请求示例:

{
"miniappId": "1000083312531541234", //小程序id
"operatorId": "1000083312531541234", //自定义操作人标记
"timeStamp": "1677577964000", //发送消息的时间戳(毫秒)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", //签名,请参照公共签名代码进行生成
"data": {
"contentType": "image/jpeg",
"contentLength": 169120, //文件大小(字节)
"fileName": "xxx.jpeg" //文件名称
}
}

响应状态:

HTTP 状态码说明
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

响应参数:

参数名称参数说明类型
code错误状态码integer(int32)
message错误消息string
sign返回参数签名信息。计算方式同生成签名方式string
data响应数据json

响应数据 data 具体内容说明:

参数名称参数说明类型
miniappId小程序 IDstring
fileName小程序平台重新生成的文件名称string
accessUrl上传后下载文件的链接。此链接有有效期限制。默认 1 个小时string
storageType存储类型。默认 ossstring
uploadMethod上传方法。仅支持 PUTstring
uploadUrl用来上传文件的 urlstring
uploadHeader上传时需要携带的请求头object

uploadHeader 具体内容说明:

参数名称参数说明类型
authorization授权字符串string
x-oss-date获取 token 的时间(UTC+0)string
Hostoss 服务域名地址string
x-oss-security-tokenoss 服务权限 tokenstring
Content-Length文件大小string
Content-Type文件类型string

响应示例:

{
"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 上传注册消息的富文本图片文件至 oss 的接口​

接口地址: 1.2.1 获取上传注册消息的富文本图片文件至 oss 的 token 的接口中,拿到的 uploadUrl 字段的值。

请求方式: PUT

响应数据类型: */*

请求 Header 参数:

参数名称参数说明是否必须数据类型
authorization授权字符串TRUEstring
x-oss-date获取 token 的时间(UTC+0)TRUEstring
Hostoss 服务域名地址TRUEstring
x-oss-security-tokenoss 服务权限 tokenTRUEstring
Content-Type文件类型TRUEstring

请求 demo:

//引入的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 {

/**
* 上传文件
*/
public static void main(String[] args) {
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("1.2.1步骤中获得的Content-Type");
RequestBody body = RequestBody.create(new File("你的文件地址"), mediaType);
Request request = new Request.Builder()
.url("1.2.1步骤中获得的uploadUrl")
.put(body)
.addHeader("authorization", "1.2.1步骤中获得的authorization")
.addHeader("x-oss-date", "1.2.1步骤中获得的x-oss-date")
.addHeader("Host", "1.2.1步骤中获得的Host")
.addHeader("x-oss-security-token", "1.2.1步骤中获得的x-oss-security-token")
.addHeader("Content-Length", "1.2.1步骤中获得的Content-Length")
.addHeader("Content-Type", "1.2.1步骤中获得的Content-Type")
.build();
Response response = null;
try {
response = client.newCall(request).execute();
} catch (IOException e) {
e.printStackTrace();
}
System.out.println("Response content : " + response);
}
}

响应状态:

HTTP 状态码说明
200OK
201Created
401Unauthorized
403Forbidden
404Not Found
1.2.3 注册消息接口​

接口地址: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/registerMessage

请求方式: POST

请求数据类型: application/x-www-form-urlencoded,application/json

响应数据类型: */*

请求参数:

参数名称参数说明是否必须数据类型schema
miniappId小程序 idTRUEstring
operatorId操作者自定义 IdFALSEstring
sign请求签名TRUEstring
timeStamp发送消息的时间戳(毫秒)FALSEstring
data自定义业务数据TRUEmapRegisterMessageInfoRequestDTO

data 参数具体说明:

参数名称参数说明是否必须数据类型
linkUrl消息跳转地址TRUEstring
text消息正文FALSEstring
title消息标题TRUEstring
microMotionEffectStatus微动效展示状态("0":不需要展示,"1":需要展示)FALSEstring
richMediaPictureType富媒体图片展示类型(1:图片 2:视频)FALSEstring
richMediaPictureFileNames富媒体图片文件名列表(富媒体图片展示类型为 1 时,最大可传 3 条;富媒体图片展示类型为 2 时,最大可传 1 条)FALSEarray

请求示例:

{
"miniappId": "1000083312531541234", //小程序id
"operatorId": "1000083312531541234", //自定义操作人标记
"timeStamp": "1677577964000", //发送消息的时间戳(毫秒)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", //签名,请参照公共签名代码进行生成
"data": {
"title": "这是个消息标题",
"text": "这是个消息正文",
"linkUrl": "这是个消息链接",
"microMotionEffectStatus": "0", //无需展示桌面微动效
"richMediaPictureType": "1", //图片类型
"richMediaPictureFileNames": ["6bc061fe27664e319fc12f0d799018bd.jpeg"] //展示的图片列表
}
}

响应状态:

HTTP 状态码说明
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

响应参数:

参数名称参数说明类型
code错误状态码integer(int32)
message错误消息string
sign返回参数签名信息。计算方式同生成签名方式string
data响应数据json

相应参数 data 具体说明:

参数名称参数说明类型
messageId小程序消息 idstring
miniappId小程序 IDstring

响应示例:

{
"code": 0,
"message": null,
"data": {
"miniappId": "1000083312531541234",
"messageId": "100008331253154123420230228093159187"
},
"sign": "72B9C5CBF004636DB1CF057D2F9355F3EF9BD9D0E26CC67617F1AE4FDEE60C67"
}

2. 发送消息(接口)​

2.1 简介​

注意:该接口有使用限制。通过接口传入 uniqueId 列表,列表大小限制为 200,每个小程序每秒可发送的消息条数限制为 200 条(默认值,如需调整,请联系小程序平台)。

通过接口形式同步发送消息给指定的 uniqueIds,适合发送消息给小批量 uniqueId 的场景。

2.2 接口文档​

接口地址: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/sendMessage

请求方式: POST

请求数据类型: application/x-www-form-urlencoded,application/json

响应数据类型: */*

请求参数:

参数名称参数说明是否必须数据类型
miniappId小程序 idTRUEstring
operatorId操作者自定义 IdFALSEstring
sign请求签名TRUEstring
timeStamp发送消息的时间戳(毫秒)FALSEstring
data自定义业务数据TRUEmap

请求参数 data 具体说明:

参数名称参数说明是否必须数据类型
messageId消息 IdTRUEstring
uniqueIdsuniqueId 列表TRUEarray

请求示例:

{
"miniappId": "1000083312531541234", // 小程序id
"operatorId": "1000083312531541234", // 自定义操作人标记
"timeStamp": "1677577964000", // 发送消息的时间戳(毫秒)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // 签名,请参照公共签名代码进行生成
"data": {
"messageId": "100008331253154123420230228093159187",
"uniqueIds": [
"d8ae2bcd1e448394e606359d1d03aa910f6e4978fe01d2381971a058be0c767d",
"a9b2b1c5ec1cfd0e232069f820097c1cba0fcb93f90d1110cddb305fd8293ebe"
]
}
}

响应状态:

HTTP 状态码说明
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

响应参数:

参数名称参数说明类型
code错误状态码integer(int32)
sign返回参数签名信息。计算方式同生成签名方式string
data响应数据json

相应参数 data 具体说明:

参数名称参数说明类型
sendFailedUniqueInfosarrayarray
uniqueIduniqueIdstring
failCode发送失败业务码string
failDesc发送失败业务备注原因string

响应示例:

{
"code": 0,
"message": null,
"data": {
"sendFailedUniqueInfos": [
{
"uniqueId": "xxxx",
"failCode": "70013",
"failDesc": "用户最近未访问过该小程序"
}
]
},
"sign": "A05A50E851C4C256127480B227AABD0BFEBA0C7D2E395458DCC6BA93B4CB4A38"
}

3. 发送消息(文件)​

3.1 简介​

注意:

  1. 上传的 uniqueId 的文件最大 50M(文件每一行为一个 uniqueId,换行符为\r\n).
  2. 此功能需要开发者向小程序平台申请使用。

通过 uniqueId 文件方式,异步发送信息给指定用户,适合发送给大批量用户。此功能需要开发者执行三步。获取上传 context -> 上传 uniqueId 文件 -> 调用发送消息接口。

3.2 接口文档​

3.2.1 获取上传 oss 的 token 的接口​

注意:此上传 token 具有有效期,目前有效期 1200s

接口地址: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/sendMessageByFileContext

请求方式: POST

请求数据类型: application/x-www-form-urlencoded,application/json

响应数据类型: */*

请求参数:

参数名称参数说明是否必须数据类型
miniappId小程序 idTRUEstring
operatorId操作者自定义 IdFALSEstring
sign请求签名TRUEstring
timeStamp发送消息的时间戳(毫秒)FALSEstring
data自定义业务数据TRUEmap

data 参数具体说明:

参数名称参数说明是否必须数据类型
contentLength文件大小(byte),最大限制 50MTRUEinteger
contentType文件类型TRUEstring
fileName文件名称TRUEstring
messageId消息 IdTRUEstring

请求示例:

{
"miniappId": "1000083312531541234", // 小程序id
"operatorId": "1000083312531541234", // 自定义操作人标记
"timeStamp": "1677577964000", // 发送消息的时间戳(毫秒)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // 签名,请参照公共签名代码进行生成
"data": {
"contentType": "text/plain",
"contentLength": 33000000, // 文件大小(字节)
"fileName": "uniqueId.txt", // 文件名称
"messageId": "100008331253154123420230228093159187"
}
}

响应状态:

HTTP 状态码说明
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

响应参数:

参数名称参数说明类型
code错误状态码integer(int32)
data响应数据json
sign返回参数签名信息。计算方式同生成签名方式string

响应参数 data 具体说明:

参数名称参数说明类型
miniappId小程序 IDstring
fileName小程序平台重新生成的文件名称string
accessUrl上传后下载文件的链接。此链接有有效期限制。默认 1 个小时string
storageType存储类型。默认 ossstring
uploadMethod上传方法。仅支持 PUTstring
uploadUrl用来上传文件的 urlstring
uploadHeader上传时需要携带的请求头object

uploadHeader 具体说明:

参数名称参数说明类型
authorization授权字符串string
x-oss-date获取 token 的时间(UTC+0)string
Hostoss 服务域名地址string
x-oss-security-tokenoss 服务权限 tokenstring
Content-Length文件大小string
Content-Type文件类型string

响应示例:

{
"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 上传 uniqueId 文件至 oss 的接口​

接口地址: 3.2.1 获取上传 oss 的 token 的接口中,拿到的 uploadUrl 字段的值。

请求方式: PUT

响应数据类型: */*

请求 Header 参数:

参数名称参数说明是否必须数据类型
authorization授权字符串TRUEstring
x-oss-date获取 token 的时间(UTC+0)TRUEstring
Hostoss 服务域名地址TRUEstring
x-oss-security-tokenoss 服务权限 tokenTRUEstring
Content-Type文件类型TRUEstring
Content-Length文件大小TRUEstring

请求 demo:

//引入的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 {

/**
* 上传文件
*/
public static void main(String[] args) {
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("3.2.1步骤中获得的Content-Type");
RequestBody body = RequestBody.create(new File("你的文件地址"), mediaType);
Request request = new Request.Builder()
.url("3.2.1步骤中获得的uploadUrl")
.put(body)
.addHeader("authorization", "3.2.1步骤中获得的authorization")
.addHeader("x-oss-date", "3.2.1步骤中获得的x-oss-date")
.addHeader("Host", "3.2.1步骤中获得的Host")
.addHeader("x-oss-security-token", "3.2.1步骤中获得的x-oss-security-token")
.addHeader("Content-Length", "3.2.1步骤中获得的Content-Length")
.addHeader("Content-Type", "3.2.1步骤中获得的Content-Type")
.build();
Response response = null;
try {
response = client.newCall(request).execute();
} catch (IOException e) {
e.printStackTrace();
}
System.out.println("Response content : " + response);
}
}

响应状态:

HTTP 状态码说明
200OK
201Created
401Unauthorized
403Forbidden
404Not Found
3.2.3 通过文件发送消息的接口​

该接口为异步方式调用,数据任务处理存在延时。

接口地址: https://api.dlight-app.com/miniapp/messageplatform/openapi/message/cmd/sendMessageByFile

请求方式: POST

请求数据类型: application/x-www-form-urlencoded,application/json

响应数据类型: */*

请求参数:

参数名称参数说明是否必须数据类型
miniappId小程序 idTRUEstring
operatorId操作者自定义 IdFALSEstring
sign请求签名TRUEstring
timeStamp发送消息的时间戳(毫秒)FALSEstring
data自定义业务数据TRUEmap

请求参数 data 具体说明:

参数名称参数说明是否必须数据类型
messageFileNameuniqueId 的文件名称. ⚠️ 注意:此文件名为从获取 context 接口返回的文件名,是小程序平台生成的文件名。TRUEstring
messageId消息 IdTRUEstring

请求示例:

{
"miniappId": "1000083312531541234", // 小程序id
"operatorId": "1000083312531541234", // 自定义操作人标记
"timeStamp": "1677577964000", // 发送消息的时间戳(毫秒)
"sign": "1347FF225BDBA2E7D26BE03BC2B2CD9A2B6A32271102BAEDA5AACDC184FF0781", // 签名,请参照公共签名代码进行生成
"data": {
"messageFileName": "2183d1173dd341fea0ba60234fe56ce2.txt", // 注意:此文件名为从获取context接口返回的文件名,是小程序平台生成的文件名。
"messageId": "100008331253154123420230228093159187"
}
}

响应状态:

HTTP 状态码说明
200OK
201Created
401Unauthorized
403Forbidden
404Not Found

响应参数:

参数名称参数说明类型
code错误状态码integer(int32)
message错误消息string
sign返回参数签名信息。计算方式同生成签名方式string
data响应数据json

响应参数 data 具体说明:

参数名称参数说明类型
success是否操作成功boolean

响应示例:

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