mirai/mirai-api-http/README_CH.md

mirai-api-http

Mirai-API-http 提供HTTP API供所有语言使用mirai

快速开始

fun main() {
    val bot = Bot(123456789, "password")

    bot.login()

    MiraiHttpAPIServer.start()
    
    bot.network.awaitDisconnection()
}

认证相关

开始会话-认证(Authorize)

[POST] /auth

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

请求:

{
    "authKey": "U9HSaDXl39ksd918273hU"
}

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

响应: 返回(成功):

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

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

状态码:

代码	原因
0	正常
1	错误的MIRAI API HTTP auth key

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

校验Session

[POST] /verify

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

请求:

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

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

响应: 返回统一状态码（后续不再赘述）

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

状态码	原因
0	正常
1	错误的auth key
2	指定的Bot不存在
3	Session失效或不存在
4	Session未认证(未激活)
5	发送消息目标不存在(指定对象不存在)
10	无操作权限，指Bot没有对应操作的限权
400	错误的访问，如参数错误等

释放Session

[POST] /release

使用此方式释放session及其相关资源（Bot不会被释放） 不使用的Session应当被释放，否则Session持续保存Bot收到的消息，将会导致内存泄露

请求:

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

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

响应: 返回统一状态码

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

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

消息相关

发送好友消息

[POST] /sendFriendMessage

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

请求

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

名字	类型	可选	举例	说明
sessionKey	String	false	YourSession	已经激活的Session
target	Long	false	987654321	发送消息目标好友的QQ号
messageChain	Array	false	[]	消息链，是一个消息对象构成的数组

响应: 返回统一状态码

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

发送群消息

[POST] /sendGroupMessage

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

请求

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

名字	类型	可选	举例	说明
sessionKey	String	false	YourSession	已经激活的Session
target	Long	false	987654321	发送消息目标群的群号
messageChain	Array	false	[]	消息链，是一个消息对象构成的数组

响应: 返回统一状态码

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

获取Bot收到的消息

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

请求:

名字	可选	举例	说明
sessionKey	false	YourSessionKey	你的session key
count	false	10	获取消息的数量

响应: 返回JSON对象

[{
    "type": "GroupMessage",        // 消息类型：GroupMessage或FriendMessage
	"messageChain": [{             // 消息链，是一个消息对象构成的数组
        "type": "Plain",
        "text": "Miral牛逼"
    }],
    "sender": {                      // 发送者信息
        "id": 123456789,             // 发送者的QQ号码
        "memberName": "化腾",        // 发送者的群名片
        "permission": "MEMBER",      // 发送者的群限权：OWNER、ADMINISTRATOR或MEMBER
        "group": {                   // 消息发送群的信息
            "id": 1234567890,        // 发送群的群号
            "name": "Miral Technology" // 发送群的群名称
        }
    }
 },
 {
    "type": "FriendMessage",         // 消息类型：GroupMessage或FriendMessage
        "messageChain": [{           // 消息链，是一个消息对象构成的数组
        "type": "Plain",
        "text": "Miral牛逼"
    }],
    "sender": {                      // 发送者信息
        "id": 1234567890,            // 发送者的QQ号码
        "nickName": "",              // 发送者的昵称
        "remark": ""                 // 发送者的备注
    }
}]

消息类型一览

消息是构成消息链的基本对象，目前支持的消息类型有

• At，@消息
• Face，表情消息
• Plain，文字消息
• Image，图片消息
• Xml，Xml卡片消息
• 敬请期待

At

{
    "type": "At",
    "target": 123456,
    "display": "@Mirai"
}

名字	类型	说明
target	Long	群员QQ号
display	String	@时显示的文本如："@Mirai"

Face

{
    "type": "Face",
    "faceID": 123
}

名字	类型	说明
faceID	Int	QQ表情编号

Plain

{
    "type": "Plain",
    "text": "Mirai牛逼"
}

名字	类型	说明
text	String	文字消息

Image

{
    "type": "Image"
    // 暂时不支持Image
}

名字	类型	说明

Xml

{
    "type": "Xml",
    "xml": "XML"
}

名字	类型	说明
xml	String	XML文本

管理相关

获取好友列表

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

[GET] /friendList?sessionKey=YourSessionKey

请求:

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

响应: 返回JSON对象

[{
    "id":123456789,
    "nickName":"",
    "remark":""
  },{
    "id":987654321,
    "nickName":"",
    "remark":""
}]

获取群列表

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

[GET] /groupList?sessionKey=YourSessionKey

请求:

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

响应: 返回JSON对象

[{
    "id":123456789,
    "name":"群名1"
  },{
    "id":987654321,
    "name":"群名2"
}]

获取群成员列表

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

[GET] /memberList?sessionKey=YourSessionKey

请求:

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

响应: 返回JSON对象

[{
    "id":1234567890,
    "memberName":"",
    "group":{
        "id":12345,
        "name":"群名1"
    },
    "permission":"MEMBER"
  },{
    "id":9876543210,
    "memberName":"",
    "group":{
        "id":54321,
        "name":"群名2"
    },
    "permission":"OWNER"
}]

群全体禁言

使用此方法令指定群进行全体禁言

[POST] /muteAll

请求:

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

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

响应: 返回统一状态码

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

群解除全体禁言

使用此方法令指定群解除全体禁言

[POST] /unmuteAll

请求:

同全体禁言

响应

同全体禁言

群禁言群成员

使用此方法指定群禁言指定群员

[POST] /mute

请求:

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

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

响应: 返回统一状态码

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

群解除群成员禁言

使用此方法令指定群解除全体禁言

[POST] /unmute

请求:

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

响应

同群禁言群成员