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

响应正文¶

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

头部参数¶

字段名称	描述	类型	必需
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 游戏索引	整数	Y
channelId	渠道 ID	字符串	Y

头部参数¶

字段名称	描述	类型	必需
Authorization	API 调用的认证令牌 (`Bearer`)	字符串	Y
Content-Type	请求数据的类型 (`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

头部参数¶

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

响应主体¶

字段名称	描述	类型
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 游戏索引	字符串	是
playerId	Hive 玩家ID	长整型	是

头部参数¶

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

响应主体¶

字段名称	描述	类型
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 游戏索引	字符串	是
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¶

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

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	字符串	Y
playerId	Hive 玩家ID	长整型	Y
blockedPlayerId	Hive 要解锁的玩家ID	长整型	Y

头部参数¶

字段名称	描述	类型	必需
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	字符串	N
langCode	发送消息的用户的 Hive 语言代码（如果未提供，则不考虑语言发送） (基于 ISO 639 alpha-2，ISO 639 alpha-2 无法区分的语言应使用 Script 标签分隔)	字符串	N
message	要发送的公告消息的内容 (最多 200 个字符)	字符串	Y

渠道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`)	字符串	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`)	字符串	是
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

头部参数¶

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

请求体¶

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

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

头部参数¶

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

查询参数¶

这是请求频道消息检索时所需的查询字符串数据。

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