跳转至

Websocket api

概述

WebSocket API通过WebSocket与套接字服务器通信提供聊天服务。它支持游戏客户端连接、发送频道消息等功能。

WebSocket API 的主要特点如下：

  • 客户端连接 / 断开连接
  • PING / PONG
  • 发送 / 接收聊天消息
    • 频道聊天
    • 1:1 聊天
  • 被阻止用户过滤
    • 不向被阻止用户发送消息
    • 不接收被阻止用户的消息
  • 频道进出通知

基本信息

本节提供了使用 WebSocket API 时需要了解的基本信息。

关键术语

  • 频道: 聊天室
  • 频道消息: 发送给加入频道的所有用户的聊天消息
  • 1:1 消息: 仅发送给特定用户的聊天消息

数据包类型

以下数据包类型通过套接字服务器发送和接收。

数据包名称 描述
CONNECT 连接到套接字服务器
RESPONSE_CONNECT 对CONNECT请求的响应
RECONNECT 重新连接到套接字服务器
RESPONSE_RECONNECT 对RECONNECT请求的响应
PING 保持连接
如果在CONNECT成功之前发送PING，服务器将断开连接
PONG 对PING请求的响应
CHANNEL_CHAT 频道聊天
RESPONSE_CHANNEL_CHAT 对CHANNEL_CHAT请求的响应
DIRECT_CHAT 1:1聊天
RESPONSE_DIRECT_CHAT 对DIRECT_CHAT请求的响应
NOTIFY_ENTER_CHANNEL 频道进入消息
NOTIFY_EXIT_CHANNEL 频道退出消息
NOTIFY_DELETE_CHANNEL 频道删除消息
NOTIFY_CHANNEL_NOTICE 频道通知消息
NOTIFY_NOTICE 用户通知消息
NOTIFY_CHANNEL_CHAT 频道聊天消息
NOTIFY_DIRECT_CHAT 1:1聊天消息

套接字连接过程

  1. 游戏服务器向聊天 Http API 请求令牌发行。※ 发行的令牌用于连接聊天 Socket 服务器

  2. 应用客户端请求与 Socket 服务器的连接

    • WebSocket 通信
    • 使用第 1 步中发放的令牌
    • 连接成功后，Socket 服务器返回以下信息
    {
    "packetType":"RESPONSE_CONNECT",
    "status": 200,
    "message": "OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
    }
}

套接字断开连接

当WebSocket连接被终止时，服务器执行以下操作：

  • 退出您参与的频道并发送离开通知消息
  • 删除连接信息

套接字通信结构

WebSocket通信采用JSON格式进行。请求数据包格式如下：

{
        "packetType":"Packet type",
        "correlationId":"Identifier matching the response to the request",
        "body": {
                //JSON data according to packetType
        }
}


以下是响应数据包格式。

{
        "packetType":"Packet type (starts with RESPONSE)",
        "correlationId":"Identifier matching the response to the request",
        "status":"Status code",
        "message":"Status message",
        "body": // JSON Object
}


以下是服务器消息数据包格式。

{
        "packetType":"Packet type (starts with NOTIFY)",
        "body":{
                //JSON data according to packetType
        }
}


服务器可能在以下情况下终止WebSocket连接：

  • 如果客户端在1分钟内没有请求
  • 如果不是JSON格式
  • 当状态值为401或403时
    • 401 未授权
    • 403 禁止
  • 如果您使用另一个会话连接，现有会话将被终止

响应代码

响应状态代码如下。

状态代码 状态消息 描述
200 成功. 成功
400 错误请求 错误请求
401 未授权 无权限
403 禁止 服务器拒绝
408 请求超时 由于客户端60秒内没有请求，服务器断开连接
409 冲突 用户的请求与服务器状态冲突（例如，如果1:1聊天伙伴离线）
500 内部服务器错误 内部服务器错误

WebSocket API 函数

本节描述了聊天服务中使用的WebSocket API每个功能的API请求、响应和示例代码。

客户端连接

请求参数

字段名称 描述 类型 必需
packetType 客户端连接命令 (CONNECT) 字符串 是
body 请求数据 对象 是
请求参数 > 正文
字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
playerId 账户标识符
玩家ID		 长整型 Y 例如 1234
langCode Hive 语言代码
(基于 ISO 639 alpha-2，ISO 639 alpha-2 未区分的语言由脚本标签分隔)		 字符串 Y 例如 "en"
loginKey 用于连接的令牌
由 Chat Http API 发放		 字符串 Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

响应主体

字段名称 描述 类型 必需
packetType 对连接请求的响应 (RESPONSE_CONNECT) 字符串 是
status 状态码 整数 是
message 状态消息 字符串 是
body 返回数据 对象 是
响应主体 > 主体
字段名称 描述 类型 是否必需 示例
sessionId 连接成功时返回的值 字符串 是 例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

请求示例

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // JWT created by the API server
    }
}

响应示例

{
    "packetType":"RESPONSE_CONNECT",
    "status": 200,
    "message":"OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
    }
}

客户端重新连接

WebSocket 提供了重连功能，因为连接可能会根据网络情况被终止。如果在 WebSocket 断开后的 10 分钟内发出 RECONNECT 请求，它将重新加入之前加入的频道。

请求参数

字段名称 描述 类型 必需
packetType 客户端重新连接命令 (RECONNECT) 字符串 是
body 请求数据 对象 是
请求参数 > 正文
字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 是 例如 1
playerId 账户标识符
玩家ID		 长整型 是 例如 1234
langCode Hive 语言代码
(基于 ISO 639 alpha-2，未通过 ISO 639 alpha-2 区分的语言用脚本标签分隔)		 字符串 是 例如 "en"
loginKey 用于连接的令牌
由 Chat Http API 颁发		 字符串 是 "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

响应主体

字段名称 描述 类型 是否必需
packetType 对重连请求的响应 (RESPONSE_RECONNECT) 字符串 是
status 状态码 整数 是
message 状态消息 字符串 是
body 返回数据 对象 是
响应主体 > 主体
字段名称 描述 类型 必需 示例
sessionId 成功连接后返回的值 字符串 Y 例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
channelIds 从之前加入的频道成功重新加入的频道列表 字符串数组 Y 例如 ["ch:1", "ch:2"]
failChannelIds 从之前加入的频道未能重新加入的频道列表 字符串数组 Y 例如 []

请求示例

{
    "packetType": "RECONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // JWT created by the API server
    }
}

响应示例

{
    "packetType":"RESPONSE_RECONNECT",
    "status": 200,
    "message":"OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76",
        "channelIds":["ch:1", "ch:2"], // List of channels that were successfully rejoined
        "failChannelIds":[]                // List of channels that failed to rejoin
    }
}

PING / PONG

  • 请求仅在 Socket 服务器和 CONNECT 成功完成时有效
  • 如果没有 PONG 响应，则需要重新登录

请求参数

字段名称 描述 类型 必需
packetType PING 请求命令 (PING) 字符串 是

响应体

字段名称 描述 类型 必需
packetType PONG 响应命令 (PONG) 字符串 Y

请求示例

{
    "packetType":"PING"   
}

响应示例

{
    "packetType": "PONG"   
}

发送频道消息

请求参数

字段名称 描述 类型 必需
packetType 频道消息发送命令 (CHANNEL_CHAT) 字符串 是
body 请求数据 对象 是
请求参数 > 正文
字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
from 发送消息到频道的账户标识符
玩家ID		 长整型 Y 例如 1234
to 发送频道消息的频道ID
聊天Http API中创建		 字符串 Y 例如 "open:1"
message 要发送到频道的消息
(最多200个字符)		 字符串 Y 例如 "Hello World!"
extraData 附加消息信息（基于 UTF-8）
(最多256字节)		 字符串 Y 例如 "bbbb"
langCode 发送消息的语言代码
Hive 语言代码
(基于ISO 639 alpha-2，ISO 639 alpha-2未区分的语言由脚本标签分隔)		 字符串 Y 例如 "en"

响应主体

字段名称 描述 类型 必需
packetType 对频道消息发送的响应 (RESPONSE_CHANNEL_CHAT) 字符串 是
status 状态代码 整数 是
message 状态消息 字符串 是

请求示例

{
    "packetType":"CHANNEL_CHAT",
    "body": {
        "gameIndex": 1,
        "from": 1234,
        "to": "open:1",
        "message": "Hello World!",
        "extraData": "bbbb",
        "langCode": "en"
    }
}

响应示例

{
    "packetType": "RESPONSE_CHANNEL_CHAT",
    "status": 200,
    "message":"OK"
}

发送 1:1 消息

请求参数

字段名称 描述 类型 是否必需
packetType 1:1 消息发送命令 (DIRECT_CHAT) 字符串 是
body 请求数据 对象 是
请求参数 > 主体
字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
from 发送 1:1 消息的账户标识符
玩家 ID		 长整型 Y 例如 1234
to 接收 1:1 消息的账户标识符
玩家 ID		 长整型 Y 例如 2222
message 要发送的 1:1 消息
(最多 200 个字符)		 字符串 Y 例如 "Hello World!"
extraData 附加消息信息 (基于 UTF-8)
(最多 256 字节)		 字符串 Y 例如 "bbbb"
langCode 发送消息的语言代码
Hive 语言代码
(基于 ISO 639 alpha-2，ISO 639 alpha-2 不区分的语言用脚本标签分隔)		 字符串 Y 例如 "en"

响应主体

字段名称 描述 类型 必需
packetType 对1:1消息发送的响应（RESPONSE_DIRECT_CHAT） 字符串 是
status 状态码 整数 是
message 状态消息 字符串 是
响应主体 > 主体
字段名称 描述 类型 必需 示例
status 响应状态码 整数 Y 例如 200

请求示例

{
  "packetType": "DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "to": 1234,
    "message": "안녕하세요",
    "extraData": "bbbb",
    "langCode": "ko"
  }
}

响应示例

{
    "packetType": "RESPONSE_DIRECT_CHAT",
    "status": 200,
    "message":"OK"
}

套接字服务器事件消息

本节描述了事件发生时从服务器发送到客户端的消息。

这些消息在packetType中以NOTIFY开头。

渠道入口消息

字段名称 描述 类型 必需
packetType 通道进入消息 (NOTIFY_ENTER_CHANNEL) 字符串 是
body 请求数据 对象 是

主题

字段名称 描述 类型 是否必填 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
channelId 条目的频道ID 字符串 Y 例如 "open:10"
playerId 进入频道的账户标识符
玩家ID		 长整型 Y 例如 1234
timestamp 进入频道的时间（UTC+0标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ格式） 字符串 Y 例如 "2024-11-12T08:59:59.497Z"
timestampMillis 进入频道的时间（Unix时间戳毫秒） 长整型 Y 例如 1731401989

示例

{
  "packetType": "NOTIFY_ENTER_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "playerId": 1234,
    "timestamp": "2024-11-12T08:59:59.497Z",
    "timestampMillis": 1731401989
  }
}

渠道退出消息

字段名称 描述 类型 必需
packetType 通道退出消息 (NOTIFY_EXIT_CHANNEL) 字符串 是
body 请求数据 对象 是

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 是 例如 1
channelId 退出的频道 ID 字符串 是 例如 "open:10"
playerId 退出频道的账户标识符
玩家 ID		 长整型 是 例如 2222
timestamp 从频道退出的时间（UTC+0 标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式） 字符串 是 例如 "2024-11-12T08:59:59.497Z"
timestampMillis 从频道退出的时间（Unix时间戳毫秒） 长整型 是 例如 1731401989

示例

{
  "packetType": "NOTIFY_EXIT_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "playerId": 2222,
    "timestamp": "2024-11-12T09:29:35.872Z",
    "timestampMillis": 1731401989
  }
}

渠道删除消息

字段名称 描述 类型 必需
packetType 渠道删除消息 (NOTIFY_DELETE_CHANNEL) 字符串 是
body 请求数据 对象 是

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
channelId 被删除频道的频道ID 字符串 Y 例如 "open:10"
timestamp 频道删除时间（UTC+0 标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式） 字符串 Y 例如 "2024-11-12T08:59:59.497Z"
timestampMillis 频道删除时间（Unix时间戳毫秒） 长整型 Y 例如 1731401989

示例

{
  "packetType": "NOTIFY_DELETE_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "owner:1",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

渠道通知消息

字段名称 描述 类型 是否必需
packetType 通知消息 (NOTIFY_CHANNEL_NOTICE) 字符串 是
body 请求数据 对象 是

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
channelId 接收通知消息的频道ID 字符串 Y 例如 "open:10"
from 发送通知消息的账户标识符 字符串 Y 例如 SYSTEM
message 通知消息的内容 字符串 Y 例如 "这是一条通知消息。"
timestamp 发送通知消息的时间（UTC+0标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ格式） 字符串 Y 例如 "2024-11-13T05:06:29.198Z"
timestampMillis 发送通知消息的时间（Unix时间戳毫秒） 长整型 Y 例如 1731401989

示例

// Notice to a specific channel
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "message": "This is a notice message.",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

用户通知消息

字段名称 描述 类型 必需
packetType 用户通知消息 (NOTIFY_NOTICE) 字符串 是
body 请求数据 对象 是

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 是 例如 1
playerId 收到通知消息的玩家ID 长整型 是 例如 123123
from 发送通知消息的账户标识符 字符串 是 例如 SYSTEM
message 通知消息的内容 字符串 是 例如 "这是一条通知消息。"
timestamp 发送通知消息的时间（UTC+0标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ格式） 字符串 是 例如 "2024-11-13T05:06:29.198Z"
timestampMillis 发送通知消息的时间（Unix时间戳毫秒） 长整型 是 例如 1731401989

示例

// Notice to a specific user
{
  "packetType": "NOTIFY_NOTICE",
  "body": {
    "gameIndex": 1,
    "playerId": 123123,
    "from": "SYSTEM",
    "message": "This is a notice message.",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

渠道消息

字段名称 描述 类型 是否必需
packetType 通道消息 (NOTIFY_CHANNEL_CHAT) 字符串 是
body 请求数据 对象 是

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
from 发送频道消息的账户标识符
玩家ID		 长整型 Y 例如 2222
to 接收频道消息的频道ID 字符串 Y 例如 "open:10"
message 频道消息的内容 字符串 Y 例如 "你好。这是一个频道聊天。"
extraData 附加消息信息（基于 UTF-8）
（最多 256 字节）		 字符串 Y 例如 "bbbb"
timestamp 发送频道消息的时间（UTC+0 标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式） 字符串 Y 例如 "2024-11-13T05:12:18.385Z"
timestampMillis 发送频道消息的时间（Unix时间戳毫秒） 长整型 Y 例如 1731401989

示例

{
  "packetType": "NOTIFY_CHANNEL_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "to": "open:10",
    "message": "Hello World!",
    "extraData": "bbbb",
    "timestamp": "2024-11-13T05:12:18.385Z",
    "timestampMillis": 1731401989
  }
}

1:1 消息

字段名称 描述 类型 必需
packetType 1:1 消息 (NOTIFY_DIRECT_CHAT) 字符串 是
body 请求数据 对象 是

主题

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
from 接收 1:1 消息的账户标识符
玩家 ID		 长整型 Y 例如 1234
to 发送 1:1 消息的账户标识符
玩家 ID		 长整型 Y 例如 2222
message 1:1 消息的内容 字符串 Y 例如 "你好。这是一个 1:1 聊天。"
extraData 附加消息信息（基于 UTF-8）
（最多 256 字节）		 字符串 Y 例如 "abcd"
timestamp 发送 1:1 消息的时间（UTC+0 标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式） 字符串 Y 例如 "2024-11-13T05:12:50.060Z"
timestampMillis 发送 1:1 消息的时间（Unix时间戳毫秒） 长整型 Y 例如 1731401989

示例

{
  "packetType": "NOTIFY_DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 1234,
    "to": 2222,
    "message": "Hello. This is a 1:1 chat.",
    "extraData": "abcd",
    "timestamp": "2024-11-13T05:12:50.060Z",
    "timestampMillis": 1731401989
  }
}