pushplus 开放接口文档

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的使用及生成方式说明:

  1. 用户需要提前配置自己的secretKey,建议至少32位数字、英文大小写随机组合。将请求的服务器IP添加到安全IP列表中。接口使用的token同发送消息的token。

  2. 建议第三方开发者使用中控服务器统一获取和刷新AccessKey,其他业务逻辑服务器所使用的AccessKey均来自于该中控服务器,不应该各自去刷新,否则容易造成冲突,导致AccessKey覆盖而影响业务;

  3. 目前AccessKey的有效期通过返回的expireIn来传达,目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新AccessKey。在刷新过程中,中控服务器可对外继续输出的老AccessKey,此时pushplus后台会保证在5分钟内,新老AccessKey都可用,这保证了第三方业务的平滑过渡;

  4. AccessKey的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新AccessKey的接口,这样便于业务服务器在API调用获知AccessKey已超时的情况下,可以触发AccessKey的刷新流程。

  5. 对于可能存在风险的调用,在开发者进行获取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
}
  • 请求参数说明
参数名称是否必填默认值说明
current1当前所在分页数
pageSize20每页大小,最大值为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
  }
}
  • 请求参数说明
参数名称是否必填默认值说明
current1当前所在分页数
pageSize20每页大小,最大值为50
topicType0群组类型;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群组编号
forever0二维码类型;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
  }
}
  • 请求参数说明
参数名称是否必填默认值说明
current1当前所在分页数
pageSize20每页大小,最大值为50
topicId0群组编号
  • 响应内容
{
  "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
}
  • 请求参数说明
参数名称是否必填默认值说明
current1当前所在分页数
pageSize20每页大小,最大值为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列表
  • 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传参
  • 请求参数说明
参数名称是否必填默认值说明
webhookIdwebhook编号
  • 响应内容
{
  "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"
}
  • 请求参数说明
参数名称是否必填默认值说明
webhookCodewebhook编码
webhookNamewebhook名称
webhookTypewebhook类型;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"
}
  • 请求参数说明
参数名称是否必填默认值说明
idwebhook编号
webhookCodewebhook编码
webhookNamewebhook名称
webhookTypewebhook类型;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
}
  • 9
    点赞
  • 17
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值