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`)	字符串	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	渠道拥有者的玩家 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	字符串	是

头部参数¶

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

响应主体¶

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

响应主体 > 数据¶

字段	描述	类型
info	渠道信息	对象
members	成员列表	对象数组

响应主体 > 数据 > 信息¶

字段	描述	类型
channelId	频道 ID	字符串
type	频道类型 (`PRIVATE`, `PUBLIC`, `GROUP`)	字符串
gameIndex	Hive 游戏索引	整数
owner	频道拥有者	字符串
channelName	频道名称	字符串
memberCount	当前频道成员数量	整数
maxMemberCount	频道允许的最大成员数量	整数
chatHistoryAllowed	是否可以查看消息历史	布尔值
regTime	频道创建日期和时间（`UTC+0` 标准，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	字符串
regTimeMillis	频道创建日期和时间（Unix时间戳毫秒）	长整型

响应主体 > 数据 > 成员¶

字段	描述	类型
playerId	玩家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": "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

头部参数¶

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

响应正文¶

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

响应主体 > 数据¶

字段	描述	类型
members	渠道成员列表	对象数组

响应主体 > 数据 > 成员¶

字段	描述	类型
playerId	玩家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	渠道创建者的玩家ID	长整型	否
password	密码（`PRIVATE` 渠道必需） (最多50个字符)	字符串	否
channelName	渠道名称 (最多50个字符)	字符串	是
maxMemberCount	渠道允许的最大成员数 (最小2 ~ 最大5,000)	整型	是
type	渠道类型（`PRIVATE`、`PUBLIC`、`GROUP`）	字符串	是
chatHistoryAllowed	是否可以查看消息历史 (默认值为假)	布尔型	否

响应主体¶

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

头部参数¶

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

请求体¶

请求退出频道时所需的数据。

字段	描述	类型	必需
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	长整型	是

头部参数¶

字段	描述	类型	必需
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 游戏索引	整数	是
playerId	玩家ID	长整型	是

头部参数¶

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

响应主体¶

字段	描述	类型
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	渠道创建日期和时间（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": "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 游戏索引	字符串	Y
playerId	玩家ID	长整型	Y

头部参数¶

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

响应主体¶

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

响应主体 > 数据¶

字段	描述	类型
gameIndex	Hive 游戏索引	整数
playerId	玩家ID	长整型
blockedUsers	被阻止的用户列表	对象数组

响应主体 > 数据 > 被阻止的用户¶

字段	描述	类型
blockedPlayerId	被封锁用户的玩家ID	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
      },
      // ... 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	长整型	是

头部参数¶

字段	描述	类型	必需
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	玩家ID	长整型	Y
blockedPlayerId	要解封的玩家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 游戏索引	整数	是

头部参数¶

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

请求体¶

请求发送通知消息时要发送的数据。

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

channelId¶

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

如果未提供 channelId，则会向所有连接到应用程序的用户发送用户通知消息，并带有相应的 gameIndex。

语言代码¶

如果未提供 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 游戏索引	整数	是
playerId	Hive 玩家ID	长整型	是

头部参数¶

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

请求体¶

请求向用户发送通知消息时要发送的数据。

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

语言代码¶

如果未提供 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`)	字符串	是
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": "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 游戏索引	整数	Y

头部参数¶

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

请求体¶

请求向用户发送自定义消息时要发送的数据。

字段	描述	类型	必需
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 的默认值为 none，如果请求中没有 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
      },
    ]
  }
}