HTTP API

概述¶

HTTP API 透過 HTTP 與 API 伺服器進行通信來提供聊天服務。它主要由 Channel API 和 User API 組成。

頻道 API 和用戶 API 的主要特點如下。

頻道 API
- 獲取所有頻道列表 API
- 頻道檢索 API
- 頻道參與者檢索 API
- 頻道創建 API
- 頻道刪除 API
- 頻道進入 API
- 頻道退出 API
- 公告消息發送 API
用戶 API
- 用戶令牌發放 API
- 用戶參與的頻道檢索 API
- 用戶封鎖列表檢索 API
- 用戶封鎖 API
- 用戶解除封鎖 API

基本信息¶

這提供了使用HTTP API時您需要知道的基本資訊。

準備¶

要使用 HTTP API，您需要準備以下項目。

Hive 認證金鑰 (Hive Certification Key): 用於 API 調用的身份驗證令牌
- 可以在 Hive 控制台 > 應用中心 > 專案管理 > 遊戲詳情 > 基本資訊 中找到
遊戲索引: 在 Hive 控制台 > 應用中心 > 專案管理 中創建的遊戲的索引

頻道類型¶

發送 HTTP API 時使用的通道類型如下。

類型	描述
`PUBLIC`	任何人都可以進入的頻道
`PRIVATE`	需要輸入密碼才能進入的頻道
`GROUP`	只有特定用戶可以參加的頻道（例如，公會頻道）

請求網址¶

伺服器	URL
直播	`api-chat.withhive.com`
沙盒	`sandbox-api-chat.withhive.com`

常見標題¶

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

回應代碼¶

API 回應代碼

HTTP 狀態碼	代碼	訊息	描述
200	0	成功。	成功
400	100	錯誤的請求。	錯誤的請求
401	101	無效的令牌。	無效的令牌
403	102	禁止。	禁止
404	103	找不到。	找不到
405	104	不允許的方法。	不允許的方法
500	105	內部伺服器錯誤。	內部伺服器錯誤

詳細錯誤代碼 (400, 403)

HTTP 状态码	代码	消息	描述
400	200	重复的频道 ID。	重复的频道 ID
	201	找不到频道或频道已删除。	找不到频道或频道已删除
	202	频道已满。	频道已满，无法进入，超出参与者限制
	203	无效的频道密码。	无效的频道密码
	204	消息大小超出限制。最大大小为 200。	消息大小超出限制（最大 200 个字符）
	300	用户不在会话中。	用户不在会话中（未连接到 Socket 服务器）
	301	用户不在频道中。	用户不在频道中
	302	用户已在频道中。	用户已在频道中
	303	用户已被阻止。	用户已被阻止
	304	阻止列表已满。最大大小为 100。	阻止列表已满（最大 100 人）
	305	用户不在阻止列表中。	用户不在阻止列表中
	306	用户已被阻止。	用户已被阻止
	307	用户可以进入的频道最大数量为 10。	超过用户可以进入的频道数量（限制为 10）
403	308	用户不是频道的拥有者。	用户不是频道的拥有者

通道 API 功能¶

這解釋了聊天服務中使用的通道 API 每個功能的 API 請求和響應，以及示例代碼。

取得所有頻道列表¶

檢索當前創建的頻道列表。

請求網址¶

伺服器	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`)	字串	Y

查詢參數¶

欄位名稱	描述	類型	必填
type	頻道類型（`PRIVATE`、`PUBLIC`、`GROUP`）	字串	否
channelId	檢索以特定頻道 ID 開頭的頻道	字串	否
channelName	檢索包含特定頻道名稱的頻道	字串	否
sort	排序標準（`channelId`、`channelName`、`regTime`）（預設為 `regTime`）	字串	否
order	排序方式（`ASC`、`DESC`）（預設為 `DESC`）	字串	否
size	每頁檢索的頻道數量（最少 10 ~ 最多 100，預設為 10）	整數	否
page	要檢索的頁碼（從 1 開始，預設為 1）	整數	否

回應主體¶

欄位名稱	描述	類型
code	回應代碼	整數
message	結果訊息	字串
data	回應資料	物件

回應主體 > 數據¶

欄位名稱	描述	類型
content	頻道列表	陣列
page	頁面資訊	物件

回應主體 > 數據 > 內容¶

欄位名稱	描述	類型
channelId	頻道 ID	字串
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串
gameIndex	Hive 遊戲索引	整數
owner	Hive 頻道擁有者的玩家 ID	字串
channelName	頻道名稱	字串
memberCount	當前頻道參與者人數	整數
maxMemberCount	頻道參與者的最大人數	整數
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": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 50,
        "regTime": "2024-12-30T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      /// ... 채널 정보
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

頻道查詢¶

檢索特定頻道的詳細信息。

請求 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

標頭參數¶

欄位名稱	描述	類型	必需
授權	API 調用的身份驗證令牌 (`Bearer`)	字串	Y

回應主體¶

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

回應主體 > 數據¶

欄位名稱	描述	類型
info	頻道資訊	物件
members	參與者名單	陣列

回應主體 > 數據 > 資訊¶

欄位名稱	描述	類型
channelId	頻道 ID	字串
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串
gameIndex	Hive 遊戲索引	整數
owner	頻道擁有者	字串
channelName	頻道名稱	字串
memberCount	當前頻道參與者人數	整數
maxMemberCount	頻道參與者的最大人數	整數
regTime	頻道創建日期和時間（基於 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字串
regTimeMillis	頻道創建日期和時間（Unix時間戳毫秒）	整數

回應主體 > 數據 > 成員¶

字段名稱	描述	類型
playerId	Hive 玩家ID	long
extraData	附加數據 (`UTF-8` 基礎) (最大256字節)	string
connectedTime	連接日期和時間 (`UTC+0` 基礎，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	string
connectedTimeMillis	連接時間（Unix時間戳毫秒）	integer

請求範例¶

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": "오픈채팅방",
      "memberCount": 2,
      "maxMemberCount": 50,
      "regTime": "2024-12-30T15:01:01.004Z",
      "regTimeMillis": 1731306364351
    },
    "members": [
      {
        "playerId": 1,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

頻道參與者查詢¶

檢索特定頻道的參與者資訊。

請求 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	Hive 玩家ID	long
extraData	附加數據 (`UTF-8` 基礎) (最大 256 字節)	string
connectedTime	連接日期和時間 (`UTC+0` 基礎，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	string
connectedTimeMillis	連接時間 (UnixTimestamp 毫秒)	integer

請求範例¶

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,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

創建頻道¶

創建一個新的對話頻道。

如果 playerId 存在，則用戶將被允許進入頻道。如果沒有 playerId，擁有者將是 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`)	字串	是
Content-Type	請求數據的類型 (`application/json`)	字串	是

請求主體¶

這是請求創建頻道時所需的傳輸數據。

欄位名稱	描述	類型	必填
channelId	頻道 ID (允許英文字母、數字及某些特殊字符 (`-`, `.`, `_`, `~`, `:`)，最多 100 個字符)	字串	是
playerId	頻道創建者的 Hive 的玩家 ID	長整數	否
password	密碼（`PRIVATE` 頻道必填） (最多 50 個字符)	字串	否
channelName	頻道名稱 (最多 50 個字符)	字串	是
maxMemberCount	頻道參與者的最大人數 (最少 2，最多 5,000)	整數	是
type	頻道類型（`PRIVATE`、`PUBLIC`、`GROUP`）	字串	是

回應主體¶

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

請求樣本¶

curl --request POST 'https://sandbox-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",
    "playerId": 1000,
    "channelName": "오픈 채팅방",
    "maxMemberCount": 100,
    "type": "PUBLIC"
}'

回應範例¶

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

刪除頻道¶

刪除特定頻道。

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

進入頻道¶

將用戶加入現有頻道。

用戶可以進入的最大頻道數為10。

請求網址¶

伺服器	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 Hive	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-raw '{
    "playerId": 1001,
    "password": "guildPass123"
}'

回應範例¶

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

頻道退出¶

從頻道中移除用戶。即使頻道擁有者離開，頻道仍將保留。

請求 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 Hive	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."
}

通知消息發送¶

將公告消息發送到遊戲中的特定頻道或所有頻道。如果未提供 channelId 參數，則公告消息將發送到為相應的 gameIndex 創建的所有頻道。

請求 URL¶

伺服器	URL
實時	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/notice`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/notice`
HTTP 方法	`POST`
內容類型	`application/json`

路徑參數¶

欄位名稱	描述	類型	必填
gameIndex	Hive 遊戲索引	整數	Y

標頭參數¶

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

請求主體¶

這是請求發送通知消息時所需的傳輸數據。

字段名稱	描述	類型	必需
channelId	要發送消息的頻道 ID（如果未提供 `channelId`，則將發送到所有頻道）	字串	否
message	要發送的公告消息內容	字串	是

回應主體¶

欄位名稱	描述	類型
code	回應結果代碼	整數
message	描述結果訊息	字串

請求範例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "channelId": "open:12345",
    "message": "서버 점검이 있습니다. 잠시 후 다시 접속해 주세요."
}'

回應範例¶

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

用戶 API 功能¶

這解釋了聊天服務中使用的用戶 API 的 API 請求和響應，以及示例代碼。

用戶令牌發放¶

發佈用於連接到套接字伺服器的身份驗證令牌。

透過發出的令牌連接到返回的 Socket 伺服器地址。

請求 URL¶

伺服器	URL
直播	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/token`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/token`
HTTP 方法	`POST`

路徑參數¶

欄位名稱	描述	類型	必填
gameIndex	Hive 遊戲索引	整數	是
playerId	Hive 玩家ID	長整數	是

標頭參數¶

欄位名稱	描述	類型	必填
Authorization	用於 API 調用的身份驗證令牌 (`Bearer`)	字串	Y

回應主體¶

欄位名稱	描述	類型
code	回應結果代碼	整數
message	結果訊息	字串
data	回應資料	物件

回應主體 > 數據¶

欄位名稱	描述	類型
gameIndex	Hive 遊戲索引	整數
socketAddress	插座伺服器地址	字串
token	發行的令牌	字串

請求範例¶

curl  --request POST 'https://api-chat.withhive.com/api/v1/games/1/users/1001/token' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

回應範例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "socketAddress": "wss://test-socket-chat.withhive.com/ws",
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg"
  }
}

用戶參與通道查詢¶

檢索用戶參與的頻道列表。

請求 URL¶

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

路徑參數¶

欄位名稱	描述	類型	必填
gameIndex	Hive 遊戲索引	整數	是
playerId	Hive 玩家ID	長整數	是

標頭參數¶

欄位名稱	描述	類型	必填
授權	用於 API 調用的身份驗證令牌 (`Bearer`)	字串	Y

回應主體¶

欄位名稱	描述	類型
code	回應結果代碼	整數
message	結果訊息	字串
data	回應資料	物件

回應主體 > 數據¶

欄位名稱	描述	類型
gameIndex	Hive 遊戲索引	整數
playerId	Hive 玩家ID	長整數
channels	渠道列表	陣列

回應主體 > 數據 > 頻道¶

欄位名稱	描述	類型
channelId	頻道 ID	字串
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串
gameIndex	Hive 遊戲索引	整數
owner	頻道擁有者	字串
channelName	頻道名稱	字串
memberCount	當前頻道參與者數量	整數
maxMemberCount	頻道參與者的最大數量	整數
regTime	頻道創建日期和時間（基於 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字串
regTimeMillis	頻道創建日期和時間（UnixTimestamp 毫秒）	整數

請求範例¶

curl --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/channels' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

回應範例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "playerId": 1001,
    "channels": [
      {
        "channelId": "guild:12345",
        "type": "GROUP",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "길드 채팅방",
        "memberCount": 1,
        "maxMemberCount": 50,
        "regTime": "2023-12-19T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      {
        "channelId": "open:67890",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 100,
        "regTime": "2023-12-20T10:15:30.123Z",
        "regTimeMillis": 1731302348750
      }
      // ... 채널
    ]
  }
}

用戶封鎖列表檢索¶

檢索用戶阻止的用戶列表。

請求 URL¶

伺服器	URL
實時	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks`
HTTP 方法	`GET`

路徑參數¶

欄位名稱	描述	類型	必填
gameIndex	Hive 遊戲索引	字串	Y
playerId	Hive 玩家ID	長整數	Y

標頭參數¶

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

回應主體¶

欄位名稱	描述	類型
code	回應結果代碼	整數
message	結果訊息	字串
data	回應資料	物件

回應主體 > 數據¶

欄位名稱	描述	類型
gameIndex	Hive 遊戲索引	整數
playerId	Hive 玩家ID	長整數
blockedUsers	被封鎖的用戶列表	陣列

回應主體 > 數據 > 被封鎖的用戶¶

欄位名稱	描述	類型
blockedPlayerId	被封鎖用戶的玩家ID Hive	long
blockedTime	封鎖時間（基於 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	string
blockedTimeMillis	封鎖時間（Unix 時間戳毫秒）	integer

請求範例¶

curl  --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/blocks' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

回應範例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "playerId": 1001,
    "blockedUsers": [
      {
        "blockedPlayerId": 1002,
        "blockedTime": "2023-12-20T10:15:30.123Z",
        "blockedTimeMillis": 1739329550811
      },
      {
        "blockedPlayerId": 1003,
        "blockedTime": "2023-12-21T08:45:12.456Z",
        "blockedTimeMillis": 1739329553137
      },
      // ... 차단 목록
    ]
  }
}

用戶區塊¶

用戶封鎖特定用戶。

請求 URL¶

伺服器	URL
直播	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId}`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId}`
HTTP 方法	`POST`

路徑參數¶

欄位名稱	描述	類型	必需
gameIndex	Hive 遊戲索引	字串	Y
playerId	Hive 玩家ID	長整數	Y
blockPlayerId	封鎖 Hive 玩家ID	長整數	Y

標頭參數¶

欄位名稱	描述	類型	必填
Authorization	用於 API 調用的身份驗證令牌 (`Bearer`)	字串	Y

回應主體¶

欄位名稱	描述	類型
code	回應結果代碼	整數
message	結果訊息	字串

請求範例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

回應範例¶

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

解鎖用戶¶

用戶解除對特定用戶的封鎖。

請求 URL¶

伺服器	URL
實時	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId}`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId}`
HTTP 方法	`DELETE`

路徑參數¶

欄位名稱	描述	類型	必填
gameIndex	Hive 遊戲索引	字串	Y
playerId	Hive 玩家ID	長整數	Y
blockedPlayerId	解鎖 Hive 玩家ID	長整數	Y

標頭參數¶

欄位名稱	描述	類型	必填
Authorization	用於 API 調用的身份驗證令牌 (`Bearer`)	字串	Y

回應主體¶

欄位名稱	描述	類型
code	回應結果代碼	整數
message	結果訊息	字串

請求範例¶

curl --request DELETE 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

回應範例¶

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