HTTP API

概述¶

我們提供一個通過 HTTP 的聊天服務。它主要由 Channel API、User API 和 Message API 組成。

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

基本信息¶

使用HTTP API時，我們提供您需要了解的基本信息。

字典的準備¶

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

Hive 認證金鑰：API 調用的身份驗證令牌
- 可以在 Hive 控制台 > 應用中心 > 專案管理 > 遊戲詳情 > 基本資訊 中檢查
遊戲索引：在 Hive 控制台 > 應用中心 > 專案管理 中創建的遊戲索引

頻道類型¶

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

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

請求 URL¶

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

常見標題¶

欄位名稱	描述	類型	必需
授權	API 調用的身份驗證令牌 (`Bearer`)	字串	Y
內容類型	請求數據的類型 (`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 個限制）
	400	自定義訊息大小超過限制。最大大小為 8,000 字節。	自定義訊息大小超過限制（最大 8,000 字節）
403	308	用戶不是頻道的擁有者。	用戶不是頻道的擁有者

通道 API 功能¶

這解釋了聊天服務中使用的通道 API 每個功能的 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`)	字串	是

查詢參數¶

欄位名稱	描述	類型	必填
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	Hive 頻道擁有者的玩家 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": "오픈 채팅방",
        "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
    }
  }
}

頻道查詢¶

正在檢索頻道詳細資訊。

請求 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	頻道最大參與者人數	整數
chatHistoryAllowed	是否允許檢索消息歷史	布林值
regTime	頻道創建日期和時間（基於 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字串
regTimeMillis	頻道創建日期和時間（UnixTimestamp 毫秒）	長整數

回應主體 > 數據 > 成員¶

欄位名稱	描述	類型
playerId	Hive 玩家 ID	long
connectedTime	連接時間（基於 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	string
connectedTimeMillis	連接時間（Unix 時間戳毫秒）	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": "오픈채팅방",
      "memberCount": 2,
      "maxMemberCount": 50,
      "chatHistoryAllowed": true,
      "regTime": "2024-12-30T15:01:01.004Z",
      "regTimeMillis": 1731306364351
    },
    "members": [
      {
        "playerId": 1,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "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 遊戲索引	整數	Y
channelId	要查詢的頻道 ID	字串	Y

標頭參數¶

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

回應主體¶

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

回應主體 > 數據¶

欄位名稱	描述	類型
members	頻道參與者列表	物件陣列

回應主體 > 數據 > 成員¶

欄位名稱	描述	類型
playerId	Hive 玩家 ID	long
connectedTime	連接時間（基於 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	string
connectedTimeMillis	連接時間（Unix 時間戳毫秒）	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,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

創建頻道¶

創建一個新頻道。

當您在請求主體中輸入playerId時，對應於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 遊戲索引	整數	是

標頭參數¶

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

請求主體¶

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

字段名稱	描述	類型	必需
channelId	頻道 ID （允許英文字母、數字和某些特殊字符（`-`、`.`、`_`、`~`、`:`），最多 100 個字符）	字串	是
playerId	頻道創建者的 Hive 的玩家 ID	長整數	否
password	密碼（如果頻道為 `PRIVATE` 則必需）（最多 50 個字符）	字串	否
channelName	頻道名稱（最多 50 個字符）	字串	是
maxMemberCount	頻道中參與者的最大人數（最少 2 到最多 5,000）	整數	是
type	頻道類型（`PRIVATE`、`PUBLIC`、`GROUP`）	字串	是
chatHistoryAllowed	是否可以查看消息歷史（默認為 false）	布林值	否

回應主體¶

欄位名稱	描述	類型
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",
    "chatHistoryAllowed": true
}'

回應範例¶

{
    "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`)	字串	是

回應主體¶

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

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

回應範例¶

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

通道退出¶

移除已加入頻道的用戶。即使頻道擁有者離開，頻道仍將保留。沒有參與者且頻道擁有者不是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	字串	是

標頭參數¶

欄位名稱	描述	類型	必需
授權	API 調用的身份驗證令牌 (`Bearer`)	字串	是
內容類型	請求數據的類型 (`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."
}

使用者 API 功能¶

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

用戶令牌發放¶

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

透過發出的令牌連接到套接字伺服器地址。

請求 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 遊戲索引	整數	Y
playerId	Hive 玩家ID	長整數	Y

標頭參數¶

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

回應主體¶

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

回應主體 > 數據¶

欄位名稱	描述	類型
gameIndex	Hive 遊戲索引	整數
socketAddress	Socket 伺服器地址	字串
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 遊戲索引	整數	Y
playerId	Hive 玩家ID	長整數	Y

標頭參數¶

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

回應主體¶

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

回應主體 > 數據¶

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

回應主體 > 數據 > 頻道¶

欄位名稱	描述	類型
channelId	頻道 ID	字串
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串
gameIndex	Hive 遊戲索引	整數
owner	頻道擁有者	字串
channelName	頻道名稱	字串
memberCount	當前頻道參與者數量	整數
maxMemberCount	頻道參與者的最大數量	整數
chatHistoryAllowed	是否允許檢索消息歷史	布林值
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,
        "chatHistoryAllowed": true,
        "regTime": "2023-12-19T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      {
        "channelId": "open:67890",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 100,
        "chatHistoryAllowed": true,
        "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 遊戲索引	字串	是
playerId	Hive 玩家ID	長整數	是

標頭參數¶

欄位名稱	描述	類型	必填
授權	用於 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時間戳毫秒）	long

請求範例¶

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

標頭參數¶

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

訊息 API 功能¶

這是一個用於發送通知消息或自定義消息的API，或用於從特定頻道檢索消息歷史記錄。

頻道通知消息發送¶

將公告消息發送到特定頻道或所有頻道。

請求 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（如果未提供，則發送到所有頻道）	字串	N
langCode	要發送消息的用戶的 Hive 語言代碼（如果未提供，則不論語言發送）（基於 ISO 639 alpha-2，未被 ISO 639 alpha-2 區分的語言應用 Script 標籤分隔）	字串	N
message	要發送的公告消息內容（最多 200 個字符）	字串	Y

渠道ID¶

如果沒有 channelId，則路徑參數 gameIndex 將向應用中的所有頻道發送消息。

語言代碼¶

如果 langCode 不存在，消息將會發送給所有用戶，不論語言。

如果有 langCode，接收消息的用户将根据字段值而有所不同。例如，如果 langCode 是 en，则通知消息将仅发送给在连接客户端时请求主体 langCode 为 en 的用户。

回應主體¶

欄位名稱	描述	類型
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",
    "langCode": "en",
    "message": "서버 점검이 있습니다. 잠시 후 다시 접속해 주세요."
}'

回應範例¶

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

用戶通知消息發送¶

向用戶發送通知消息。

請求 URL¶

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

路徑參數¶

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

標頭參數¶

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

請求主體¶

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

欄位名稱	描述	類型	必填
langCode	將要發送消息的用戶的 Hive 語言代碼（如果未提供，則無論語言如何都會發送）（基於 ISO 639 alpha-2，未由 ISO 639 alpha-2 區分的語言應使用 Script 標籤分隔）	字串	N
message	要發送的通知消息內容（最多 200 個字符）	字串	Y

語言代碼¶

如果沒有 langCode，則會將消息發送給 playerId 用戶，而不考慮語言。

如果有 langCode，用户通知消息仅在 API 请求主体中的 langCode 与客户端连接时请求主体中的 langCode 匹配时发送。例如，如果一个 playerId=1111 的用户以 langCode=en 连接到聊天客户端，而用户通知消息发送 API 被调用时使用 playerId=1111, langCode=ja，则不会向该用户发送通知消息。

回應主體¶

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

請求範例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice/users/123123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "langCode": "en",
    "message": "123123 님에게 보내는 공지 메시지입니다."
}'

回應範例¶

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

發送頻道自定義消息¶

向所有加入頻道的用戶發送自定義消息。

請求 URL¶

伺服器	URL
直播	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId}`
沙盒	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId}`
HTTP 方法	`POST`
內容類型	`application/json`

路徑參數¶

欄位名稱	描述	類型	必需
gameIndex	Hive 遊戲索引	整數	Y
channelId	接收消息的頻道ID	字串	Y

標頭參數¶

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

請求主體¶

這是請求發送自定義消息時所需的傳輸數據。

欄位名稱	描述	類型	必填
message	要發送的自定義消息內容（`UTF-8` 編碼）（最多 8,000 字節）	字串	Y

回應主體¶

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

請求範例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/channels/public:123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "message": "커스텀 메시지입니다."
}'

回應範例¶

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

發送用戶自定義消息¶

向用戶發送自定義消息。

請求 URL¶

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

路徑參數¶

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

標頭參數¶

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

請求主體¶

這是請求發送自定義消息時所需的傳輸數據。

欄位名稱	描述	類型	必填
playerIds	一組帳戶識別碼，用於接收消息 Hive 玩家 ID 列表 (最多 10 個)	長整數陣列	是
message	要發送的自定義消息內容（基於 `UTF-8`） (最多 8,000 字節)	字串	是

回應主體¶

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

請求範例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/users' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "playerIds": [
        123123
    ],
    "message": "커스텀 메시지입니다."
}'

回應範例¶

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

渠道消息歷史檢索¶

檢索頻道消息歷史。頻道消息歷史是通過基於游標的分頁提供的，並且只能檢索過去30天的頻道消息歷史。此API僅在頻道設置中啟用了查看先前對話歷史的選項時才能使用。API響應中接收到的頻道消息歷史可能包括來自被封鎖用戶的過去消息。

分頁：大小和索引¶

使用查詢參數 index 提供分頁。index 沒有預設值，如果請求中不包含 index，則將返回從最新開始到指定 size 的聊天消息。

例如，如果您在不指定index的情況下調用API並使用size=5，它將返回最近的5條聊天記錄和一個nextIndex（例如，像68009c30780e4f2d9830d8a0這樣的值），允許您接收下一條記錄。

在重新調用API，使用index=68009c30780e4f2d9830d8a0和size=5後，它將返回在之前返回的最後聊天記錄之後發生的5條聊天記錄。

分頁：有下一頁¶

如果回應值 hasNext 為 true，則表示還有更多過去的聊天記錄。換句話說，您可以使用回應值 nextIndex 作為 index 來檢索更多以前的頻道消息記錄。

請求 URL¶

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

路徑參數¶

欄位名稱	描述	類型	必填
gameIndex	Hive 遊戲索引	整數	Y
channelId	查詢的頻道 ID	整數	Y

標頭參數¶

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

查詢參數¶

這是請求頻道消息檢索時所需的查詢字符串數據。

欄位名稱	描述	類型	必填
size	頻道歷史大小 (最小 1 ~ 最大 50)	整數	是
index	用於檢索的索引（如果未提供，則檢索最新的消息）	字串	否

回應主體¶

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

回應主體 > 數據¶

欄位名稱	描述	類型
hasNext	是否可以進行額外檢索	boolean
nextIndex	用於下一次檢索的索引	string
content	頻道消息歷史	物件陣列

回應主體 > 數據 > 內容¶

字段名称	描述	类型
gameIndex	Hive 游戏索引	整数
from	接收消息的账户标识符 Hive 玩家 ID	长整型
extraData	用户附加信息（`UTF-8` 编码）（最大 256 字节）	字符串
to	发送消息的频道 ID	字符串
message	消息内容	字符串
langCode	Hive 语言代码（基于 ISO 639 alpha-2，ISO 639 alpha-2 未区分的语言应使用 Script 标签分隔）	字符串
timestamp	消息发送的日期和时间（`UTC+0` 基础，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	字符串
timestampMillis	消息发送的日期和时间（Unix时间戳毫秒）	长整型

請求範例¶

curl --request GET 'https://test-api-chat.withhive.com/api/v1/games/1/channels/open:1/messages?size=50' \
--header 'Authorization: hivechat 005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76'

回應範例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "hasNext": true,
    "nextIndex": "67c7d83336af25202c1c0ad4",
    "content": [
    // as size=50, returns 50 objects each of which is like the followings.
      {
        "gameIndex": 1,
        "from": 1111112,
        "extraData": "김하이브",
        "to": "open:10",
        "message": "zzz",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:50:59.757Z",
        "timestampMillis": 1741150259757
      },
      {
        "gameIndex": 1,
        "from": 1111111,
        "extraData": null,
        "to": "open:10",
        "message": "하이브2",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:51:01.689Z",
        "timestampMillis": 1741150261689
      },
    ]
  }
}