频道

本指南解释了如何使用API来创建和删除频道、更新频道信息以及检索频道列表和参与者。

概述¶

频道是一个概念空间，聊天在这里进行，所有游戏内聊天都发生在频道内。

本节描述了API支持的通道类型和通道操作方法。

渠道类型¶

可以通过 API 请求创建以下频道类型。

渠道类型	成员	参与限制	断开时离开	主要用例
`PUBLIC`	1 ~ 5000	最多10人	O	开放聊天，活动
`GROUP`	1 ~ 500	最多10人	X	公会，团队，聚会
`PRIVATE`	1 ~ 500	最多10人	X	朋友，私人群组
`ONE_ON_ONE`	2	最多200人	X	一对一聊天

PUBLIC 频道适合与未指定参与者进行公开聊天。
只有连接到套接字服务器的用户才能加入该频道。
GROUP 和 PRIVATE 频道适合公会、朋友或聚会等群聊。
PRIVATE 频道需要密码才能加入。

渠道操作¶

通道的基本操作如下：

渠道有明确的进入和退出点，聊天服务器在每个点提供一致的处理。
当消息发送到一个频道时，它会被送达频道中的所有用户（除被阻止的用户外）。
只有频道参与者可以向频道发送消息（通知消息是一个例外）。

以下描述了使用通道 API 时的行为。

渠道创建和删除¶

您可以使用创建渠道或创建 1:1 渠道 API 创建渠道。
- 对于 1:1 渠道（ONE_ON_ONE），请使用创建 1:1 渠道 API。
渠道在以下情况下被删除：
- 当使用删除渠道 API 时
- 当渠道所有者不是 SYSTEM 且没有参与者时，渠道会定期被删除。
如果在有参与者的情况下删除渠道，将向参与者发送渠道删除事件。

渠道信息更新¶

您可以使用更新渠道 API 更新渠道信息。
- 可更新项目：频道名称、最大成员数、密码、聊天记录可用性
- 如果您将最大成员数减少到当前参与者数量以下，现有参与者不会被强制移除。
- 1:1 渠道（ONE_ON_ONE）信息无法更新。

创建频道 API¶

创建一个新频道。

如果请求体参数 playerId 被包含，则具有该 playerId 的用户将成为频道所有者，并自动加入频道。如果不包含 playerId，则频道所有者设置为 SYSTEM。

以下类型的频道会定期被删除：

所有者不是 SYSTEM 且没有参与者的频道

请求 URL¶

服务器	URL
生产环境	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channel`
沙盒环境	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channel`
HTTP 方法	`POST`
内容类型	`application/json`

路径参数¶

字段名称	描述	类型	是否必需
gameIndex	Hive 游戏索引	整数	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	Y
Content-Type	请求数据的类型 (`application/json`)	字符串	Y

请求体¶

字段名称	描述	类型	必需
channelId	渠道 ID (允许使用英文字母、数字和某些特殊字符(`-`, `.`, `_`, `~`, `:`)，最多 100 个字符)	字符串	是
playerId	渠道创建者的玩家 ID	长整型	否
password	密码（`PRIVATE` 渠道必需） (最多 50 个字符)	字符串	否
channelName	渠道名称 (最多 50 个字符)	字符串	是
maxMemberCount	渠道参与者的最大数量 (从 2 到 5,000)	整数	是
type	渠道类型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字符串	是
chatHistoryAllowed	消息历史可查看 (默认: `false`)	布尔值	否

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串
data	响应数据	对象

响应主体 > 数据¶

字段名称	描述	类型
channelId	渠道 ID	字符串
type	渠道类型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字符串
gameIndex	Hive 游戏索引	整数
owner	渠道拥有者	字符串
channelName	渠道名称	字符串
maxMemberCount	渠道参与者的最大数量	整数
chatHistoryAllowed	消息历史可查看	布尔值
regTime	渠道创建日期和时间 (`UTC+0` 标准，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	字符串
regTimeMillis	渠道创建日期和时间 (Unix时间戳毫秒)	长整型

请求示例¶

curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/channel' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "channelId": "open:12345",
    "channelName": "Open Chat Room",
    "maxMemberCount": 100,
    "type": "PUBLIC",
    "chatHistoryAllowed": true
}'

响应示例¶

{
    "code": 0,
    "message": "Success.",
    "data": {
        "channelId": "open:12345",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "Open Chat Room",
        "chatHistoryAllowed": true,
        "maxMemberCount": 100,
        "regTime": "2025-07-21T08:39:07.542913300Z",
        "regTimeMillis": 1753087147542
  }
}

创建 1:1 渠道 API¶

创建一个1:1频道，并将请求数据中对应于playerId和otherPlayerId的用户加入到1:1频道（ONE_ON_ONE）。如果已经存在1:1频道（ONE_ON_ONE），则加入现有频道。

每个用户最多可以拥有 200 个 1:1 通道 (ONE_ON_ONE)。

请求 URL¶

服务器	URL
生产环境	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/1on1`
沙盒环境	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/1on1`
HTTP 方法	`POST`
内容类型	`application/json`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的身份验证令牌 (`Bearer`)	字符串	是
Content-Type	请求数据的类型 (`application/json`)	字符串	是

请求体¶

字段名称	描述	类型	必需
playerId	玩家ID	long	是
otherPlayerId	对手玩家ID	long	是
chatHistoryAllowed	消息历史可见（默认：`false`）	boolean	否

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串
data	响应数据	对象

响应体 > 数据¶

字段名称	描述	类型
channelId	渠道 ID	字符串
type	渠道类型 (`ONE_ON_ONE`)	字符串
gameIndex	Hive 游戏索引	整数
owner	渠道拥有者	字符串
channelName	渠道名称	字符串
maxMemberCount	渠道参与者的最大数量	整数
chatHistoryAllowed	可查看的消息历史	布尔值
regTime	渠道创建日期和时间（`UTC+0` 标准，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	字符串
regTimeMillis	渠道创建日期和时间（Unix时间戳毫秒）	长整型

请求示例¶

curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/channel/1on1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "playerId": 1000,
    "otherPlayerId": 2000,
    "chatHistoryAllowed": false
}'

响应示例¶

{
    "code": 0,
    "message": "Success.",
    "data": {
        "channelId": "V0FQBKSa9bWC33v",
        "type": "ONE_ON_ONE",
        "gameIndex": 1,
        "owner": "100",
        "channelName": "100&200",
        "chatHistoryAllowed": true,
        "maxMemberCount": 2,
        "regTime": "2025-07-18T09:37:36.697035738Z",
        "regTimeMillis": 1752831456697
    }
}

更新频道 API¶

更新现有频道。

仅可以更新以下类型的频道：

公开
私有
组

在更新聊天频道的最大参与者人数时，即使当前频道中的用户数量超过新限制，现有用户也不会被强制移除。因此，如果您将最大参与者人数减少到当前人数以下，将会出现一个临时状态，参与者人数超过最大限制。

请求 URL¶

服务器	URL
生产环境	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
沙盒环境	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
HTTP 方法	`PATCH`
内容类型	`application/json`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y
channelId	渠道ID	字符串	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	是
Content-Type	请求数据的类型 (`application/json`)	字符串	是

请求体¶

字段名称	描述	类型	必需
channelName	频道名称（最多50个字符）	字符串	否
password	密码（`PRIVATE`频道必需）（最多50个字符）	字符串	否
maxMemberCount	频道参与者的最大数量	整数	否
type	频道类型（`PRIVATE`，`PUBLIC`，`GROUP`）	字符串	否
chatHistoryAllowed	消息历史可查看（默认：`false`）	布尔值	否

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串
data	响应数据	对象

请求示例¶

curl --request PATCH 'https://api-chat.withhive.com/api/v1/games/1/channels/testchannel' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "channelName": "Open Chat Room",
    "maxMemberCount": 100,
    "type": "PUBLIC",
    "chatHistoryAllowed": true
}'

响应示例¶

{
    "code": 0,
    "message": "Success."
}

删除频道 API¶

删除一个频道，并向参与该频道的用户发送频道删除事件。

请求 URL¶

服务器	URL
生产环境	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
沙盒环境	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
HTTP 方法	`DELETE`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y
channelId	渠道 ID	字符串	Y

头部参数¶

字段名称	描述	类型	是否必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	Y

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串

请求示例¶

curl --request DELETE 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
    "code": 0,
    "message": "Success."
}

获取频道 API¶

检索已创建的频道列表。可以检索的频道类型如下：

公开
私有
组

请求 URL¶

服务器	URL
生产环境	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels`
沙盒环境	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels`
HTTP 方法	`GET`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y

头部参数¶

字段名称	描述	类型	必需
授权	API 调用的身份验证令牌 (`Bearer`)	字符串	是

查询参数¶

字段名称	描述	类型	是否必需
type	渠道类型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字符串	否
channelId	检索以频道 ID 开头的频道	字符串	否
channelName	检索包含频道名称的频道	字符串	否
sort	排序标准 (`channelId`, `channelName`, `regTime`) (默认: `regTime`)	字符串	否
order	排序顺序 (`ASC`, `DESC`) (默认: `DESC`)	字符串	否
size	每页检索的频道数量 (最小 1 - 最大 10, 默认: `10`)	整数	否
page	要检索的页码 (从 1 开始, 默认: `1`)	整数	否

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串
data	响应数据	对象

响应主体 > 数据¶

字段名称	描述	类型
content	渠道列表	对象数组
page	页面信息	对象

响应主体 > 数据 > 内容¶

字段名称	描述	类型
channelId	渠道 ID	字符串
type	渠道类型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字符串
gameIndex	Hive 游戏索引	整数
owner	渠道拥有者的玩家 ID	字符串
channelName	渠道名称	字符串
memberCount	当前渠道参与者数量	整数
maxMemberCount	渠道参与者的最大数量	整数
chatHistoryAllowed	可查看的消息历史	布尔值
regTime	渠道创建日期和时间（`UTC+0` 标准，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	字符串
regTimeMillis	渠道创建日期和时间（Unix时间戳毫秒）	长整型

响应主体 > 数据 > 页面¶

字段名称	描述	类型
size	每页项目数量	整数
currentPage	当前页码	整数
totalElements	项目总数	整数
totalPages	页数总数	整数

请求示例¶

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels?type=PUBLIC&sort=regTime&order=DESC&size=10&page=1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "content": [
      {
        "channelId": "open:12345",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "Open Chat Room",
        "memberCount": 2,
        "maxMemberCount": 50,
        "chatHistoryAllowed": true,
        "regTime": "2024-12-30T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      /// ... Channel information
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

获取频道 API¶

检索有关特定频道的详细信息。

请求 URL¶

服务器	URL
直播	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
HTTP 方法	`GET`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y
channelId	渠道 ID	字符串	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	Y

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串
data	响应数据	对象

响应体 > 数据¶

字段名称	描述	类型
info	渠道信息	对象
members	参与者列表	对象数组

响应体 > 数据 > 信息¶

字段名称	描述	类型
channelId	渠道 ID	字符串
type	渠道类型 (`PRIVATE`, `PUBLIC`, `GROUP`, `ONE_ON_ONE`)	字符串
gameIndex	Hive 游戏索引	整数
owner	渠道所有者	字符串
channelName	渠道名称	字符串
memberCount	当前参与者人数	整数
maxMemberCount	渠道参与者的最大人数	整数
chatHistoryAllowed	消息历史可见	布尔值
regTime	渠道创建日期和时间（`UTC+0`标准，`yyyy-MM-dd'T'HH:mm:ss.SSSZ`格式）	字符串
regTimeMillis	渠道创建日期和时间（Unix时间戳毫秒）	长整型

响应体 > 数据 > 成员¶

字段名称	描述	类型
playerId	玩家ID	long

请求示例¶

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "info": {
      "channelId": "open:12345",
      "type": "PUBLIC",
      "gameIndex": 1,
      "owner": "SYSTEM",
      "channelName": "Open Chat Room",
      "memberCount": 2,
      "maxMemberCount": 50,
      "chatHistoryAllowed": true,
      "regTime": "2024-12-30T15:01:01.004Z",
      "regTimeMillis": 1731306364351
    },
    "members": [
      {
        "playerId": 1
      },
      {
        "playerId": 2
      }
    ]
  }
}

获取频道成员 API¶

检索参与频道的用户的信息。

请求 URL¶

服务器	URL
直播	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members`
HTTP 方法	`GET`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y
channelId	渠道 ID	字符串	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	是

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串
data	响应数据	对象

响应主体 > 数据¶

字段名称	描述	类型
members	频道参与者列表	对象数组

响应体 > 数据 > 成员¶

字段名称	描述	类型
playerId	玩家 ID	long

请求示例¶

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345/members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "members": [
      {
        "playerId": 1
      },
      {
        "playerId": 2
      }
    ]
  }
}

进入频道 API¶

允许特定用户加入频道。

请求 URL¶

服务器	URL
直播	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter`
HTTP 方法	`POST`
内容类型	`application/json`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y
channelId	渠道 ID	字符串	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	Y
Content-Type	请求数据的类型 (`application/json`)	字符串	Y

请求体¶

字段名称	描述	类型	是否必需
playerId	要加入的用户的玩家ID	long	Y
password	密码（`PRIVATE`频道必需）	string	N

响应体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串

请求示例¶

curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/channels/guild:12345/enter' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
    "playerId": 1001,
    "password": "guildPass123"
}'

响应示例¶

{
    "code": 0,
    "message": "Success."
}

退出通道 API¶

允许用户退出频道。

如果所有者退出，频道不会被删除，除非所有者不是SYSTEM并且没有参与者。

请求 URL¶

服务器	URL
直播	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit`
HTTP 方法	`POST`
内容类型	`application/json`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y
channelId	渠道 ID	字符串	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的身份验证令牌 (`Bearer`)	字符串	Y
Content-Type	请求数据的类型 (`application/json`)	字符串	Y

请求体¶

字段名称	描述	类型	是否必填
playerId	要退出的用户的玩家ID	long	Y

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串

请求示例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channels/guild:12345/exit' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
    "playerId": 1001
}'

响应示例¶

{
    "code": 0,
    "message": "Success."
}