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

基本信息¶

在使用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`)	字符串	是
Content-Type	请求数据的类型 (`application/json`)	字符串	是

响应代码¶

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 游戏索引	整数	Y
channelId	查询的频道ID	字符串	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	是

响应主体¶

字段名称	描述	类型
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 游戏索引	整数	是
channelId	查询的频道 ID	字符串	是

头部参数¶

字段名称	描述	类型	必需
Authorization	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

头部参数¶

字段名称	描述	类型	必需
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
直播	`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`)	字符串	是
Content-Type	请求数据的类型 (`application/json`)	字符串	是

请求体¶

这是请求进入频道时所需的数据。

字段名称	描述	类型	必需
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	字符串	是

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	是
Content-Type	请求数据的类型 (`application/json`)	字符串	是

请求体¶

这是请求退出频道时所需的传输数据。

字段名称	描述	类型	必需
playerId	要删除的用户的玩家ID Hive	long	Y

响应体¶

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

请求示例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channels/guild:12345/exit' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
    "playerId": 1001
}'

响应示例¶

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

用户 API 功能¶

这解释了聊天服务中使用的用户 API 的 API 请求和响应，以及示例代码。

用户令牌发放¶

为连接到套接字服务器发放身份验证令牌。

通过发出的令牌连接到返回的Socket服务器地址。

请求 URL¶

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

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	是
playerId	Hive 玩家ID	长整型	是

头部参数¶

字段名称	描述	类型	必需
Authorization	API调用的认证令牌（`Bearer`）	字符串	Y

响应主体¶

字段名称	描述	类型
code	响应结果代码	整数
message	结果消息	字符串
data	响应数据	对象

响应体 > 数据¶

字段名称	描述	类型
gameIndex	Hive 游戏索引	整数
socketAddress	套接字服务器地址	字符串
token	发放的令牌	字符串

请求示例¶

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

响应示例¶

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

用户参与渠道查询¶

检索用户参与的频道列表。

请求 URL¶

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

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	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	渠道创建日期和时间（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

头部参数¶

字段名称	描述	类型	必需
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 游戏索引	字符串	是
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."
}

消息 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（如果未提供，则发送到所有频道）	字符串	否
langCode	发送消息的用户的 Hive 语言代码（如果未提供，则不考虑语言发送） (基于 ISO 639 alpha-2，未通过 ISO 639 alpha-2 区分的语言应通过 Script 标签分隔)	字符串	否
message	要发送的公告消息的内容 (最多 200 个字符)	字符串	是

频道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 游戏索引	整数	是
playerId	Hive 玩家ID	长整型	是

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	Y
Content-Type	请求数据的类型 (`application/json`)	字符串	Y

请求体¶

这是请求发送通知消息时所需的传输数据。

字段名称	描述	类型	必需
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`)	字符串	Y
Content-Type	请求数据的类型 (`application/json`)	字符串	Y

请求体¶

这是请求发送自定义消息时所需的传输数据。

字段名称	描述	类型	是否必需
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

头部参数¶

字段名称	描述	类型	必需
Authorization	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
      },
    ]
  }
}