正向 WebSocket

OneBot 在启动时开启一个 WebSocket 服务器,监听配置文件指定的 IP 和端口,接受路径为 /api(或 /api/)、/event(或 /event/)、/ 的连接请求。连接建立后,将一直保持连接(用户可主动断开连接),并根据路径的不同,提供 API 调用或事件推送服务。通过 WebSocket 消息发送的数据全部使用 JSON 格式。

/api 接口

连接此接口后,向 OneBot 发送如下结构的 JSON 对象,即可调用相应的 API:

{
    "action": "send_private_msg",
    "params": {
        "user_id": 10001000,
        "message": "你好"
    },
    "echo": "123"
}

这里的 action 参数用于指定要调用的 API,具体参考 APIparams 用于传入参数,如果要调用的 API 不需要参数,则可以不加;echo 字段是可选的,类似于 JSON RPCid 字段,用于唯一标识一次请求,可以是任何类型的数据,OneBot 将会在调用结果中原样返回。

客户端向 OneBot 发送 JSON 之后,OneBot 会往回发送一个调用结果,结构和 HTTP 的响应 相似,(除了包含请求中传入的 echo 字段外)唯一的区别在于,通过 HTTP 调用 API 时,HTTP 状态码反应的错误情况被移动到响应 JSON 的 retcode 字段,例如,HTTP 返回 404 的情况,对应到 WebSocket 的回复,是:

{
    "status": "failed",
    "retcode": 1404,
    "data": null,
    "echo": "123"
}

下面是 retcode 和 HTTP 状态码的对照:

retcode HTTP 接口中的状态码
1400 400
1401 401
1403 403
1404 404

实际上 14011403 并不会真的返回,因为如果建立连接时鉴权失败,连接会直接断开,根本不可能进行到后面的 API 调用阶段。

/event 接口

连接此接口后,OneBot 会在收到事件后推送至客户端,推送的格式和 HTTP POST 的上报 完全一致,事件的具体内容见 事件

与 HTTP POST 不同的是,WebSocket 推送不会对数据进行签名(即 HTTP POST 中的 X-Signature 请求头在这里没有等价的东西),并且也不会处理响应数据。如果对事件进行处理的时候需要调用接口,请使用 /api 接口 或使用 HTTP 调用 API。

此外,这个接口和 HTTP POST 不冲突,如果启用了正向 WebSocket,同时也配置了 HTTP POST 的上报地址,OneBot 会先通过 HTTP POST 上报,在处理完它的响应后,向所有已连接了 /event 的 WebSocket 客户端推送事件。

/ 接口

在一条连接上同时提供 /api/event 的服务,使用方式参考上面。

相关配置

配置项名称 默认值 说明
ws.enable false 是否启用正向 WebSocket
ws.host 0.0.0.0 WebSocket 服务器监听的 IP
ws.port 6700 WebSocket 服务器监听的端口

上一节 下一节
HTTP POST 反向 WebSocket