Http Adapter

提供基于轮询的 http 接口

配置文件

adapterSettings:
  http:
    ## http server 监听的本地地址
    ## 一般为 localhost 即可, 如果多网卡等情况，自定设置
    host: localhost

    ## http server 监听的端口
    ## 与 websocket server 可以重复, 由于协议与路径不同, 不会产生冲突
    port: 8080

    ## 配置跨域, 默认允许来自所有域名
    cors: [*]

    ## 未读队列最大容量，为 0 时不接收任何消息
    unreadQueueMaxSize: 100

接口一览

专有接口

专有接口为该 adapter 特有的接口

• 认证与会话
  • 认证
  • 绑定
  • 获取会话信息
  • 释放
  • 传递(重要)
• 接收消息与事件
  • 查看队列大小
  • 获取队列头部
  • 获取队列尾部
  • 查看队列头部
  • 查看队列尾部
  • 消息队列操作接口请求与响应
• 多媒体内容上传
  • 图片文件上传
  • 语音文件上传
  • 群文件上传

---

通用接口

通用接口为所有 built-in adapter 公用的数据规范, 该文档定义了不同 adapter 的具体调用方式

• 获取插件信息
  • 关于
  • 获取登录账号
• 缓存操作
  • 通过messageId获取消息
• 获取账号信息
  • 获取好友列表
  • 获取群列表
  • 获取群成员列表
  • 获取Bot资料
  • 获取好友资料
  • 获取群成员资料
  • 获取QQ用户资料
• 消息发送与撤回
  • 发送好友消息
  • 发送群消息
  • 发送临时会话消息
  • 发送头像戳一戳消息
  • 撤回消息
  • 获取漫游消息
• 文件操作
  • 查看文件列表
  • 获取文件信息
  • 创建文件夹
  • 删除文件
  • 移动文件
  • 重命名文件
• 账号管理
  • 删除好友
• 群管理
  • 禁言群成员
  • 解除群成员禁言
  • 移除群成员
  • 退出群聊
  • 全体禁言
  • 解除全体禁言
  • 设置群精华消息
  • 获取群设置
  • 修改群设置
  • 获取群员资料
  • 修改群员资料
• 群公告
  • 获取群公告
  • 发布群公告
  • 删除群公告
• 事件处理
  • 添加好友申请
  • 用户入群申请
  • Bot被邀请入群申请
• Console命令
  • 执行命令
  • 注册命令
  • 命令接收

认证与会话

认证

接口名称

[POST] /verify

使用此方法验证你的身份，并返回一个会话

请求:

{
    "verifyKey": "U9HSaDXl39ksd918273hU"
}

名字	类型	可选	举例	说明
verifyKey	String	false	"U9HSaDXl39ksd918273hU"	创建Mirai-Http-Server时生成的key，可在启动时指定或随机生成

响应:

{
    "code": 0,
    "session": "UnVerifiedSession"
}

名字	类型	举例	说明
code	Int	0	返回状态码
session	String	"UnVerifiedSession"	你的session key

session key 是使用以下方法必须携带的 session key 使用前必须进行校验和绑定指定的Bot，每个Session只能绑定一个Bot，但一个Bot可有多个Session session Key 在未进行校验的情况下，一定时间后将会被自动释放

绑定

[POST] /bind

使用此方法校验并激活你的Session，同时将Session与一个已登录的Bot绑定

请求:

{
    "sessionKey": "UnVerifiedSession",
    "qq": 123456789
}

名字	类型	可选	举例	说明
sessionKey	String	false	"UnVerifiedSession"	你的session key
qq	Long	false	123456789	Session将要绑定的Bot的qq号

响应:

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

获取会话信息

使用此方法获取 session 的相关信息

[GET] /sessionInfo?sessionKey=YourSessionKey

请求:

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

响应:

{
  "code": 0,
  "msg": "",
  "data": {
    "sessionKey": "YourSessionKey",
    "qq": {
      "id": 1234567890,
      "nickname": "",
      "remark": ""
    }
  }
}

释放

[POST] /release

使用此方式释放session及其相关资源（Bot不会被释放） 不使用的Session应当被释放，长时间（30分钟）未使用的Session将自动释放，否则Session持续保存Bot收到的消息，将会导致内存泄露(开启websocket后将不会自动释放)

请求:

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

名字	类型	可选	举例	说明
sessionKey	String	false	"YourSessionKey"	你的session key
qq	Long	false	123456789	与该Session绑定Bot的QQ号码

响应:

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

SessionKey与Bot 对应错误时将会返回状态码2：指定的Bot不存在

传递(重要)

sessionKey 作为会话的唯一标识, 它对应着服务器缓存及其上下文. 在 adapter 允许的情况下, 复用 sessionKey 创建多个连接会共享上下文

HttpAdapter 允许复用 sessionKey 创建多个连接

在 singleMode 模式下: 所有需要 sessionKey 参数的接口可忽略 sessionKey

在非 singleMode 模式下 sessionKey 可通过以下方式传递:

1. 设置请求头 sessionKey: YourSessionKey, 大小写敏感
2. 设置请求头 Authorization: session YourSessionKey, Authorization 大小写敏感, session 大小写不敏感
3. 设置请求头 Authorization: sessionKey YourSessionKey, Authorization 大小写敏感, sessionKey 大小写不敏感
4. 通过 url参数(对于GET请求)或 json 参数(对于POST请求)填入 sessionKey 字段, 大小写敏感

接收消息与事件

http adapter 基于缓存队列保存 session 的"未读消息", 消息与事件的接收，等同于对该队列的操作

http adatper 提供以下队列操作

查看队列大小

使用此方法获取 session 未读缓存消息的数量

[GET] /countMessage?sessionKey=YourSessionKey

请求:

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

响应:

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

获取队列头部

即按时间顺序获取消息，获取消息后从队列中移除

[GET] /fetchMessage?sessionKey=YourSessionKey&count=10

获取队列尾部

即获取最新的消息，获取消息后从队列中移除

[GET] /fetchLatestMessage?sessionKey=YourSessionKey&count=10

查看队列头部

即按时间顺序查看消息，查看消息后不从队列中移除

[GET] /peekMessage?sessionKey=YourSessionKey&count=10

查看队列尾部

即查看最新的消息，查看消息后不从队列中移除

[GET] /peekLatestMessage?sessionKey=YourSessionKey&count=10

消息队列操作接口请求与响应

请求:

名字	可选	举例	说明
sessionKey	false	YourSessionKey	你的session key
count	false	10	获取(查看)消息和事件的数量

响应:

{
  "code": 0,
  "msg": "",
  "data": [] // 消息、事件列表
}

相关阅读:

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

获取插件信息

关于

使用此方法获取插件的信息，如版本号

[GET] /about

通用接口定义: 关于

获取登录账号

使用此方法获取所有当前登录账号

[GET] /botList

通用接口定义: 获取登录账号

缓存操作

通过messageId获取消息

此方法通过 messageId 获取历史消息, 历史消息的缓存有容量大小, 在配置文件中设置

[GET] /messageFromId?sessionKey=YourSessionKey&messageId=1234567890&target=123456789

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 通过messageId获取消息

获取账号信息

获取好友列表

使用此方法获取bot的好友列表

[GET] /friendList?sessionKey=YourSessionKey

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取好友列表

获取群列表

使用此方法获取bot的群列表

[GET] /groupList?sessionKey=YourSessionKey

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取群列表

获取群成员列表

使用此方法获取bot指定群中的成员列表

[GET] /memberList?sessionKey=YourSessionKey&target=123456789

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取群成员列表

获取最新群成员列表

使用此方法获取bot指定群中的最新群成员列表

[GET] /latestMemberList?sessionKey=YourSessionKey&target=123456789

通用接口定义: 获取最新群成员列表

获取Bot资料

此接口获取 session 绑定 bot 的详细资料

[GET] /botProfile

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取Bot资料

获取好友资料

此接口获取好友的详细资料

[GET] /friendProfile

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取好友资料

获取群成员资料

此接口获取群成员的消息资料

[GET] /memberProfile

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取群成员资料

获取QQ用户资料

此接口获取任意QQ用户的资料

[GET] /userProfile

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取QQ用户资料

消息发送与撤回

发送好友消息

使用此方法向指定好友发送消息

[POST] /sendFriendMessage

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 发送好友消息

发送群消息

[POST] /sendGroupMessage

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 发送群消息

发送临时会话消息

[POST] /sendTempMessage

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 发送临时会话消息

发送头像戳一戳消息

[POST] /sendNudge

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 发送头像戳一戳消息

撤回消息

[POST] /recall

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 撤回消息

获取漫游消息

[POST] /roamingMessages

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 获取漫游消息

文件操作

查看文件列表

[GET] /file/list

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 查看文件列表

获取文件信息

[GET] /file/info

本接口为[GET]请求, 参数格式为url参数

通用接口定义: 获取文件信息

创建文件夹

[POST] /file/mkdir

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 创建文件夹

删除文件

[POST] /file/delete

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 删除文件

移动文件

[POST] /file/move

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 移动文件

重命名文件

[POST] /file/rename

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 重命名文件

多媒体内容上传

如果发送错误的请求,API将不会返回任何数据,也不会断开连接. 请确保发送了正确的multipart请求.

图片文件上传

使用此方法上传图片文件至服务器并返回ImageId

[POST] /uploadImage

本接口为[POST]请求, 参数格式为multipart/form-data

请求:

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
type	String	false	"friend"	"friend" 或 "group" 或 "temp"
img	File	true	-	图片文件
url	String	true	-	图片URL

响应:

{
  "imageId": "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}.mirai",
  "url": "xxxxxxxxxxxxxxxxxxxx"
}

语音文件上传

使用此方法上传语音文件至服务器并返回VoiceId

[POST] /uploadVoice

本接口为[POST]请求, 参数格式为multipart/form-data

请求:

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
type	String	false	"group"	当前仅支持 "group"
voice	File	true	-	语音文件
url	String	true	-	语音文件 URL

响应:

{
  "voiceId":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.amr", //语音的VoiceId
  "url":"xxxxxxxxxxxxxxxxxxxx"
}

短视频文件上传

使用此方法上传语音文件至服务器并返回videoId

[POST] /uploadShortVideo

本接口为[POST]请求, 参数格式为multipart/form-data

请求:

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
type	String	false	"group"	当前仅支持 "group", "friend", "temp"
video	File	false	-	短视频文件
thumbnail	File	false	-	短视频封面

响应:

{
  "videoId":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", //短视频的videoId
}

群文件上传

[POST] /file/upload

本接口为[POST]请求, 参数格式为multipart/form-data

请求:

名字	类型	可选	举例	说明
sessionKey	String	true	YourSession	已经激活的Session
type	String	false	"group"	当前仅支持 "group"
target	Long	false	1234567	上传目标群号
path	String	false	""	上传目录的id, 空串为上传到根目录
file	File	false	-	上传的文件

响应:

{
  "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
  }
}

返回上传文件的信息

账号管理

删除好友

使用此方法删除指定好友

[POST] /deleteFriend

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 删除好友

群管理

禁言群成员

使用此方法指定群禁言指定群员（需要有相关限权）

[POST] /mute

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 禁言群成员

解除群成员禁言

使用此方法指定群解除群成员禁言（需要有相关限权）

[POST] /unmute

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 解除群成员禁言

移除群成员

使用此方法移除指定群成员（需要有相关限权）

[POST] /kick

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 移除群成员

退出群聊

使用此方法使Bot退出群聊

[POST] /quit

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 退出群聊

全体禁言

使用此方法令指定群进行全体禁言（需要有相关限权）

[POST] /muteAll

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 全体禁言

解除全体禁言

使用此方法令指定群解除全体禁言（需要有相关限权）

[POST] /unmuteAll

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 解除全体禁言

设置群精华消息

使用此方法添加一条消息为精华消息（需要有相关限权）

[POST] /setEssence

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 设置群精华消息

获取群设置

使用此方法获取群设置

[GET] /groupConfig

本接口为[GET]请求, 参数格式为URL参数

通用接口定义: 获取群设置

修改群设置

使用此方法修改群设置（需要有相关限权）

[POST] /groupConfig

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 修改群设置

获取群员设置

使用此方法获取群员设置

[GET] /memberInfo

本接口为[GET]请求, 参数格式为URL参数

通用接口定义: 获取群员设置

修改群员设置

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

[POST] /memberInfo

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 修改群员设置

修改群员管理员

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

[POST] /memberAdmin

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 修改群员管理员

群公告

获取群公告

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

[GET] /anno/list

本接口为[GET]请求, 参数格式为URL参数

通用接口定义: 获取群公告

发布群公告

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

[POST] /anno/publish

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 发布群公告

删除群公告

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

[POST] /anno/delete

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 删除群公告

事件处理

添加好友申请

使用此方法处理添加好友申请

[POST] /resp/newFriendRequestEvent

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 添加好友申请

用户入群申请

使用此方法处理用户入群申请

[POST] /resp/memberJoinRequestEvent

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 用户入群申请

Bot被邀请入群申请

使用此方法处理Bot被邀请入群申请

[POST] /resp/botInvitedJoinGroupRequestEvent

本接口为[POST]请求, 参数格式为application/json

通用接口定义: Bot被邀请入群申请

Console命令

执行命令

使用此方法向 console 提交一个消息作为命令执行

[POST] /cmd/execute

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 执行命令

注册命令

使用此方法向 console 注册一个指令, 当指令触发时, 会生成一个 CommandExecutedEvent

[POST] /cmd/register

本接口为[POST]请求, 参数格式为application/json

通用接口定义: 执行命令

命令接收

命令被调用时, 会触发 CommandExecutedEvent