频道

本指南描述了如何使用API创建和删除频道、修改频道信息，以及检索频道列表和参与者。

概述¶

频道是一个概念空间，聊天在其中进行，所有游戏内聊天都在频道内进行。

本节描述了API支持的通道类型和通道行为。

渠道类型¶

可以通过 API 创建的频道类型如下：

渠道类型	容量	最大加入频道数	断开连接时离开频道	主要用途
`PUBLIC`	1 – 5,000	最多 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 修改频道信息。
- 可修改字段：频道名称、最大成员数量、密码和聊天记录可用性
- 即使最大成员数量更改为50，而频道已经有100名参与者，现有参与者的状态也不会受到影响。
- 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 游戏索引	整数	是

头部参数¶

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

请求体¶

字段	描述	类型	必需
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 通道（ONE_ON_ONE），并在请求数据中加入与 playerId 和 otherPlayerId 对应的用户。

如果已经存在一个与相同用户的1:1频道，则将加入现有频道。

请求 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`）	字符串	是

请求体¶

字段	描述	类型	必需
channelId	频道 ID （允许使用大写/小写字母、数字和一些特殊字符（`-`、`.`、`_`、`~`、`:`），最大 100 个字符）	字符串	是
channelName	频道名称（最大 50 个字符）	字符串	是
playerId	玩家 ID	长整型	是
otherPlayerId	其他玩家的玩家 ID	长整型	是
chatHistoryAllowed	消息历史是否可用（默认值：`false`）	布尔值	否

响应主体¶

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

响应主体 > 数据¶

字段	描述	类型
channelId	渠道ID	字符串
type	渠道类型（`ONE_ON_ONE`）	字符串
gameIndex	Hive游戏索引	整数
owner	渠道拥有者	字符串
channelName	渠道名称	字符串
maxMemberCount	渠道参与者的最大数量	整数
participants	参与者的玩家ID列表	数组
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'{
    "channelId": "1on1:test",
    "channelName": "Test 1:1 Channel",
    "playerId": 1000,
    "otherPlayerId": 2000,
    "chatHistoryAllowed": false
}'

响应示例¶

{
    "code": 0,
    "message": "Success.",
    "data": {
        "channelId": "1on1:test",
        "type": "ONE_ON_ONE",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "Test 1:1 Channel",
        "chatHistoryAllowed": false,
        "maxMemberCount": 2,
        "participants": [1000, 2000],
        "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 游戏索引	整数	是
channelId	渠道 ID	字符串	是

头部参数¶

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

请求体¶

字段	描述	类型	必需
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	蜂巢游戏索引	整数	是
channelId	要删除的频道ID	字符串	是

头部参数¶

字段	描述	类型	必需
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 游戏索引	整数	是

头部参数¶

字段	描述	类型	必需
授权	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 info
    ],
    "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	蜂巢游戏索引	整数	是
channelId	要检索的频道ID	字符串	是

头部参数¶

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

响应主体¶

字段	描述	类型
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 游戏索引	整数	是
channelId	要检索的频道 ID	字符串	是

头部参数¶

字段	描述	类型	必需
Authorization	API 调用的身份验证令牌（`Bearer`）	字符串	Y

响应主体¶

字段	描述	类型
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 游戏索引	整数	是
channelId	渠道 ID	字符串	是

头部参数¶

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

请求体¶

字段	描述	类型	必需
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	蜂巢游戏索引	整数	是
channelId	渠道ID	字符串	是

头部参数¶

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

请求体¶

字段	描述	类型	必需
playerId	要退出的用户的玩家ID	long	Y

响应主体¶

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

请求示例¶

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."
}