跳转至

WebSocket API

概述

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

WebSocket API的主要功能如下。

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

基本信息

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

主要术语

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

数据包类型

与 Socket 服务器传输和接收的数据包类型如下所示。

数据包名称 描述
CONNECT Socket 服务器连接
RESPONSE_CONNECT 对 CONNECT 请求的响应
DISCONNECT Socket 服务器断开连接
RESPONSE_DISCONNECT 对 DISCONNECT 请求的响应
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":"RESPONSE_CONNECT",
    "status": 200,
    "message": "OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
    }
}

Socket通信结构

  • 以'RESPONSE_'开头的包类型的JSON格式 

    {
        "packetType":"包类型",
        "status":"状态代码",
        "message":"状态消息",
        "body": JSON对象
}

  • 其他数据包格式 

    {
        "packetType":"数据包类型",
        "body":{
                //根据 packetType 的 JSON 数据
        }
}

服务器端断开 WebSocket 连接的情况如下。

  • 如果客户端在1分钟内没有任何请求
  • 不是JSON格式时
  • status值为401、403时
    • 401 未授权
    • 403 禁止

响应代码

响应状态代码。

状态代码 状态消息 说明
200 成功 成功
400 错误请求 请求错误
401 未授权 权限不足
403 被禁止 服务器拒绝
408 请求超时 客户端60秒内没有请求，服务器断开连接
409 冲突 用户的请求与服务器状态冲突 (例如：1:1聊天对象离线)
500 内部服务器错误 内部服务器错误

WebSocket API 功能

解释用于聊天服务的 WebSocket API 的功能、API 请求和响应，以及示例代码。

客户端连接

请求参数

字段名 说明 类型 必填
packetType 客户端连接命令 (CONNECT) string Y
body 请求数据 object Y
请求参数 > 正文
字段名 说明 类型 必填 示例
gameIndex Hive 游戏索引 整数 是 例如 1
playerId 账户标识符
Hive 玩家 ID		 长整型 是 例如 1234
loginKey 登录时使用的令牌
聊天 Http API中颁发		 字符串 是 "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData 用户附加信息 (UTF-8 标准)
(最大 256 字节)		 字符串 否 例如 "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

响应体

字段名 说明 类型 必填
packetType 对连接请求的响应 (RESPONSE_CONNECT) string Y
status 状态代码 integer Y
message 状态消息 string Y
body 返回数据 object Y
响应主体 > 主体
字段名 描述 类型 必填 示例
sessionId 连接成功时返回的值 string Y 例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

请求示例

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": JWT generated by API server,
        "extraData": Additional information
    }
}

响应示例

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

客户端断开连接

请求参数

字段名 描述 类型 必需性
packetType 客户端断开连接命令 (DISCONNECT) string Y
body 请求数据 object Y
请求参数 > 主体
字段名 说明 类型 必填性 示例
sessionId 成功连接时返回的 sessionId string N 例如 "6c2408fffe8c91a8-00002f24-00000032-093b757cdc668383-54b4fbc1"
  • 如果未指定 sessionId，则处理与分配给 websocket 的 sessionId 的断开连接
  • 如果指定 sessionId，则处理该值的断开连接

响应体

字段名 说明 类型 必需性
packetType 对接入断开请求的响应 (RESPONSE_DISCONNECT) 字符串 Y
status 状态代码 整数 Y
message 状态消息 字符串 Y

请求示例

  • 如果未指定sessionId 

    {
        "packetType":"DISCONNET"
}

  • 指定sessionId的情况下 

    {
        "packetType":"DISCONNECT",
        "body":{
                "sessionId":"6c2408fffe8c91a8-00002f24-00000032-093b757cdc668383-54b4fbc1"
        }
}

响应示例

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

PING / PONG

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

请求参数

字段名 说明 类型 是否必需
packetType PING 请求命令 (PING) 字符串 Y

响应主体

字段名 说明 类型 是否必填
packetType PONG 响应命令 (PONG) 字符串 Y

请求示例

{
    "packetType":"PING"   
}

响应示例

{
    "packetType": "PONG"   
}

频道消息发送

请求参数

字段名 描述 类型 必填 여부
packetType 渠道消息发送命令 (CHANNEL_CHAT) string Y
body 请求数据 object Y
请求参数 > body
字段名 描述 类型 必填 示例
gameIndex Hive 游戏索引 integer Y 例如 1
from 向频道发送消息的账户标识符
Hive 玩家 ID		 long Y 例如 1234
to 向频道发送消息的频道 ID
聊天 Http API中创建		 string Y 例如 "open:1"
message 要发送到频道的消息
(最多 200 字符)		 string Y 例如 "Hello World!"
langCode Hive 语言代码
(基于 ISO 639 alpha-2，未按 ISO 639 alpha-2 区分的语言附加 Script 标签)		 string Y 例如 "en"

响应体

字段名 说明 类型 是否必需
packetType 关于频道消息传送的响应 (RESPONSE_CHANNEL_CHAT) string Y
status 状态码 integer Y
message 状态消息 string Y

请求示例

{
    "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) string Y
body 请求数据 object Y
请求参数 > 正文
字段名 描述 类型 必填 여부 示例
gameIndex Hive 游戏索引 整数 Y e.g. 1
from 发送 1:1 消息的账户标识符
Hive 玩家 ID		 长整型 Y e.g. 1234
to 接收 1:1 消息的账户标识符
Hive 玩家 ID		 长整型 Y e.g. 2222
message 要发送的 1:1 消息
(最多 200 字符)		 字符串 Y e.g. "Hello World!"
langCode Hive 语言代码
(基于 ISO 639 alpha-2，未按 ISO 639 alpha-2 区分的语言需附加脚本标签)		 字符串 Y e.g. "en"

响应正文

字段名 说明 类型 是否必需
packetType 对1:1消息传送的响应 (RESPONSE_DIRECT_CHAT) string Y
status 状态代码 integer Y
message 状态消息 string Y
响应主体 > body
字段名 描述 类型 必填 여부 示例
status 响应状态码 integer Y e.g. 200

请求示例

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

响应示例

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

Socket 服务器事件消息

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

该消息以 packetType 为 NOTIFY 开头。

频道入场消息

字段名 说明 类型 是否必填
packetType 渠道进入消息 (NOTIFY_ENTER_CHANNEL) string Y
body 请求数据 object Y

正文

字段名 说明 类型 必填项 示例
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) string Y
body 请求数据 object Y

正文

字段名 描述 类型 是否必需 示例
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) string Y
body 请求数据 object Y

正文

字段名 描述 类型 必填性 示例
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"

示例

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

渠道公告消息

字段名 说明 类型 是否必填
packetType 通知消息 (NOTIFY_CHANNEL_NOTICE) string Y
body 请求数据 object Y

正文

字段名 说明 类型 必填项 示例
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"

示例

// Announcement to specific channel
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "message": "공지 메시지 입니다.",
    "timestamp": "2024-11-13T05:06:29.198Z"
  }
}

渠道消息

字段名 说明 类型 必需性
packetType 渠道消息 (NOTIFY_CHANNEL_CHAT) 字符串 Y
body 请求数据 对象 Y

正文

字段名 描述 类型 必填 示例
gameIndex Hive 游戏索引 integer Y e.g. 1
from 发送频道消息的账户标识符
Hive 玩家 ID		 long Y e.g. 2222
fromExtra 用户附加信息 (UTF-8 标准)
(最大 256 字节)		 string Y e.g. "bbbb"
to 发送频道消息的频道 ID string Y e.g. "open:10"
langCode Hive 语言代码
(基于 ISO 639 alpha-2，未按 ISO 639 alpha-2 区分的语言需附加 Script 标签)		 string Y e.g. "ko"
timestamp 发送频道消息的时间 (UTC+0 标准，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) string Y e.g. "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) 字符串 Y
body 请求数据 对象 Y

主题

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

示例

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