API 文档参考

该 API 文档为 mirai-api-http 通用接口文档, 对于所有内置的(built-in)接口适配器(adapter)都适用的相同规则.

对于因调用逻辑的不同而产生不同接口数据的的地方, 在对应 adapter 文档中会明确指出

参考阅读:

Adapter: 接口适配器

状态码
获取插件信息
- 关于
- 获取登录账号
缓存操作
- 通过messageId获取消息
获取账号信息
消息发送与撤回
文件操作
账号管理
- 删除好友
群管理
群公告
事件处理
Console命令

扩展阅读:

事件类型一览
消息类型一览

状态码

大部分 API 返回的数据包含一个 code 字段的状态码, 分别代表不同的响应状态.
所有API返回状态码的意义都一致.

以下为状态码一览:

状态码	原因
0	正常
1	错误的verify key
2	指定的Bot不存在
3	Session失效或不存在
4	Session未认证(未激活)
5	发送消息目标不存在(指定对象不存在)
6	指定文件不存在，出现于发送本地图片
10	无操作权限，指Bot没有对应操作的限权
20	Bot被禁言，指Bot当前无法向指定群发送消息
30	消息过长
400	错误的访问，如参数错误等

获取插件信息

关于

请求:

无

响应:

{
  "code":0,
  "msg":"",
  "data":{
    "version":"v1.0.0"
  }
}

获取登录账号

请求:

无

响应:

{
  "code":0,
  "msg":"",
  "data":[
    123456789,
    987654321,
    1145141919
  ]
}

缓存操作

通过messageId获取消息

请求:

名字	类型	可选	举例	说明
sessionKey	String	true	YourSessionKey	你的session key
messageId	Int	false	1234567890	获取消息的messageId
target	Long	false	1234567890	好友id或群id

响应:

当该messageId没有被缓存或缓存失效时，返回code 5(指定对象不存在)

{
  "code":0,
  "msg":"",
  "data":{
    "type":"FriendMessage",         // 消息类型：GroupMessage或FriendMessage或TempMessage或各类Event
    "messageChain":[                // 消息链，是一个消息对象构成的数组
    {
      "type":"Source",
      "id":123456,
      "time":123456789
    },
    {
      "type":"Plain",
      "text":"Miral牛逼"
    }
    ],
    "sender":{                    // 发送者信息
      "id":1234567890,            // 发送者的QQ号码
      "nickname":"",              // 发送者的昵称
      "remark":""                 // 发送者的备注
    }
  }
}

获取账号信息

获取好友列表

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key

响应:

{
  "code":0,
  "msg":"",
  "data":[
    {
      "id":123456789,
      "nickname":"",
      "remark":""
    },
    {
      "id":987654321,
      "nickname":"",
      "remark":""
    }
  ]
}

获取群列表

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key

响应:

{
  "code":0,
  "msg":"",
  "data":[
    {
      "id":123456789,
      "name":"群名1",
      "permission":"MEMBER" // bot 在群中的权限
    },
    {
      "id":987654321,
      "name":"群名2",
      "permission":"MEMBER"
    }
  ]
}

获取群成员列表

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key
target	false	123456789	指定群的群号

响应:

{
  "code":0,
  "msg":"",
  "data":[
    {
      "id":1234567890,
      "memberName":"",
      "permission":"MEMBER",  // 群成员在群中的权限
      "specialTitle":"群头衔",
      "joinTimestamp":12345678,
      "lastSpeakTimestamp":8765432,
      "muteTimeRemaining":0,
      "group":{
        "id":12345,
        "name":"群名1",
        "permission":"MEMBER" // bot 在群中的权限
      }
    },
    {
      "id":9876543210,
      "memberName":"",
      "specialTitle":"群头衔",
      "permission":"OWNER",
      "joinTimestamp":12345678,
      "lastSpeakTimestamp":8765432,
      "muteTimeRemaining":0,
      "group":{
        "id":54321,
        "name":"群名2",
        "permission":"MEMBER"
      }
    }
  ]
}

获取最新群成员列表

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key
target	false	123456789	指定群的群号
memberIds	false	[9876543210]	群成员账号, 为空表示获取所有

响应:

{
  "code":0,
  "msg":"",
  "data":[
    {
      "id":9876543210,
      "memberName":"",
      "specialTitle":"群头衔",
      "permission":"OWNER",
      "joinTimestamp":12345678,
      "lastSpeakTimestamp":8765432,
      "muteTimeRemaining":0,
      "group":{
        "id":123456789,
        "name":"群名2",
        "permission":"MEMBER"
      }
    }
  ]
}

获取Bot资料

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key

响应:

{
  "nickname":"nickname",
  "email":"email",
  "age":18,
  "level":1,
  "sign":"mirai",
  "sex":"UNKNOWN" // UNKNOWN, MALE, FEMALE
}

获取好友资料

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key
target	false	123456789	指定好友账号

响应:

{
  "nickname":"nickname",
  "email":"email",
  "age":18,
  "level":1,
  "sign":"mirai",
  "sex":"UNKNOWN" // UNKNOWN, MALE, FEMALE
}

获取群成员资料

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key
target	false	123456789	指定群的群号
memberId	false	987654321	群成员QQ号码

响应:

{
  "nickname":"nickname",
  "email":"email",
  "age":18,
  "level":1,
  "sign":"mirai",
  "sex":"UNKNOWN" // UNKNOWN, MALE, FEMALE
}

获取QQ用户资料

请求:

名字	可选	举例	说明
sessionKey	true	YourSessionKey	你的session key
target	false	987654321	要查询的QQ号码

响应:

{
  "nickname":"nickname",
  "email":"email",
  "age":18,
  "level":1,
  "sign":"mirai",
  "sex":"UNKNOWN" // UNKNOWN, MALE, FEMALE
}

消息发送与撤回

发送好友消息

请求:

{
  "sessionKey":"YourSession",
  "target":987654321,
  "messageChain":[
    { "type":"Plain", "text":"hello\n" },
    { "type":"Plain", "text":"world" },
	{ "type":"Image", "url":"https://i0.hdslb.com/bfs/album/67fc4e6b417d9c68ef98ba71d5e79505bbad97a1.png" }
  ]
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
target	Long	true	987654321	可选，发送消息目标好友的QQ号
qq	Long	true	987654321	可选，target与qq中需要有一个参数不为空，当target不为空时qq将被忽略，同target
quote	Int	true	135798642	引用一条消息的messageId进行回复
messageChain	Array	false	[]	消息链，是一个消息对象构成的数组

响应:

{
  "code":0,
  "msg":"success",
  "messageId":1234567890 // 一个Int类型属性，标识本条消息，用于撤回和引用回复
}

发送群消息

请求:

{
  "sessionKey":"YourSession",
  "target":987654321,
  "messageChain":[
    { "type":"Plain", "text":"hello\n" },
    { "type":"Plain", "text":"world" },
    { "type":"Image", "url":"https://i0.hdslb.com/bfs/album/67fc4e6b417d9c68ef98ba71d5e79505bbad97a1.png" }
  ]
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
target	Long	true	987654321	可选，发送消息目标群的群号
group	Long	true	987654321	可选，target与group中需要有一个参数不为空，当target不为空时group将被忽略，同target
quote	Int	true	135798642	引用一条消息的messageId进行回复
messageChain	Array	false	[]	消息链，是一个消息对象构成的数组

响应:

{
  "code":0,
  "msg":"success",
  "messageId":1234567890 // 一个Int类型属性，标识本条消息，用于撤回和引用回复
}

发送临时会话消息

请求

{
  "sessionKey":"YourSession",
  "qq":1413525235,
  "group":987654321,
  "messageChain":[
    { "type":"Plain", "text":"hello\n" },
    { "type":"Plain", "text":"world" }
  ]
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
qq	Long	false	987654321	临时会话对象QQ号
group	Long	false	987654321	临时会话群号
quote	Int	true	135798642	引用一条消息的messageId进行回复
messageChain	Array	false	[]	消息链，是一个消息对象构成的数组

响应:

{
  "code":0,
  "msg":"success",
  "messageId":1234567890 // 一个Int类型属性，标识本条消息，用于撤回和引用回复
}

发送头像戳一戳消息

请求:

{
  "sessionKey":"YourSessionKey",
  "target":123456,
  "subject":654321,
  "kind":"Group"
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	戳一戳的目标, QQ号, 可以为 bot QQ号
subject	false	Long	987654321	戳一戳接受主体(上下文), 戳一戳信息会发送至该主体, 为群号/好友QQ号
kind	false	String	"Group"	上下文类型, 可选值 `Friend`, `Group`, `Stranger`

响应:

{
    "code": 0,
    "msg": "success"
}

撤回消息

请求

{
  "sessionKey":"YourSession",
  "target":987654321,
  "messageId":12345
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
messageId	Int	false	12345	需要撤回的消息的messageId
target	Long	false	987654321	好友id或群id

响应:

{
  "code":0,
  "msg":"success"
}

获取漫游消息

请求

{
  "timeStart": 0,
  "timeEnd": 0,
  "target": 123456789,
}

名字	类型	可选	说明
timeStart	Long	false	起始时间, UTC+8 时间戳, 单位为秒. 可以为 0, 即表示从可以获取的最早的消息起. 负数将会被看是 0.
timeEnd	Long	false	结束时间, UTC+8 时间戳, 单位为秒. 可以为 Long.MAX_VALUE, 即表示到可以获取的最晚的消息为止. 低于 timeStart 的值将会被看作是 timeStart 的值.
target	Long	false	漫游消息对象，好友id，目前仅支持好友漫游消息

响应:

{
  "code":0,
  "msg":"success",
  "data":[]
}

data 为 #消息链数组

文件操作

目前仅支持群文件的操作, 所有好友文件的字段为保留字段

查看文件列表

请求

{
  "sessionKey":"YourSession",
  "id": "",
  "path": null,
  "target":987654321,
  "group":null,
  "qq":null,
  "withDownloadInfo":true,
  "offset": 0,
  "size": 1
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
id	String	false	""	文件夹id, 空串为根目录
path	String	true	null	文件夹路径, 文件夹允许重名, 不保证准确, 准确定位使用 id
target	Long	true	987654321	群号或好友QQ号
group	Long	true	987654321	群号
qq	Long	true	987654321	好友QQ号
withDownloadInfo	Boolean	true	true	是否携带下载信息，额外请求，无必要不要携带
offset	Long	true	1	分页偏移
size	Long	true	10	分页大小

响应:

{
  "code":0,
  "msg":"",
  "data": [
    {
      "name":"setu.png",
      "id":"/12314d-1wf13-a98ffa",
      "path":"/setu.png",
      "parent":null,
      "contact":{
        "id":123123,
        "name":"setu qun",
        "permission":"OWNER"
      },
      "isFile":true,
      "isDictionary":false,
      "isDirectory":false,
      "sha1":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "md5":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "downloadTimes":10,
      "uploaderId":123456789,
      "uploadTime":1631153749,
      "lastModifyTime":1631153749,
      "downloadInfo":{
        "sha1":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "md5":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "downloadTimes":10,
        "uploaderId":123456789,
        "uploadTime":1631153749,
        "lastModifyTime":1631153749,
        "url":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      }
    }
  ]
}

名字	类型	说明
data	Array	文件对象数组
data.name	String	文件名
data.id	String	文件ID
data.parent	Object	文件对象, 递归类型. null 为存在根目录
data.contact	Object	群信息或好友信息
data.contact	Object	群信息或好友信息
data.isFile	Boolean	是否文件
data.isDictionary	Boolean	~~是否文件夹~~(弃用)
data.isDirectory	Boolean	是否文件夹
downloadInfo	Object	文件下载信息
downloadInfo.sha1	String	文件sha1校验
downloadInfo.md5	String	文件md5校验
downloadInfo.url	String	文件下载url

获取文件信息

请求

{
  "sessionKey":"YourSession",
  "id": "",
  "path": null,
  "target":987654321,
  "group":null,
  "qq":null,
  "withDownloadInfo":true
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
id	String	false	""	文件id,空串为根目录
path	String	true	null	文件夹路径, 文件夹允许重名, 不保证准确, 准确定位使用 id
target	Long	true	987654321	群号或好友QQ号
group	Long	true	987654321	群号
qq	Long	true	987654321	好友QQ号
withDownloadInfo	Boolean	true	true	是否携带下载信息，额外请求，无必要不要携带

响应:

{
  "code":0,
  "msg":"",
  "data": {
    "name":"setu.png",
    "id":"/12314d-1wf13-a98ffa",
    "path":"/setu.png",
    "parent":null,
    "contact":{
      "id":123123,
      "name":"setu qun",
      "permission":"OWNER"
    },
    "isFile":true,
    "isDictionary":false,
    "isDirectory":false,
    "sha1":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "md5":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "downloadTimes":10,
    "uploaderId":123456789,
    "uploadTime":1631153749,
    "lastModifyTime":1631153749,
    "downloadInfo":{
      "sha1":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "md5":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "downloadTimes":10,
      "uploaderId":123456789,
      "uploadTime":1631153749,
      "lastModifyTime":1631153749,
      "url":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    }
  }
}

名字	类型	说明
data	Object	文件信息
data.name	String	文件名
data.id	String	文件ID
data.parent	Object	文件对象, 递归类型. null 为存在根目录
data.contact	Object	群信息或好友信息
data.contact	Object	群信息或好友信息
data.isFile	Boolean	是否文件
data.isDictionary	Boolean	~~是否文件夹~~(弃用)
data.isDirectory	Boolean	是否文件夹
downloadInfo	Object	文件下载信息
downloadInfo.sha1	String	文件sha1校验
downloadInfo.md5	String	文件md5校验
downloadInfo.url	String	文件下载url

创建文件夹

请求

{
  "sessionKey":"YourSession",
  "id": "",
  "path": null,
  "target":987654321,
  "group":null,
  "qq":null,
  "directoryName": "newDirectoryName"
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
id	String	false	""	父目录id,空串为根目录
path	String	true	null	文件夹路径, 文件夹允许重名, 不保证准确, 准确定位使用 id
target	Long	true	987654321	群号或好友QQ号
group	Long	true	987654321	群号
qq	Long	true	987654321	好友QQ号
directoryName	String	false	""	新建文件夹名

响应:

{
  "code":0,
  "msg":"",
  "data": {
    "name":"setu",
    "id":"/12314d-1wf13-a98ffa",
    "path":"/setu",
    "parent":null,
    "contact":{
      "id":123123,
      "name":"setu qun",
      "permission":"OWNER"
    },
    "isFile":false,
    "isDictionary":true,
    "isDirectory":true
  }
}

返回新建文件夹的信息

上传文件

未通用，仅 http 支持

删除文件

请求

{
  "sessionKey":"YourSession",
  "id": "",
  "path": null,
  "target":987654321,
  "group":null,
  "qq":null
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
id	String	false	""	删除文件id
path	String	true	null	文件夹路径, 文件夹允许重名, 不保证准确, 准确定位使用 id
target	Long	true	987654321	群号或好友QQ号
group	Long	true	987654321	群号
qq	Long	true	987654321	好友QQ号

响应:

{
  "code":0,
  "msg":"success"
}

移动文件

请求

{
  "sessionKey":"YourSession",
  "id": "",
  "path": null,
  "target":987654321,
  "group":null,
  "qq":null,
  "moveTo": "/23fff2-3fwe-ga12eds",
  "moveToPath": null
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
id	String	false	""	移动文件id
path	String	false	null	文件夹路径, 文件夹允许重名, 不保证准确, 准确定位使用 id
target	Long	true	987654321	群号或好友QQ号
group	Long	true	987654321	群号
qq	Long	true	987654321	好友QQ号
moveTo	String	true	"/23fff2-3fwe-ga12eds"	移动目标文件夹id
moveToPath	String	true	null	移动目标文件路径, 文件夹允许重名, 不保证准确, 准确定位使用 moveTo

响应:

{
  "code":0,
  "msg":"success"
}

重命名文件

请求

{
  "sessionKey":"YourSession",
  "id": "",
  "path": null,
  "target":987654321,
  "group":null,
  "qq":null,
  "renameTo": "setu"
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
id	String	false	""	重命名文件id
path	String	false	null	文件夹路径, 文件夹允许重名, 不保证准确, 准确定位使用 id
target	Long	true	987654321	群号或好友QQ号
group	Long	true	987654321	群号
qq	Long	true	987654321	好友QQ号
renameTo	Long	true	987654321	新文件名

响应:

{
  "code":0,
  "msg":"success"
}

账号管理

删除好友

请求:

{
  "sessionKey":"YourSessionKey",
  "target":1234567890
}

名字	类型	可选	举例	说明
sessionKey	String	true	YourSessionKey	你的session key
target	Long	false	1234567890	删除好友的QQ号码

响应:

{
  "code":0,
  "msg":""
}

群管理

禁言群成员

请求:

{
  "sessionKey":"YourSessionKey",
  "target":123456789,
  "memberId":987654321,
  "time":1800
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	指定群的群号
memberId	false	Long	987654321	指定群员QQ号
time	true	Int	1800	禁言时长，单位为秒，最多30天，默认为0

响应:

{
  "code":0,
  "msg":"success"
}

解除群成员禁言

请求:

{
  "sessionKey":"YourSessionKey",
  "target":123456789,
  "memberId":987654321
}

响应

{
  "code":0,
  "msg":"success"
}

移除群成员

请求:

{
  "sessionKey":"YourSessionKey",
  "target":123456789,
  "memberId":987654321,
  "block":false,
  "msg":"您已被移出群聊"
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	指定群的群号
memberId	false	Long	987654321	指定群员QQ号
block	true	Boolean	false	移除后拉黑，默认为 false
msg	true	String	""	信息

响应

{
  "code":0,
  "msg":"success"
}

退出群聊

请求:

{
  "sessionKey":"YourSessionKey",
  "target":123456789
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	退出的群号

响应

{
  "code":0,
  "msg":"success"
}

bot为该群群主时退出失败并返回code 10(无操作权限)

全体禁言

请求:

{
  "sessionKey":"YourSessionKey",
  "target":123456789
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	指定群的群号

响应:

{
  "code":0,
  "msg":"success"
}

解除全体禁言

请求:

同全体禁言

响应

同全体禁言

设置群精华消息

请求:

{
  "sessionKey":"YourSessionKey",
  "target":1234567
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
messageId	false	Int	1234567	精华消息的messageId
target	false	Long	1234567890	群id

响应:

{
  "code":0,
  "msg":"success"
}

获取群设置

请求:

名字	可选	类型	举例	说明
sessionKey	true	String	YourSessionKey	你的session key
target	false	Long	123456789	指定群的群号

响应

{
  "name":"群名称",
  "announcement":"群公告",
  "confessTalk":true,
  "allowMemberInvite":true,
  "autoApprove":true,
  "anonymousChat":true,
  "muteAll":true
}

修改群设置

请求:

{
  "sessionKey":"YourSessionKey",
  "target":123456789,
  "config":{
    "name":"群名称",
    "announcement":"群公告",
    "confessTalk":true,
    "allowMemberInvite":true,
    "autoApprove":true,
    "anonymousChat":true
  }
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	指定群的群号
config	false	Object	{}	群设置
name	true	String	"Name"	群名
announcement	true	String	"Announcement"	群公告
confessTalk	true	Boolean	true	是否开启坦白说
allowMemberInvite	true	Boolean	true	是否允许群员邀请
autoApprove	true	Boolean	true	是否开启自动审批入群
anonymousChat	true	Boolean	true	是否允许匿名聊天

响应:

{
  "code":0,
  "msg":"success"
}

获取群员设置

使用此方法获取群员资料

请求:

名字	可选	类型	举例	说明
sessionKey	true	String	YourSessionKey	你的session key
target	false	Long	123456789	指定群的群号
memberId	false	Long	987654321	群员QQ号

响应:

{
  "id":987654321,
  "memberName":"群名片",
  "specialTitle":"群头衔",
  "permission":"OWNER",
  "joinTimestamp":12345678,
  "lastSpeakTimestamp":8765432,
  "muteTimeRemaining":0,
  "active": {
    "rank": 6,            // 群活跃等级 1-6
    "point": 100,         // 群活跃积分
    "honors": ["群聊之火"],// 群荣誉表示
    "temperature": 100    // 群荣誉等级 LV 1-100
  },
  "group":{
    "id":12345,
    "name":"群名1",
    "permission":"MEMBER" // bot 在群中的权限
  }
}

修改群员设置

使用此方法修改群员资料（需要有相关限权）

请求:

{
    "sessionKey": "YourSessionKey",
    "target": 123456789,
    "memberId": 987654321,
    "info": {
        "name": "群名片",
        "specialTitle": "群头衔"
    }
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	指定群的群号
memberId	false	Long	987654321	群员QQ号
info	false	Object	{}	群员资料
name	true	String	"Name"	群名片，即群昵称
specialTitle	true	String	"Title"	群头衔

响应: 返回统一状态码

{
  "code":0,
  "msg":"success"
}

修改群员管理员

使用此方法修改群员的管理员权限（需要有群主限权）

请求:

{
    "sessionKey": "YourSessionKey",
    "target": 123456789,
    "memberId": 987654321,
    "assign": true
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
target	false	Long	123456789	指定群的群号
memberId	false	Long	987654321	群员QQ号
assign	false	Boolean	true	是否设置为管理员

响应: 返回统一状态码

{
  "code":0,
  "msg":"success"
}

群公告

获取群公告

此方法获取指定群公告列表

请求

名字	可选	类型	举例	说明
id	false	Long	123456789	群号
offset	true	Long	0	分页参数
size	true	Long	10	分页参数，默认10

响应

{
  "code": 0,
  "msg": "",
  "data":[
    {
      "group":{"id": 123456789, "name": "group name", "permission": "ADMINISTRATOR"},
      "content": "群公告内容",
      "senderId": 987654321,        // 发布者账号
      "fid": "公告唯一id",
      "allConfirmed": false,        // 是否所有群成员已确认
      "confirmedMembersCount": 0,   // 确认群成员人数
      "publicationTime": 1645085843 // 发布时间
    }
  ]
}

发布群公告

此方法向指定群发布群公告

请求

{
  "target": 123456789,
  "content": "测试公告内容",
  "pinned": true
}

名字	可选	类型	举例	说明
target	false	Long	123456789	群号
content	false	String	""	公告内容
sendToNewMember	true	Boolean	false	是否发送给新成员
pinned	true	Boolean	false	是否置顶
showEditCard	true	Boolean	false	是否显示群成员修改群名片的引导
showPopup	true	Boolean	false	是否自动弹出
requireConfirmation	true	Boolean	false	是否需要群成员确认
imageUrl	false	String	null	公告图片url
imagePath	false	String	null	公告图片本地路径
imageBase64	false	String	null	公告图片base64编码

响应

{
  "code": 0,
  "msg": "",
  "data":[
    {
      "group":{"id": 123456789, "name": "group name", "permission": "ADMINISTRATOR"},
      "content": "群公告内容",
      "senderId": 987654321,        // 发布者账号
      "fid": "公告唯一id",
      "allConfirmed": false,        // 是否所有群成员已确认
      "confirmedMembersCount": 0,   // 确认群成员人数
      "publicationTime": 1645085843 // 发布时间
    }
  ]
}

删除群公告

此方法删除指定群中一条公告

请求

{
  "id": 123456789,
  "fid": "群公告唯一id",
}

名字	可选	类型	举例	说明
id	false	Long	123456789	群号
fid	false	String	""	群公告唯一id

响应: 返回统一状态码

{
  "code":0,
  "msg":"success"
}

事件处理

添加好友申请

处理添加好友申请事件(NewFriendRequestEvent)

{
  "sessionKey":"YourSessionKey",
  "eventId":12345678,
  "fromId":123456,
  "groupId":654321,
  "operate":0,
  "message":""
}

名字	类型	说明
sessionKey	String	session key
eventId	Long	响应申请事件的标识
fromId	Long	事件对应申请人QQ号
groupId	Long	事件对应申请人的群号，可能为0
operate	Int	响应的操作类型
message	String	回复的信息

operate	说明
0	同意添加好友
1	拒绝添加好友
2	拒绝添加好友并添加黑名单，不再接收该用户的好友申请

用户入群申请（Bot需要有管理员权限）

处理用户入群申请事件(MemberJoinRequestEvent)

{
  "sessionKey":"YourSessionKey",
  "eventId":12345678,
  "fromId":123456,
  "groupId":654321,
  "operate":0,
  "message":""
}

名字	类型	说明
sessionKey	String	session key
eventId	Long	响应申请事件的标识
fromId	Long	事件对应申请人QQ号
groupId	Long	事件对应申请人的群号
operate	Int	响应的操作类型
message	String	回复的信息

operate	说明
0	同意入群
1	拒绝入群
2	忽略请求
3	拒绝入群并添加黑名单，不再接收该用户的入群申请
4	忽略入群并添加黑名单，不再接收该用户的入群申请

Bot被邀请入群申请

处理 Bot被邀请入群申请事件(BotInvitedJoinGroupRequestEvent)

{
  "sessionKey":"YourSessionKey",
  "eventId":12345678,
  "fromId":123456,
  "groupId":654321,
  "operate":0,
  "message":""
}

名字	类型	说明
sessionKey	String	session key
eventId	Long	事件标识
fromId	Long	邀请人（好友）的QQ号
groupId	Long	被邀请进入群的群号
operate	Int	响应的操作类型
message	String	回复的信息

operate	说明
0	同意邀请
1	拒绝邀请

Console命令

执行命令

请求:

{
  "sessionKey":"YourSessionKey",
  "command":[]
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
command	false	Array	[]	命令与参数

console 支持以不同消息类型作为指令的参数, 执行命令需要以消息类型作为参数, 若执行纯文本的命令, 构建多个 Plain 格式的消息 console 会将第一个消息作为指令名, 后续消息作为参数具体参考 console 文档

响应:

{
  "code":0,
  "msg":"success"
}

注册命令

请求:

{
  "name":"shutdown",
  "alias":["close", "exit"],
  "usage":"/shutdown <nil>",
  "description":"Shutdown console."
}

名字	可选	类型	举例	说明
sessionKey	true	String	"YourSessionKey"	你的session key
name	false	String	"shutdown"	指令名
alias	true	Array	[]	指令别名
usage	false	String	""	使用说明
description	false	String	""	命令描述

注册的指令会直接覆盖已有的指令(包括 console 内置的指令)

响应:

{
  "code":0,
  "msg":"success"
}

命令接收

命令被调用时, 会触发 CommandExecutedEvent

Files

API.md

Latest commit

History

API.md

File metadata and controls

API 文档参考

状态码

获取插件信息

关于

请求:

响应:

获取登录账号

请求:

响应:

缓存操作

通过messageId获取消息

请求:

响应:

获取账号信息

获取好友列表

请求:

响应:

获取群列表

请求:

响应:

获取群成员列表

请求:

响应:

获取最新群成员列表

请求:

响应:

获取Bot资料

请求:

响应:

获取好友资料

请求:

响应:

获取群成员资料

请求:

响应:

获取QQ用户资料

请求:

响应:

消息发送与撤回

发送好友消息

请求:

响应:

发送群消息

请求:

响应:

发送临时会话消息

请求

响应:

发送头像戳一戳消息

请求:

响应:

撤回消息

请求

响应:

获取漫游消息

请求

响应:

文件操作

查看文件列表

请求

响应:

获取文件信息

请求

响应:

创建文件夹

请求

响应:

上传文件

删除文件

请求

响应:

移动文件

请求

响应: