Http api

概覽¶

聊天服務是通過HTTP提供的。API大致分為頻道API、用戶API和消息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`)	字串	是

查詢參數¶

欄位	描述	類型	必需
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	渠道拥有者的玩家 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": "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
    }
  }
}

獲取頻道¶

檢索有關頻道的詳細信息。

請求 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`)	字串
gameIndex	Hive 遊戲索引	整數
owner	頻道擁有者	字串
channelName	頻道名稱	字串
memberCount	當前頻道中的成員數量	整數
maxMemberCount	頻道中允許的最大成員數量	整數
chatHistoryAllowed	是否可以查看消息歷史	布林值
regTime	頻道創建日期和時間 (`UTC+0` 標準，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	字串
regTimeMillis	頻道創建日期和時間（Unix時間戳毫秒）	長整數

回應主體 > 數據 > 成員¶

欄位	描述	類型
playerId	玩家 ID	long
connectedTime	連接日期和時間（`UTC+0` 標準，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	string
connectedTimeMillis	連接日期和時間（UnixTimestamp 毫秒）	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,
        "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	玩家 ID	long
connectedTime	連接日期和時間（`UTC+0` 標準，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	string
connectedTimeMillis	連接日期和時間（UnixTimestamp 毫秒）	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

標頭參數¶

欄位	描述	類型	必填
授權	API 調用的身份驗證令牌 (`Bearer`)	字串	Y
內容類型	請求數據的類型 (`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	結果訊息	字串

請求範例¶

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": "Open Chat Room",
    "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 遊戲索引	整數	是
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."
}

進入頻道¶

輸入一個頻道。

每位用户可以输入的最大频道数为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	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	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伺服器發出身份驗證令牌。

使用發出的令牌連接到返回的 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	玩家ID	长整型	是

標頭參數¶

欄位	描述	類型	必需
授權	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	玩家ID	長整數	Y

標頭參數¶

欄位	描述	類型	必需
授權	API 呼叫的身份驗證令牌 (`Bearer`)	字串	是

回應主體¶

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

回應主體 > 數據¶

欄位	描述	類型
gameIndex	Hive 遊戲索引	整數
playerId	玩家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": "Guild Chat Room",
        "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": "Open Chat Room",
        "memberCount": 2,
        "maxMemberCount": 100,
        "chatHistoryAllowed": true,
        "regTime": "2023-12-20T10:15:30.123Z",
        "regTimeMillis": 1731302348750
      }
      // ... channels
    ]
  }
}

獲取用戶封鎖列表¶

檢索用戶封鎖的用戶列表。

請求 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	玩家ID	長整數	是

標頭參數¶

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

回應主體¶

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

null | 字段 | 描述 | 类型 | | ------------ | ---------------- | ------- | | gameIndex | Hive 游戏索引 | 整数 | | playerId | 玩家ID | 长整型 | | blockedUsers | 被封锁用户列表 | 对象数组 |

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

欄位	描述	類型
blockedPlayerId	被封鎖用戶的玩家ID	long
blockedTime	用戶被封鎖的日期和時間（`UTC+0` 標準，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	string
blockedTimeMillis	用戶被封鎖的日期和時間（UnixTimestamp 毫秒）	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
      },
      // ... Blocked users list
    ]
  }
}

封鎖用戶¶

封鎖另一個用戶。這會限制即時消息的發送和接收。

請求 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 遊戲索引	字串	是
playerId	玩家 ID	長整數	是
blockPlayerId	要被封鎖的玩家 ID	長整數	是

標頭參數¶

欄位	描述	類型	必需
授權	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	玩家ID	長整數	是
blockedPlayerId	要解除封鎖的玩家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

標頭參數¶

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

請求主體¶

請求發送通知消息時要發送的數據。

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

channelId¶

如果提供了 channelId，则会向所有连接到该频道的用户发送频道通知消息。

如果未提供 channelId，則會將用戶通知消息發送給所有連接到應用程序的用戶，並帶有相應的 gameIndex。

null 如果未提供 langCode，則消息將發送給所有用戶，無論語言如何。

如果提供了 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": "Server maintenance. Please reconnect later."
}'

回應範例¶

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

請求主體¶

當請求向用戶發送通知消息時要發送的數據。

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

語言代碼¶

如果未提供 langCode，則消息將不論語言發送給用戶。

如果提供了 langCode，则仅当客户端请求中的 langCode 与此 API 的 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": "This is a notice message for user 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`)	字串	Y
Content-Type	請求數據的類型 (`application/json`)	字串	Y

請求主體¶

在请求发送自定义消息时要发送的数据。

欄位	描述	類型	必填
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": "This is a custom 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 游戏索引	整数	是

標頭參數¶

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

請求主體¶

當請求向用戶發送自定義消息時要發送的數據。

欄位	描述	類型	必填
playerIds	接收消息的帳戶識別碼列表玩家ID列表 (最多10個用戶)	long array	Y
message	要發送的自定義消息內容（`UTF-8`標準） (最多8,000字節)	string	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": "This is a custom message."
}'

回應範例¶

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

獲取頻道消息歷史¶

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

分頁：大小和索引¶

使用 index 查詢參數進行分頁。index 的預設值為無，如果請求是沒有 index，則會根據 size 檢索最新的消息。

例如，如果API以size=5调用而不带index，则将返回5条最近的消息历史记录以及一个nextIndex（例如，68009c30780e4f2d9830d8a0）。

隨後，如果使用 index=68009c30780e4f2d9830d8a0 和 size=5 調用 API，則會檢索到最後返回的消息之前發生的 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	整數	是

標頭參數¶

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

查詢參數¶

請求以檢索頻道消息歷史記錄時所需的查詢字符串數據。

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

回應主體¶

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

回應主體 > 數據¶

欄位	描述	類型
hasNext	是否可以檢索更多數據	布林值
nextIndex	用於檢索的下一個索引	字串
content	頻道消息歷史	物件陣列

回應主體 > 數據 > 內容¶

字段	描述	类型
gameIndex	Hive 游戏索引	整数
from	接收消息的账户标识符玩家ID	长整型
extraData	额外用户信息（`UTF-8`标准）（最大256字节）	字符串
to	消息发送到的频道ID	字符串
message	消息内容	字符串
langCode	Hive 语言代码（基于ISO 639 alpha-2，使用脚本标签区分未被ISO 639 alpha-2分类的语言）	字符串
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": [
    // size=50이므로 아래와 같은 객체들을 50개 반환함.
      {
        "gameIndex": 1,
        "from": 1111112,
        "extraData": "Kim Hive",
        "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": "Hive2",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:51:01.689Z",
        "timestampMillis": 1741150261689
      },
    ]
  }
}