Chocolatl / Qqlight Websocket

QQLight机器人框架的WebSocket-RPC插件

插件通过WebSocket与JSON实现远程过程调用，让你能使用任何喜欢的语言编写QQ机器人程序

插件下载地址

使用方法

将插件复制到QQLight机器人框架的plugin目录中，运行QQLight机器人并在插件管理中启用插件

插件启动后默认监听49632端口，在本机可以使用WebSocket客户端通过URLws://localhost:49632/连接服务器

配置

第一次启动插件后会在插件数据目录plugin/websocket.protocol中生成config.json文件，里面提供了一些插件配置项

你可以修改这些插件配置项并保存文件，然后重新启动插件使新的配置生效

address

服务器监听地址，默认为127.0.0.1，即只允许本机连接服务器，如果你希望通过外网连接服务器，可以设置为0.0.0.0

port

服务器监听端口号，默认为49632

path

WebSocket握手时的URL路径，默认为根路径/，即通过ws://localhost:49632/连接服务器。如果将路径修改为/xxx/yyy，则需要通过ws://localhost:49632/xxx/yyy才能连接服务器

路径应该只包含字母、数字及/，当允许通过外网连接服务器时，请设置一个足够复杂的路径，防止被他人恶意连接

示例

浏览器示例

这是一个复读机（Echo）的Javascript示例，可以直接运行在浏览器上：

var ws = new WebSocket('ws://localhost:49632/');
ws.onmessage = function(ev) {
    var data   = JSON.parse(ev.data);
    var params = data.params;
    if(data.event === 'message') {
        var rpc = {
            id: Math.random().toString(),
            method: "sendMessage",
            params: {
                type    : params.type,
                group   : params.group,
                qq      : params.qq,
                content : params.content
            }
        };
        ws.send(JSON.stringify(rpc));
    }
}

Node.js示例

这是一个复读机（Echo）的Node.js示例，使用了ws模块：

const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:49632/');
ws.on('message', data => {
    data = JSON.parse(data);
    if(data.event === 'message') {
        ws.send(JSON.stringify({
            id: Math.random().toString(),
            method: 'sendMessage',
            params: {...data.params}
        }));
    }
});

API文档

服务端与客户端发送的消息都是顶层结构为对象的JSON格式文本，文本编码为UTF-8

事件

事件是服务器会主动发送给客户端的消息，如机器人收到好友请求时，服务器会向客户端发送如下格式的消息：

{
    "event": "friendRequest", 
    "params": {
        "qq"      : "123456",
        "message" : ""
    }
}

接口

接口是客户端可以发送给服务器的消息，服务器收到消息会调用机器人相应的方法处理，下面是删除好友的消息示例：

{
    "id"    : "1024"
    "method": "deleteFriend", 
    "params": {
        "qq": ""
    }
}

所有接口调用必须携带字符串类型的id字段，且每次请求都应该使用不同的id，服务器返回结果会包含与调用时相同的id。id用于分辨返回的数据属于哪个调用

接口返回

无返回值的接口调用成功会返回仅包含id字段的对象：

{
    "id"    : "1024"
}

有返回值的接口调用成功会返回包含id与result字段的对象，其中result字段类型与值视具体接口而定：

{
    "id"    : "1024"
    "result": true
}

接口调用发生错误会返回包含id与error字段的对象，其中error字段为字符串类型的错误信息：

{
    "id"   : "1024"
    "error": "Unknown Method"
}

API列表

• 事件.收到消息
• 事件.收到好友请求
• 事件.好友变动
• 事件.群成员增加
• 事件.群成员减少
• 事件.群管理员变动
• 事件.加群请求
• 事件.收款
• 接口.发送消息
• 接口.撤回消息
• 接口.获取好友列表
• 接口.添加好友
• 接口.删除好友
• 接口.获取群列表
• 接口.获取群成员列表
• 接口.添加群
• 接口.退出群
• 接口.获取群名片
• 接口.上传图片
• 接口.获取QQ资料
• 接口.获取群资料
• 接口.邀请好友入群
• 接口.设置群名片
• 接口.获取当前登录账号
• 接口.设置个性签名
• 接口.获取QQ昵称
• 接口.设置QQ昵称
• 接口.获取名片点赞数量
• 接口.点赞名片
• 接口.处理好友请求
• 接口.设置在线状态
• 接口.处理加群请求
• 接口.移除群成员
• 接口.禁言
• 接口.全体禁言
• 接口.获取Cookies
• 接口.获取Bkn
• 接口.获取长Bkn
• 接口.发表空间说说
• 替换符.at
• 替换符.face/emoji
• 替换符.image/flash

事件.收到消息

{
    "event": "message", 
    "params": {
        "type"    : 2,   // 1=好友消息、2=群消息、3=群临时消息、4=讨论组消息、5=讨论组临时消息、6=QQ临时消息
        "group"   : "",  // 类型为1或6的时候，此参数为空字符串，其余情况下为群号或讨论组号
        "qq"      : "",  // 消息来源QQ号，"10000"都是来自系统的消息（比如某人被禁言或某人撤回消息等）
        "content" : "",  // 消息内容
        "msgid"   : ""   // 消息id，撤回消息的时候会用到，群消息会存在，其余情况下为空  
    }
}

事件.收到好友请求

{
    "event": "friendRequest", 
    "params": {
        "qq"      : "",
        "message" : ""      // 验证消息
    }
}

收到该事件时可以通过调用接口.处理好友请求处理

事件.好友变动

{
    "event": "friendChange", 
    "params": {
        "type": 1,          // 1.成为好友（单向） 2.成为好友（双向） 3、被删除好友
        "qq": ""
    }
}

事件.群成员增加

{
    "event": "groupMemberIncrease", 
    "params": {
        "type"      : 1,        // 1=主动加群、2=被管理员邀请
        "group"     : "",       //
        "qq"        : "",       //
        "operator"  : ""        // 操作者QQ
    }
}

事件.群成员减少

{
    "event": "groupMemberDecrease", 
    "params": {
        "type"      : 1,        // 1=主动退群、2=被管理员踢出
        "group"     : "",       //
        "qq"        : "",       //
        "operator"  : ""        // 操作者QQ，仅在被管理员踢出时存在
    }
}

事件.群管理员变动

{
    "event": "adminChange", 
    "params": {
        "type"      : 1,        // 1=成为管理 2=被解除管理
        "group"     : "",       //
        "qq"        : ""        //
    }
}

事件.加群请求

{
    "event": "groupRequest", 
    "params": {
        "type"      : 1,        // 1=主动加群、2=被邀请进群、3=机器人被邀请进群
        "group"     : "",       //
        "qq"        : "",       //
        "operator"  : "",       // 邀请者QQ，主动加群时不存在
        "message"   : "",       // 加群附加消息，只有主动加群时存在
        "seq"       : ""        // 序列号，处理加群请求时需要用到
    }
}

type为1时，指有人主动申请进群，这时operator字段为空，如果你是管理员，可以调用接口.处理加群请求处理

type为2时，指群员邀请别人进群，这时message字段为空，如果你是管理员，可以调用接口.处理加群请求处理

type为3时，指机器人被邀请进群，这时message字段为空，可以调用接口.处理加群请求处理

事件.收款

{
    "event": "receiveMoney", 
    "params": {
        "type"      : 1,        // 1=好友转账、2=群临时会话转账、3=讨论组临时会话转账
        "group"     : "",       // type为1时此参数为空，type为2、3时分别为群号或讨论组号
        "qq"        : "",       // 转账者QQ
        "amount"    : "",       // 转账金额
        "message"   : "",       // 转账备注消息
        "id"        : ""        // 转账订单号
    }
}

接口.发送消息

{
    "method": "sendMessage", 
    "params": {
        "type"    : 2,      // 1=好友消息、2=群消息、3=群临时消息、4=讨论组消息、5=讨论组临时消息、6=QQ临时消息
        "group"   : "",     // 群号或讨论组号，发送消息给好友的情况下忽略
        "qq"      : "",     // QQ号，发送消息给群或讨论组的情况下忽略
        "content" : ""
    }
}

无返回值

接口.撤回消息

{
    "method": "withdrawMessage", 
    "params": {
        "group": "",
        "msgid": ""
    }
}

无返回值

接口.获取好友列表

{
    "method" : "getFriendList",
    "params": {
        "cache": true       // 是否缓存结果
    }
}

接口.添加好友

{
    "method": "addFriend", 
    "params": {
        "qq"        : "",
        "message"   : ""       // 验证消息，可选
    }
}

无返回值

接口.删除好友

{
    "method": "deleteFriend", 
    "params": {
        "qq": ""
    }
}

无返回值

接口.获取群列表

{
    "method": "getGroupList",
    "params": {
        "cache": true       // 是否缓存结果
    }
}

接口.获取群成员列表

{
    "method": "getGroupMemberList",
    "params": {
        "group": "",
        "cache": true       // 是否缓存结果
    }
}

接口.添加群

{
    "method": "addGroup", 
    "params": {
        "group"     : "",
        "message"   : ""    // 验证消息，可选
    }
}

无返回值

接口.退出群

{
    "method": "quitGroup", 
    "params": {
        "group": ""
    }
}

无返回值

接口.获取群名片

{
    "method": "getGroupCard", 
    "params": {
        "group" : "",
        "qq"    : ""
    }
}

接口.上传图片

{
    "method": "uploadImage",
    "params": {
        "type"  : 2,        // 1=私聊类型的图片、2=群组类型的图片
        "object": ""        // 图片准备发送到的QQ号或群组号
        "data"  : ""        // 图像数据转换的十六进制字符串
    }
}

该接口并不发送图片，而是将图片上传到QQ服务器，并返回GUID，GUID用法参见替换符.image/flash

所获得的GUID只能对type和object指定的对象使用，否则图片可能无法显示

接口.获取QQ资料

{
    "method": "getQQInfo",
    "params": {
        "qq": ""
    }
}

接口.获取群资料

{
    "method": "getGroupInfo",
    "params": {
        "group": ""
    }
}

接口.邀请好友入群

{
    "method": "inviteIntoGroup",
    "params": {
        "qq"    : "",
        "group" : ""
    }
}

无返回值

接口.设置群名片

{
    "method": "setGroupCard", 
    "params": {
        "group" : "",
        "qq"    : "",
        "name"  : ""
    }
}

无返回值

接口.获取当前登录账号

{
    "method": "getLoginAccount"
}

接口.设置个性签名

{
    "method": "setSignature",
    "params": {
        "content": ""
    }
}

无返回值

接口.获取QQ昵称

{
    "method": "getNickname",
    "params": {
        "qq": ""
    }
}

接口.设置QQ昵称

{
    "method": "setNickname",
    "params": {
        "name": ""
    }
}

无返回值

接口.获取名片点赞数量

{
    "method": "getPraiseCount",
    "params": {
        "qq": ""
    }
}

接口.点赞名片

{
    "method": "givePraise",
    "params": {
        "qq": ""
    }
}

无返回值

接口.处理好友请求

{
    "method": "handleFriendRequest",
    "params": {
        "qq"       : "",
        "type"     : 1,      // 1=同意、2=拒绝、3=忽略
        "message"  : ""      // 拒绝理由，仅在拒绝请求时有效
    }
}

无返回值

接口.设置在线状态

{
    "method": "setState",
    "params": {
        "type": 1  // 1=我在线上、2=Q我吧、3=离开、4=忙碌、5=请勿打扰、6=隐身
    }
}

无返回值

接口.处理加群请求

{
    "method": "handleGroupRequest",
    "params": {
        "group"     : "",
        "qq"        : "",
        "seq"       : "",   // 加群请求事件提供的序列号
        "type"      : 1,    // 1=同意、2=拒绝、3=忽略
        "message"   : ""    // 拒绝时的拒绝理由，其它情况忽略
    }
}

无返回值

接口.移除群成员

{
    "method": "kickGroupMember",
    "params": {
        "group" : "",
        "qq"    : ""
    }
}

无返回值

接口.禁言

{
    "method": "silence",
    "params": {
        "group"     : "",
        "qq"        : "",
        "duration"  : 0     // 禁言时间，单位为秒，为0时解除禁言
    }
}

无返回值

接口.全体禁言

{
    "method": "globalSilence",
    "params": {
        "group"   : "",
        "enable"  : true     // true为全体禁言,false为取消全体禁言
    }
}

无返回值

接口.获取Cookies

{
    "method": "getCookies"
}

接口.获取Bkn

{
    "method": "getBkn",
    "cookies": ""
}

接口.获取长Bkn

{
    "method": "getBknLong",
    "cookies": ""
}

接口.发表空间说说

{
    "method": "sendQzone", 
    "params": {
        "content" : ""      // 内容，发送到空间说说的内容，目前仅支持文本内容
    }
}

替换符.at

在发送的群消息中使用[QQ:at=xxx]表示at某个群成员，其中xxx可以替换为任意群成员QQ

使用[QQ:at=all]表示at全体成员，但仅在发送者为群管理员时有效

替换符.face/emoji

在发送的消息中使用[QQ:face=212]代表一个QQ表情，其中212为表情代码，使用[QQ:emoji=39091]代表一个emoji表情

这里不提供QQ表情和emoji表情的表情代码，你需要自己想办法获取它们

替换符.image/flash

发送消息中使用[QQ:pic=xxx]代表一张图片，[QQ:flash,pic=xxx]代表一张闪照

其中xxx可以是图片GUID，也可以是图片URL，图片GUID可以通过调用接口.上传图片接口获得

语言绑定

插件提供了较为低级的接口，当使用其它语言调用时，通常需要根据语言特性进行封装以方便开发，下面是一些已有的语言绑定：

• qqlight-websocket-node (Node.js, Chocolatl)

编译环境

MinGW 3.4.5

许可证

GLWT（祝你好运）公共许可证
版权所有（C）每个人，除了作者

任何人都被允许复制、分发、修改、合并、销售、出版、再授权或
任何其它操作，但风险自负。

作者对这个项目中的代码一无所知。
代码处于可用或不可用状态，没有第三种情况。


                祝你好运公共许可证
            复制、分发和修改的条款和条件

0：在不导致作者被指责或承担责任的情况下，你可以做任何你想
要做的事情。

无论是在合同行为、侵权行为或其它因使用本软件产生的情形，作
者不对任何索赔、损害承担责任。

祝你好运及一帆风顺