HTTP API

概要¶

HTTP API 提供與 API 伺服器的 HTTP 通信以提供聊天服務。主要由頻道 API 和用戶 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 控制台 > 應用中心 > 專案管理 > 遊戲詳細 > 基本資訊 可查詢
遊戲索引(Game Index): 在 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

標頭參數¶

欄位名稱	說明	類型	必填
Authorization	用於 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	頻道列表	array
page	頁面資訊	object

回應主體 > 數據 > 內容¶

欄位名稱	說明	類型
channelId	頻道 ID	字串
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串
gameIndex	Hive 遊戲索引	整數
owner	頻道擁有者的 Hive 玩家 ID	字串
channelName	頻道名稱	字串
maxMemberCount	最大頻道參與人數	整數
regTime	頻道創建時間 (`UTC+0` 基準, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	字串

回應主體 > 數據 > 頁面¶

欄位名稱	說明	類型
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",
        "maxMemberCount": 50,
        "regTime": "2024-12-30T15:01:01.004Z"
      },
      /// ... 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 遊戲索引	整數	Y
channelId	查詢的頻道 ID	字串	Y

標頭參數¶

欄位名稱	說明	類型	必要性
Authorization	用於 API 調用的認證令牌 (`Bearer`)	字串	Y

回應主體¶

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

回應主體 > 數據¶

欄位名稱	說明	類型
info	頻道資訊	物件
members	參與者列表	陣列

回應主體 > 數據 > 資訊¶

欄位名稱	說明	類型
channelId	頻道 ID	字串
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串
gameIndex	Hive 遊戲索引	整數
owner	頻道擁有者	字串
channelName	頻道名稱	字串
maxMemberCount	最大頻道參與人數	整數
regTime	頻道創建時間 (`UTC+0` 基準, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	字串

回應主體 > 數據 > 成員¶

欄位名稱	說明	類型
playerId	Hive 玩家 ID	long
extraData	附加資料 (`UTF-8` 為基準) (最大 256 Byte)	string
connectedTime	連接時間 (`UTC+0` 為基準, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	string

請求範例¶

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",
        "maxMemberCount": 50,
        "regTime": "2024-12-30T15:01:01.004Z"
    },
    "members": [
      {
        "playerId": 1,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:06.604Z"
      },
      {
        "playerId": 2,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:16.233Z"
      }
    ]
  }
}

查詢頻道參與者¶

查詢特定頻道的參與者資訊。

請求網址¶

伺服器	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members`
HTTP METHOD	`GET`

路徑參數¶

欄位名稱	說明	類型	必填與否
gameIndex	Hive 遊戲索引	整數	Y
channelId	查詢的頻道 ID	字串	Y

標頭參數¶

欄位名稱	說明	類型	必填 여부
Authorization	用於 API 呼叫的認證令牌 (`Bearer`)	字串	Y

回應主體¶

欄位名稱	說明	類型
code	回應結果代碼	整數
message	結果消息	字串
data	回應數據	物件

回應主體 > 數據¶

欄位名稱	說明	類型
members	頻道參與者名單	array

回應主體 > 數據 > 成員¶

欄位名稱	說明	類型
playerId	Hive 玩家 ID	long
extraData	附加資料 (`UTF-8` 為基準) (最大 256 Byte)	string
connectedTime	連接時間 (`UTC+0` 為基準, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	string

請求範例¶

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

創建頻道¶

創建新的對話頻道。

如果存在playerId，则将该用户加入频道。如果没有playerId，则owner将为SYSTEM。

請求網址¶

伺服器	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channel`
SANDBOX	`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 字元)	字串	Y
playerId	頻道創建者的 Hive 玩家 ID	長整數	N
password	密碼 (`PRIVATE` 頻道時必填) (最多 50 字元)	字串	N
channelName	頻道名稱 (最多 50 字元)	字串	Y
maxMemberCount	最大頻道參與人數 (最少 2 人 ~ 最多 5,000 人)	整數	Y
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串	Y

回應主體¶

欄位名稱	說明	類型
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

標頭參數¶

欄位名稱	說明	類型	必填與否
Authorization	用於 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
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter`
SANDBOX	`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`)	字串	Y
Content-Type	請求資料的類型 (`application/json`)	字串	Y

請求主體¶

進入頻道請求時所需的傳輸數據。

欄位名稱	說明	類型	必填與否
playerId	進入的用戶的 Hive 玩家 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-raw '{
    "playerId": 1001,
    "password": "guildPass123"
}'

回應範例¶

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

頻道退出¶

將用戶從頻道中踢出。如果頻道擁有者退出，該頻道將被刪除。

請求 URL¶

伺服器	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

路徑參數¶

欄位名稱	說明	類型	是否必填
gameIndex	Hive 遊戲索引	整數	是
channelId	頻道 ID	字串	是

標頭參數¶

欄位名稱	說明	類型	必填與否
Authorization	用於 API 呼叫的認證令牌 (`Bearer`)	字串	Y
Content-Type	請求資料的類型 (`application/json`)	字串	Y

請求主體¶

當請求退出頻道時，所需的傳輸數據。

欄位名稱	說明	類型	必填與否
playerId	要退出的用戶的 Hive 玩家 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."
}

通知消息發送¶

在遊戲內向特定頻道或所有頻道發送公告消息。如果沒有 channelId 參數，則公告消息將傳送到該 gameIndex 創建的所有頻道。

請求網址¶

伺服器	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`不存在則發送到所有頻道)	字串	N
message	要發送的公告消息內容	字串	Y

回應主體¶

欄位名稱	說明	類型
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": "Server maintenance is in progress. Please try connecting again later."
}'

回應範例¶

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

用戶 API 功能¶

說明用於聊天服務的用戶 API 的功能別 API 請求和回應、範例代碼。

用戶令牌發放¶

發放用於連接 Socket 伺服器的認證令牌。

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

請求網址¶

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

路徑參數¶

欄位名稱	說明	類型	必填與否
gameIndex	Hive 遊戲索引	整數	Y
playerId	Hive 玩家 ID	長整數	Y

標頭參數¶

欄位名稱	說明	類型	必要性
Authorization	用於 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 遊戲索引	整數	是
playerId	Hive 玩家 ID	長整數	是

標頭參數¶

欄位名稱	說明	類型	必填與否
Authorization	用於 API 調用的認證令牌 (`Bearer`)	字串	Y

回應主體¶

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

回應主體 > 數據¶

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

回應主體 > 數據 > 頻道¶

欄位名稱	說明	類型
channelId	頻道 ID	字串
type	頻道類型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字串
gameIndex	Hive 遊戲索引	整數
owner	頻道擁有者	字串
channelName	頻道名稱	字串
maxMemberCount	最大頻道參與人數	整數
regTime	頻道創建時間 (`UTC+0` 為基準，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	字串

請求範例¶

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",
        "maxMemberCount": 50,
        "regTime": "2023-12-19T15:01:01.004Z"
      },
      {
        "channelId": "open:67890",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "Open chat room",
        "maxMemberCount": 100,
        "regTime": "2023-12-20T10:15:30.123Z"
      }
      // ... 채널
    ]
  }
}

用戶封鎖列表查詢¶

查詢用戶已封鎖的用戶列表。

請求網址¶

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

路徑參數¶

欄位名稱	說明	類型	是否必填
gameIndex	Hive 遊戲索引	字串	是
playerId	Hive 玩家 ID	長整數	是

標頭參數¶

欄位名稱	說明	類型	必填與否
Authorization	用於 API 調用的認證令牌 (`Bearer`)	字串	Y

回應主體¶

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

回應主體 > 數據¶

欄位名稱	說明	類型
gameIndex	Hive 遊戲索引	整數
playerId	Hive 玩家 ID	長整數
blockedUsers	阻擋名單	陣列

回應主體 > 數據 > 區塊¶

欄位名稱	說明	類型
blockedPlayerId	被封鎖用戶的 Hive 玩家 ID	long
blockedTime	封鎖時間 (`UTC+0` 為基準，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式)	string

請求範例¶

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,
    "blocks": [
      {
        "blockedPlayerId": 1002,
        "blockedTime": "2023-12-20T10:15:30.123Z"
      },
      {
        "blockedPlayerId": 1003,
        "blockedTime": "2023-12-21T08:45:12.456Z"
      },
      // ... Block list
    ]
  }
}

用戶封鎖¶

用戶阻止特定用戶。

請求 URL¶

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

路徑參數¶

欄位名稱	說明	類型	必填與否
gameIndex	Hive 遊戲索引	字串	是
playerId	Hive 玩家 ID	長整數	是
blockPlayerId	要封鎖的 Hive 玩家 ID	長整數	是

標頭參數¶

欄位名稱	說明	類型	是否必填
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
直播	`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	長整數	是

標頭參數¶

欄位名稱	說明	類型	必填與否
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."
}