使用 Websocket 接入

payload

payload 指的是在 websocket 连接上传输的数据，网关的上下行消息采用的都是同一个结构，如下：

{
  "op": 0,
  "d": {},
  "s": 42,
  "t": "GATEWAY_EVENT_NAME"
}

op 指的是 opcode，全部 opcode 列表参考 opcode。

s 下行消息都会有一个序列号，标识消息的唯一性，客户端需要再发送心跳的时候，携带客户端收到的最新的s。

t和d 主要是用在op为 0 Dispatch 的时候，t 代表事件类型，d 代表事件内容，不同事件类型的事件内容格式都不同，请注意识别。

1.连接到 Gateway

第一步先调用 /gateway 或 /gateway/bot 接口获取网关地址。 会得到一个类似下面这样的地址：

wss://api.sgroup.qq.com/websocket/

然后进行 websocket 连接，一旦连接成功，就会返回 OpCode 10 Hello 消息。这个消息主要的内容是心跳周期，单位毫秒(milliseconds)，如下：

{
  "op": 10,
  "d": {
    "heartbeat_interval": 45000
  }
}

2.鉴权连接

建立 websocket 连接之后，就需要进行鉴权了，需要发送一个 OpCode 2 Identify 消息，如下：

{
  "op": 2,
  "d": {
    "token": "my_token",
    "intents": 513,
    "shard": [0, 4],
    "properties": {
      "$os": "linux",
      "$browser": "my_library",
      "$device": "my_library"
    }
  }
}

token 是创建机器人的时候分配的，格式为Bot {appid}.{app_token}

intents 是此次连接所需要接收的事件，具体可参考 Intents

shard 该参数是用来进行水平分片的。该参数是个拥有两个元素的数组。例如：[0,4]，代表分为四个片，当前链接是第 0 个片，业务稍后应该继续建立 shard 为[1,4],[2,4],[3,4]的链接，才能完整接收事件。更多详细的内容可以参考Shard。

properties 目前无实际作用，可以按照自己的实际情况填写，也可以留空

鉴权成功之后，后台会下发一个 Ready Event，结构如下：

{
  "op": 0,
  "s": 1,
  "t": "READY",
  "d": {
    "version": 1,
    "session_id": "082ee18c-0be3-491b-9d8b-fbd95c51673a",
    "user": {
      "id": "6158788878435714165",
      "username": "群pro测试机器人",
      "bot": true
    },
    "shard": [0, 0]
  }
}

3.发送心跳

鉴权成功之后，就需要按照周期进行心跳发送。d为客户端收到的最新的消息的s，如果是第一次连接，传null。

{
  "op": 1,
  "d": 251
}

心跳发送成功之后会收到 OpCode 11 Heartbeat ACK 消息，如下：

{
  "op": 11
}

4.恢复连接

有很多原因都会导致连接断开，断开之后短时间内重连会补发中间遗漏的事件，以保障业务逻辑的正确性。断开重连不需要发送Identify请求。在连接到 Gateway 之后，需要发送 Opcode 6 Resume消息，结构如下：

{
  "op": 6,
  "d": {
    "token": "my_token",
    "session_id": "session_id_i_stored",
    "seq": 1337
  }
}

其中 seq 指的是在接收事件时候的 s 字段，我们推荐开发者在处理过事件之后记录下 s 这样可以在 resume 的时候传递给 websocket，websocket 会自动补发这个 seq 之后的事件。

恢复成功之后，就开始补发遗漏事件，所有事件补发完成之后，会下发一个 Resumed Event，结构如下：

{
  "op": 0,
  "s": 2002,
  "t": "RESUMED",
  "d": ""
}