頻道

本指南描述了如何使用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	1:1 聊天

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`)	字串	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 通道（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

標頭參數¶

欄位	描述	類型	必需
授權	API 調用的身份驗證令牌（`Bearer`）	字串	是
內容類型	請求數據類型（`application/json`）	字串	是

請求主體¶

欄位	描述	類型	必填
channelId	頻道 ID （允許大寫/小寫字母、數字和某些特殊字符（`-`、`.`、`_`、`~`、`:`），最多 100 個字符）	字串	是
channelName	頻道名稱（最多 50 個字符）	字串	是
playerId	玩家 ID	長整數	是
otherPlayerId	其他玩家的玩家 ID	長整數	是
chatHistoryAllowed	是否允許消息歷史（默認：`false`）	布林值	否

回應主體¶

欄位	描述	類型
代碼	回應結果代碼	整數
訊息	結果訊息	字串
數據	回應數據	物件

回應主體 > 數據¶

欄位	描述	類型
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	字串	是

標頭參數¶

欄位	描述	類型	必需
授權	API 調用的身份驗證令牌 (`Bearer`)	字串	是
內容類型	請求數據類型 (`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 遊戲索引	整數	是
channelId	要刪除的頻道 ID	字串	是

標頭參數¶

欄位	描述	類型	必需
授權	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`）	字串	N
channelId	根據指定的頻道 ID 檢索頻道	字串	N
channelName	根據指定的頻道名稱檢索頻道	字串	N
sort	排序標準（`channelId`、`channelName`、`regTime`）（默認：`regTime`）	字串	N
order	排序順序（`ASC`、`DESC`）（默認：`DESC`）	字串	N
size	每頁的頻道數量（最小 1 – 最大 10，默認：`10`）	整數	N
page	要檢索的頁碼（從 1 開始，默認：`1`）	整數	N

回應主體¶

欄位	描述	類型
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	頻道創建日期時間（UnixTimestamp 毫秒）	長整數

回應主體 > 數據 > 頁面¶

字段	描述	类型
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	Hive 遊戲索引	整數	是
channelId	要檢索的頻道 ID	字串	是

標頭參數¶

欄位	描述	類型	必填
授權	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	頻道創建日期時間（UnixTimestamp 毫秒）	長整數

回應主體 > 數據 > 成員¶

欄位	描述	類型
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	字串	是

標頭參數¶

欄位	描述	類型	必需
授權	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 遊戲索引	整數	是
channelId	頻道 ID	字串	是

標頭參數¶

欄位	描述	類型	必填
授權	API 呼叫的認證令牌 (`Bearer`)	字串	Y
內容類型	請求資料類型 (`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 遊戲索引	整數	是
channelId	頻道 ID	字串	是

標頭參數¶

欄位	描述	類型	必需
Authorization	API 調用的身份驗證令牌 (`Bearer`)	字串	是
Content-Type	請求數據類型 (`application/json`)	字串	是

請求主體¶

欄位	描述	類型	必需
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."
}