頻道

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

概述¶

頻道是一個概念空間，聊天在此進行，所有遊戲內的聊天都發生在頻道中。

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

頻道類型¶

以下的頻道類型可以通過 API 請求創建。

頻道類型	成員	參與限制	斷開連接時離開	主要用例
`PUBLIC`	1 ~ 5000	最多 10	O	開放聊天，活動
`GROUP`	1 ~ 500	最多 10	X	公會，團隊，派對
`PRIVATE`	1 ~ 500	最多 10	X	朋友，私人群組
`ONE_ON_ONE`	2	最多 200	X	1:1 聊天

PUBLIC 頻道適合與未指定參與者的公開聊天。
只有連接到 socket 伺服器的用戶才能加入該頻道。
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	頻道創建日期和時間（UnixTimestamp 毫秒）	長整數

請求範例¶

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`)	字串	Y
Content-Type	請求數據的類型 (`application/json`)	字串	Y

請求主體¶

欄位名稱	描述	類型	必填
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`)	字串	Y
Content-Type	請求數據的類型 (`application/json`)	字串	Y

請求主體¶

欄位名稱	描述	類型	必填
channelName	頻道名稱 (最多 50 個字元)	字串	N
password	密碼 (對於 `PRIVATE` 頻道是必填的) (最多 50 個字元)	字串	N
maxMemberCount	頻道參與者的最大數量	整數	N
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串	N
chatHistoryAllowed	可查看的訊息歷史 (預設: `false`)	布林	N

回應主體¶

欄位名稱	描述	類型
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

標頭參數¶

欄位名稱	描述	類型	必需
授權	用於 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

標頭參數¶

欄位名稱	描述	類型	是否必填
Authorization	API 呼叫的驗證令牌 (`Bearer`)	字串	Y

查詢參數¶

欄位名稱	描述	類型	是否必填
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串	否
channelId	根據頻道 ID 檢索以頻道 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	頻道創建日期和時間（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 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	頻道創建日期和時間（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 遊戲索引	整數	Y
channelId	頻道 ID	字串	Y

標頭參數¶

欄位名稱	描述	類型	必需
授權	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`)	字串	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`)	字串	是
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."
}