pushplus 开放接口文档 V1.0
1.0 接口更新日期:2021-12-21
通过accessKey调用消息、用户、群组、渠道配置和功能设置接口
pushplus官网地址:http://www.pushplus.plus
文档说明
为了更方便的让用户使用pushplus功能,现将原本需要在界面上操作的功能开放出来,包括消息、用户、群组、设置等能力。原本发送消息的接口是通过用户token来调用的,考虑到这种方式安全性较低,容易泄露,所以本次开放的接口采用AccessKey的校验方式。在请求接口的时候,需要在header中带上key名为“access-key”的内容,否则会请求失败。
由于开放接口权限较高,泄露后会给用户造成严重后果,所以默认是禁用状态,需要用户手动的在开发设置中开启,并在调用AccessKey接口之前配置好secretKey和安全IP地址。
一. 获取AccessKey
1. 使用说明
AccessKey是开放接口的全局唯一的接口调用凭证,调用其他各接口都需要使用AccessKey。开发者需要进行妥善保存。AccessKey的存储至少要保留32个字符空间。AccessKey的有效期目前为2个小时,需定时刷新,重复获取将导致上次获取的AccessKey失效。
pushplus的开放接口调用所需的AccessKey的使用及生成方式说明:
-
用户需要提前配置自己的secretKey,建议至少32位数字、英文大小写随机组合。将请求的服务器IP添加到安全IP列表中。接口使用的token同发送消息的token。
-
建议第三方开发者使用中控服务器统一获取和刷新AccessKey,其他业务逻辑服务器所使用的AccessKey均来自于该中控服务器,不应该各自去刷新,否则容易造成冲突,导致AccessKey覆盖而影响业务;
-
目前AccessKey的有效期通过返回的expireIn来传达,目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新AccessKey。在刷新过程中,中控服务器可对外继续输出的老AccessKey,此时pushplus后台会保证在5分钟内,新老AccessKey都可用,这保证了第三方业务的平滑过渡;
-
AccessKey的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新AccessKey的接口,这样便于业务服务器在API调用获知AccessKey已超时的情况下,可以触发AccessKey的刷新流程。
-
对于可能存在风险的调用,在开发者进行获取AccessKey调用时请求的服务器需要在用户设置的安全IP列表内,否则会返回编码为403的错误。
2. 接口调用说明
- 请求地址:https://www.pushplus.plus/api/common/openApi/getAccessKey
- 请求方式:POST
- 请求参数:
{
"token": "d90******c20",
"secretKey": "qLc******gdk"
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
token | 是 | 无 | 用户令牌,同发送消息接口令牌 |
secretKey | 是 | 无 | 用户密钥 |
{
"code": 200,
"msg": "请求成功",
"data": {
"accessKey": "d7b******62f",
"expiresIn": 7200
}
}
参数名称 | 类型 | 说明 |
---|
accessKey | 字符串 | 访问令牌,后续请求需加到header中 |
expiresIn | 数字 | 过期时间,过期后需要重新获取 |
二. 消息接口
1. 消息列表
- 请求地址:https://www.pushplus.plus/api/open/message/list
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"current": 1,
"pageSize": 20
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
current | 否 | 1 | 当前所在分页数 |
pageSize | 否 | 20 | 每页大小,最大值为50 |
{
"code": 200,
"msg": "请求成功",
"data": {
"pageNum": 1,
"pageSize": 20,
"total": 8,
"pages": 1,
"list": [
{
"topicName": "",
"messageType": 1,
"title": "XXX",
"shortCode": "a01***648",
"channel": "wechat",
"updateTime": "2021-12-08 20:19:02"
}
]
}
}
参数名称 | 类型 | 说明 |
---|
pageNum | 数字 | 当前页码 |
pageSize | 数字 | 分页大小 |
total | 数字 | 总行数 |
pages | 数字 | 总页数 |
list | 数组 | 消息列表 |
参数名称 | 类型 | 说明 |
---|
channel | 字符串 | 消息发送渠道; wechat-微信公众号,mail-邮件,cp-企业微信应用,webhook-第三方webhook |
messageType | 数字 | 消息类型;1-一对一消息,2-一对多消息 |
shortCode | 字符串 | 消息短链码;可用于查询消息发送结果 |
title | 字符串 | 消息标题 |
topicName | 字符串 | 群组名称,一对多消息才有值 |
updateTime | 日期 | 更新日期 |
2. 查询消息发送结果
- 请求地址:https://www.pushplus.plus/api/open/message/sendMessageResult?shortCode=a018***648
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数,url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
shortCode | 是 | 无 | 消息短链码 |
{
"code": 200,
"msg": "请求成功",
"data": {
"status": 2,
"errorMessage": "",
"updateTime": "2021-12-08 12:19:02"
}
}
参数名称 | 类型 | 说明 |
---|
status | 数字 | 消息投递状态;0-未投递,1-发送中,2-已发送,3-发送失败 |
errorMessage | 字符串 | 发送失败原因 |
updateTime | 日期 | 更新时间 |
三. 用户接口
1. 获取token
- 请求地址:https://www.pushplus.plus/api/open/user/token
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:无
- 响应内容
{
"code": 200,
"msg": "请求成功",
"data": "604******f0b"
}
data中直接返回当前用户的token。
2. 个人资料详情
- 请求地址:https://www.pushplus.plus/api/open/user/myInfo
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数,url传参
- 请求参数:无
- 响应内容
{
"code": 200,
"msg": "请求成功",
"data": {
"openId": "o0a******A3Y",
"unionId": "oGV******NZg",
"nickName": "陈大人",
"headImgUrl": "http://thirdwx.qlogo.cn/mmopen/ajNV***gg/132",
"userSex": 1,
"token": "604******f0b",
"phoneNumber": "13******4",
"email": "admin@xxx.com",
"emailStatus": 1,
"birthday": "1990-01-01",
"points": 2
}
}
参数名称 | 类型 | 说明 |
---|
openId | 字符串 | 用户微信的openId |
unionId | 字符串 | 用户微信的unionId |
nickName | 字符串 | 昵称 |
headImgUrl | 字符串 | 头像 |
userSex | 数字 | 性别;0-未设置,1-男,2-女 |
token | 字符串 | 用户令牌 |
phoneNumber | 字符串 | 手机号 |
email | 字符串 | 邮箱 |
emailStatus | 数字 | 邮箱验证状态;0-未验证,1-待验证,2-已验证 |
birthday | 日期 | 生日 |
points | 数字 | 用户积分 |
3. 获取解封剩余时间
- 请求地址:https://www.pushplus.plus/api/open/user/userLimitTime
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: 无
- 响应内容
{
"code": 200,
"msg": "请求成功",
"data": {
"sendLimit": 1,
"userLimitTime": ""
}
}
参数名称 | 类型 | 说明 |
---|
sendLimit | 数字 | 发送限制状态;1-无限制,2-短期限制,3-永久限制 |
userLimitTime | 字符串 | 解封时间 |
四. 群组接口
1. 群组列表
- 请求地址:https://www.pushplus.plus/api/open/topic/list
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"current": 0,
"pageSize": 0,
"params": {
"topicType": 0
}
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
current | 否 | 1 | 当前所在分页数 |
pageSize | 否 | 20 | 每页大小,最大值为50 |
topicType | 是 | 0 | 群组类型;0-我创建的,1-我加入的 |
{
"code": 200,
"msg": "请求成功",
"data": {
"pageNum": 1,
"pageSize": 20,
"total": 3,
"pages": 1,
"list": [
{
"topicId": 4,
"topicCode": "群组编码",
"topicName": "群组名称",
"createTime": "2021-12-24 01:19:15"
}
]
}
}
参数名称 | 类型 | 说明 |
---|
pageNum | 数字 | 当前页码 |
pageSize | 数字 | 分页大小 |
total | 数字 | 总行数 |
pages | 数字 | 总页数 |
list | 数组 | 群组列表 |
参数名称 | 类型 | 说明 |
---|
topicId | 数字 | 群组编号 |
topicCode | 字符串 | 群组编码 |
topicName | 字符串 | 群组名称 |
createTime | 日期 | 创建时间 |
2. 获取我创建的群组详情
- 请求地址:https://www.pushplus.plus/api/open/topic/detail?topicId=1
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
topicId | 是 | 无 | 群组编号 |
{
"code": 200,
"msg": "请求成功",
"data": {
"topicId": 1,
"topicName": "测试",
"topicCode": "123456",
"qrCodeImgUrl": "",
"contact": "联系方式",
"introduction": "群组简介",
"receiptMessage": "关注后回复",
"createTime": "2021-02-10 16:58:01",
"topicUserCount": 1
}
}
参数名称 | 类型 | 说明 |
---|
topicId | 数字 | 群组编号 |
topicCode | 字符串 | 群组编码 |
topicName | 字符串 | 群组名称 |
qrCodeImgUrl | 字符串 | 永久二维码图片地址 |
contact | 字符串 | 联系方式 |
introduction | 字符串 | 群组简介 |
receiptMessage | 字符串 | 加入后回复内容 |
createTime | 日期 | 创建时间 |
topicUserCount | 字符串 | 群组订阅人总数 |
4. 获取我加入的群详情
- 请求地址:https://www.pushplus.plus/api/open/topic/joinTopicDetail?topicId=1
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
topicId | 是 | 无 | 群组编号 |
{
"code": 200,
"msg": "请求成功",
"data": {
"topicName": "string",
"topicCode": "string",
"topicId": 3,
"contact": "string",
"introduction": "string",
"createTime": "2021-03-29 20:11:50"
}
}
参数名称 | 类型 | 说明 |
---|
topicId | 数字 | 群组编号 |
topicCode | 字符串 | 群组编码 |
topicName | 字符串 | 群组名称 |
contact | 字符串 | 联系方式 |
introduction | 字符串 | 群组简介 |
createTime | 日期 | 加入时间 |
5. 新增群组
- 请求地址:https://www.pushplus.plus/api/open/topic/add
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"topicCode": "pushplus",
"topicName": "推送加",
"contact": "联系方式",
"introduction": "群组简介",
"receiptMessage": "关注后回复"
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
topicCode | 是 | 无 | 群组编码 |
topicName | 是 | 无 | 群组名称 |
contact | 是 | 无 | 联系方式 |
introduction | 是 | 无 | 群组简介 |
receiptMessage | 否 | 无 | 加入后回复内容 |
{
"code": 200,
"msg": "执行成功",
"data": 2
}
data中返回新建群组的群组编号。
6. 获取群组二维码
- 请求地址:https://www.pushplus.plus/api/open/topic/qrCode?topicId=1&forever=0
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
topicId | 是 | 无 | 群组编号 |
forever | 否 | 0 | 二维码类型;0-临时二维码,1-永久二维码 |
{
"code": 200,
"msg": "请求成功",
"data": {
"qrCodeImgUrl": "https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQ******cA",
"forever": 0
}
}
参数名称 | 类型 | 说明 |
---|
qrCodeImgUrl | 数字 | 群组二维码图片路径 |
forever | 字符串 | 二维码类型;0-临时二维码,1-永久二维码 |
7. 退出群组
- 请求地址:https://www.pushplus.plus/api/open/topic/exitTopic?topicId=1
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
topicId | 是 | 无 | 群组编号 |
{
"code": 200,
"msg": "请求成功",
"data": "退订成功"
}
五. 群组用户接口
1. 获取群组内用户
- 请求地址:https://www.pushplus.plus/api/open/topicUser/subscriberList
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"current": 1,
"pageSize": 20,
"params": {
"topicId": 1
}
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
current | 否 | 1 | 当前所在分页数 |
pageSize | 否 | 20 | 每页大小,最大值为50 |
topicId | 是 | 0 | 群组编号 |
{
"code": 200,
"msg": "请求成功",
"data": {
"pageNum": 1,
"pageSize": 20,
"total": 1,
"pages": 1,
"list": [
{
"id": 1,
"nickName": "昵称",
"openId": "o0a******wZo",
"headImgUrl": "http://thirdwx.qlogo.cn/mmopen/Q3a******32",
"userSex": -1,
"havePhone": 0,
"isFollow": 1,
"emailStatus": 0
}
]
}
}
参数名称 | 类型 | 说明 |
---|
pageNum | 数字 | 当前页码 |
pageSize | 数字 | 分页大小 |
total | 数字 | 总行数 |
pages | 数字 | 总页数 |
list | 数组 | 用户列表 |
参数名称 | 类型 | 说明 |
---|
id | 数字 | 用户编号;可用于删除用户 |
nickName | 字符串 | 昵称 |
openId | 字符串 | 用户微信openId |
headImgUrl | 字符串 | 头像url地址 |
userSex | 数字 | 性别;0-未设置,1-男,2-女 |
havePhone | 数字 | 是否绑定手机;0-未绑定,1-已绑定 |
isFollow | 数字 | 是否关注微信公众号;0-未关注,1-已关注 |
emailStatus | 数字 | 邮箱验证状态;0-未验证,1-待验证,2-已验证 |
2. 删除群组内用户
- 请求地址:https://www.pushplus.plus/api/open/topicUser/deleteTopicUser?topicRelationId=1
- 请求方式:POST
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
topicRelationId | 是 | 无 | 用户编号 |
{
"code": 200,
"msg": "请求成功",
"data": "删除成功"
}
六. 渠道配置接口
1. 获取webhook列表
- 请求地址:https://www.pushplus.plus/api/open/webhook/list
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"current": 1,
"pageSize": 20
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
current | 否 | 1 | 当前所在分页数 |
pageSize | 否 | 20 | 每页大小,最大值为50 |
{
"code": 200,
"msg": "请求成功",
"data": {
"pageNum": 1,
"pageSize": 20,
"total": 5,
"pages": 1,
"list": [
{
"id": 1,
"webhookCode": "pushplus",
"webhookName": "webhook推送",
"webhookType": 1,
"webhookUrl": "url",
"createTime": "2021-12-23 09:00:56",
}
]
}
}
参数名称 | 类型 | 说明 |
---|
pageNum | 数字 | 当前页码 |
pageSize | 数字 | 分页大小 |
total | 数字 | 总行数 |
pages | 数字 | 总页数 |
list | 数组 | webhook列表 |
参数名称 | 类型 | 说明 |
---|
id | 数字 | webhook编号 |
webhookCode | 字符串 | webhook编码 |
webhookName | 字符串 | webhook名称 |
webhookType | 数字 | webhook类型;1-企业微信,2-钉钉,3-飞书,4-server酱 |
webhookUrl | 字符串 | 调用的url地址 |
createTime | 日期 | 创建日期 |
2. webhook详情
- 请求地址:https://www.pushplus.plus/api/open/webhook/detail?webhookId=1
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
webhookId | 是 | 无 | webhook编号 |
{
"code": 200,
"msg": "请求成功",
"data": {
"id": 1,
"webhookName": "推送加",
"webhookCode": "pushplus",
"webhookUrl": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=63******8f",
"webhookType": 1,
"createTime": "2021-12-23 09:00:56"
}
}
参数名称 | 类型 | 说明 |
---|
id | 数字 | webhook编号 |
webhookCode | 字符串 | webhook编码 |
webhookName | 字符串 | webhook名称 |
webhookType | 数字 | webhook类型;1-企业微信,2-钉钉,3-飞书,4-server酱 |
webhookUrl | 字符串 | 调用的url地址 |
createTime | 日期 | 创建日期 |
3. 新增webhook
- 请求地址:https://www.pushplus.plus/api/open/webhook/add
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"webhookCode": "pushplus",
"webhookName": "推送加",
"webhookType": 1,
"webhookUrl": "url"
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
webhookCode | 是 | 无 | webhook编码 |
webhookName | 是 | 无 | webhook名称 |
webhookType | 是 | 无 | webhook类型;1-企业微信,2-钉钉,3-飞书,4-server酱 |
webhookUrl | 是 | 无 | 调用的url地址 |
{
"code": 200,
"msg": "请求成功",
"data": 2
}
data中返回新建webhook编号。
4. 修改webhook配置
- 请求地址:https://www.pushplus.plus/api/open/webhook/edit
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"id": 1,
"webhookCode": "pushplus",
"webhookName": "企业微信",
"webhookType": 1,
"webhookUrl": "https://url"
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
id | 是 | 无 | webhook编号 |
webhookCode | 是 | 无 | webhook编码 |
webhookName | 是 | 无 | webhook名称 |
webhookType | 是 | 无 | webhook类型;1-企业微信,2-钉钉,3-飞书,4-server酱 |
webhookUrl | 是 | 无 | 调用的url地址 |
{
"code": 200,
"msg": "请求成功",
"data": "修改成功"
}
七. 功能设置接口
1. 获取默认发送渠道
- 请求地址:https://www.pushplus.plus/api/open/setting/getUserSettings
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: 无
- 响应内容
{
"code": 200,
"msg": "请求成功",
"data": {
"defaultChannel": "wechat",
"defaultChannelTxt": "微信公众号",
"defaultWebhook": "",
"sendLimit": 0,
"recevieLimit": 0
}
}
参数名称 | 类型 | 说明 |
---|
defaultChannel | 字符串 | 默认渠道编码 |
defaultChannelTxt | 字符串 | 默认渠道名称 |
defaultWebhook | 字符串 | 渠道参数 |
sendLimit | 数字 | 发送限制;0-无限制,1-禁止所有渠道发送,2-限制微信渠道,3-限制邮件渠道 |
recevieLimit | 数字 | 接收限制;0-接收全部,1-不接收消息 |
2. 修改默认发送渠道
- 请求地址:https://www.pushplus.plus/api/open/setting/changeDefaultChannel
- 请求方式:POST
- Content-Type: application/json
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数:
{
"defaultChannel": "wechat",
"defaultWebhook": ""
}
参数名称 | 是否必填 | 默认值 | 说明 |
---|
defaultChannel | 是 | 无 | 默认渠道;wechat-微信公众号,mail-邮件,cp-企业微信应用,webhook-第三方webhook |
defaultWebhook | 否 | 无 | 渠道参数;webhook和cp渠道需要填写具体的webhook编号或自定义编码 |
{
"code": 200,
"msg": "执行成功",
"data": null
}
3. 修改接收消息限制
- 请求地址:https://www.pushplus.plus/api/open/setting/changeRecevieLimit?recevieLimit=0
- 请求方式:GET
- (header) access-key: d7b******62f(获取到的AccessKey)
- 请求参数: url传参
- 请求参数说明
参数名称 | 是否必填 | 默认值 | 说明 |
---|
recevieLimit | 是 | 无 | 接收消息限制;0-接收全部,1-不接收消息 |
{
"code": 200,
"msg": "执行成功",
"data": null
}