跳转至

WebSocket API

概述

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

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_CHANNEL_CHAT 频道聊天消息
NOTIFY_DIRECT_CHAT 1:1聊天消息
NOTIFY_DISCONNECT 断开连接消息
当WebSocket连接空闲且Json格式无效时，响应此数据包类型

套接字连接过程

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

  2. 从游戏客户端向Socket服务器的连接请求

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

套接字断开连接

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

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

套接字通信结构

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

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


以下是响应数据包格式。

{
        "packetType":"Packet type (starts with RESPONSE)",
        "correlationId":"Identifier for 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 游戏索引 整数 是 例如 1
playerId 账户标识符
Hive 玩家 ID		 长整型 是 例如 1234
loginKey 用于访问的令牌
从 Chat Http API 发行		 字符串 是 "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData 用户附加信息 (UTF-8 基础)
(最多 256 字节)		 字符串 否 例如 "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

响应正文

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

请求示例

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY", // JWT generated by the API server
        "extraData": "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}" // Additional information
    }
}

响应示例

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

客户端重新连接

重连功能是因为WebSocket连接可能会根据网络情况断开。如果在WebSocket连接断开后的10分钟内发出RECONNECT请求，您将进入您之前参与的频道。

请求参数

字段名称 描述 类型 必需
packetType 客户端重连命令（RECONNECT） 字符串 是
body 请求数据 对象 是
请求参数 > 正文
字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
playerId 账户标识符
Hive 玩家 ID		 长整型 Y 例如 1234
loginKey 用于访问的令牌
聊天 HTTP API 发放		 字符串 Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData 用户附加信息 (UTF-8 基础)
(最大 256 字节)		 字符串 N 例如 "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

响应主体

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

请求示例

{
    "packetType": "RECONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY", // JWT generated by the API server
        "extraData": "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}" // Additional information
    }
}

响应示例

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

PING / PONG

  • 请求仅在套接字服务器和连接完成时有效。
  • 如果没有 PONG 响应，则需要重新登录。

请求参数

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

响应主体

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

请求示例

{
    "packetType":"PING"   
}

响应示例

{
    "packetType": "PONG"   
}

频道消息发送

请求参数

字段名称 描述 类型 必需
packetType 通道消息传输命令 (CHANNEL_CHAT) 字符串 是
body 请求数据 对象 是
请求参数 > 正文
字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
from 发送消息到频道的账户标识符
Hive 玩家 ID		 长整型 Y 例如 1234
to 发送频道消息的频道 ID
聊天 HTTP API 创建的		 字符串 Y 例如 "open:1"
message 发送到频道的消息
(最多 200 个字符)		 字符串 Y 例如 "Hello World!"
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!",
        "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 消息发送者账户标识符
Hive 玩家ID		 长整型 Y 例如 1234
to 1:1 消息接收者账户标识符
Hive 玩家ID		 长整型 Y 例如 2222
message 要发送的1:1消息
(最多200个字符)		 字符串 Y 例如 "Hello World!"
langCode Hive 语言代码
(基于ISO 639 alpha-2，未通过ISO 639 alpha-2区分的语言应使用Script标签分隔)		 字符串 Y 例如 "en"

响应主体

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

请求示例

{
  "packetType": "DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "to": 1234,
    "message": "안녕하세요",
    "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 进入频道的账户标识符
Hive 玩家 ID		 长整型 Y 例如 1234
extraData 用户附加信息（UTF-8 标准）
（最大 256 字节）		 字符串 Y 例如 "abcd"
timestamp 进入频道的日期和时间（UTC+0 标准，格式 yyyy-MM-dd'T'HH:mm:ss.SSSZ） 字符串 Y 例如 "2024-11-12T08:59:59.497Z"

示例

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

渠道退出消息

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

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
channelId 退出的频道 ID 字符串 Y 例如 "open:10"
playerId 退出频道的账户标识符
Hive 玩家 ID		 长整型 Y 例如 2222
extraData 用户附加信息（UTF-8 编码）
（最大 256 字节）		 字符串 Y 例如 "abcd"
timestamp 退出频道的日期和时间（UTC+0 基于，格式 yyyy-MM-dd'T'HH:mm:ss.SSSZ） 字符串 Y 例如 "2024-11-12T08:59:59.497Z"

示例

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

渠道删除消息

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

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 是 例如 1
channelId 删除的频道 ID 字符串 是 例如 "open:10"
timestamp 频道删除的日期和时间（基于 UTC+0，格式为 yyyy-MM-dd'T'HH:mm:ss.SSSZ） 字符串 是 例如 "2024-11-12T08:59:59.497Z"

示例

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

渠道公告消息

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

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
channelId 接收通知消息的频道ID 字符串 N 例如 "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"

示例

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

渠道消息

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

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 integer Y 例如 1
from 发送频道消息的账户标识符
Hive 玩家 ID		 long Y 例如 2222
fromExtra 用户附加信息（UTF-8 编码）
（最大 256 字节）		 string Y 例如 "bbbb"
to 发送频道消息的频道 ID string Y 例如 "open:10"
langCode Hive 语言代码
（基于 ISO 639 alpha-2，未通过 ISO 639 alpha-2 区分的语言应通过附加脚本标签进行区分）		 string Y 例如 "ko"
timestamp 发送频道消息的日期和时间（UTC+0 基于，格式 yyyy-MM-dd'T'HH:mm:ss.SSSZ） string Y 例如 "2024-11-13T05:12:18.385Z"

示例

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

1:1 消息

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

正文

字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
from 1:1 消息发送者账户标识符
Hive 玩家ID		 长整型 Y 例如 1234
fromExtra 用户附加信息 (UTF-8 编码)
(最大256字节)		 字符串 Y 例如 "abcd"
to 1:1 消息接收者账户标识符
Hive 玩家ID		 长整型 Y 例如 2222
message 1:1 消息内容 字符串 Y 例如 "你好。这是1:1聊天。"
langCode Hive 语言代码
(基于ISO 639 alpha-2，未通过ISO 639 alpha-2区分的语言用脚本标签分隔)		 字符串 Y 例如 "ko"
timestamp 1:1 消息发送日期和时间 (UTC+0 基于，格式 yyyy-MM-dd'T'HH:mm:ss.SSSZ) 字符串 Y 例如 "2024-11-13T05:12:50.060Z"

示例

{
  "packetType": "NOTIFY_DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 1234,
    "fromExtra": "abcd",
    "to": 2222,
    "message": "안녕하세요. 1:1 채팅입니다.",
    "langCode": "ko",
    "timestamp": "2024-11-13T05:12:50.060Z"
  }
}