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`

常見標題¶

欄位名稱	描述	類型	必填
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 限制）
	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`)	字串	Y

查詢參數¶

字段名稱	描述	類型	必填
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 遊戲索引	整數	是
channelId	查詢的頻道 ID	字串	是

標頭參數¶

欄位名稱	描述	類型	是否必填
Authorization	用於 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	渠道创建日期和时间（Unix时间戳毫秒）	长整型

回應主體 > 數據 > 成員¶

字段名称	描述	类型
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 遊戲索引	整數	Y

標頭參數¶

欄位名稱	描述	類型	必填
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 遊戲索引	整數	Y
channelId	渠道 ID	字串	Y

標頭參數¶

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

請求主體¶

這是請求進入頻道時所需的數據。

欄位名稱	描述	類型	必填
playerId	要被接納的用戶的玩家ID Hive	long	是
password	密碼（`PRIVATE`頻道必填）	string	否

回應主體¶

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

請求主體¶

這是請求退出通道時所需的傳輸數據。

欄位名稱	描述	類型	必填
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請求和響應，以及示例代碼。

用戶令牌發放¶

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

透過發出的令牌連接到返回的 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 遊戲索引	整數	Y
playerId	Hive 玩家ID	長整數	Y

標頭參數¶

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

回應主體¶

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

標頭參數¶

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

回應主體¶

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

請求範例¶

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

標頭參數¶

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

標頭參數¶

欄位名稱	描述	類型	必填
授權	用於 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 遊戲索引	字串	是
playerId	Hive 玩家ID	長整數	是
blockedPlayerId	Hive 要解除封鎖的玩家ID	長整數	是

標頭參數¶

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

請求主體¶

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

字段名称	描述	类型	必需
channelId	发送消息的频道 ID	字符串	否
langCode	发送消息的用户的 Hive 语言代码（如果未提供，则无论语言如何都发送） (基于 ISO 639 alpha-2，未通过 ISO 639 alpha-2 区分的语言应使用 Script 标签分隔)	字符串	否
message	要发送的公告消息的内容 (最多 200 个字符)	字符串	是

頻道ID¶

如果存在 channelId，則會向所有連接到該頻道的用戶發送頻道通知消息。

如果 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 的用户连接到语言代码为 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 字節)	字串	是

回應主體¶

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

標頭參數¶

欄位名稱	描述	類型	是否必填
授權	API 調用的身份驗證令牌 (`Bearer`)	字串	是
內容類型	請求數據的類型 (`application/json`)	字串	是

請求主體¶

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

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

回應主體¶

欄位名稱	描述	類型
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 遊戲索引	整數	是
channelId	要查詢的頻道 ID	整數	是

標頭參數¶

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

查詢參數¶

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

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

回應主體¶

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

回應主體 > 數據¶

欄位名稱	描述	類型
hasNext	是否可以進行額外的檢索	布林值
nextIndex	用於下一次檢索的索引	字串
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
      },
    ]
  }
}