消息¶

本指南解释了如何使用API查看消息历史、按类型发送消息和翻译消息。

概述¶

本节描述了API支持的消息类型和发送方法，以及消息翻译和其他功能。

渠道消息¶

发送给频道参与者的消息，以广播方式进行操作。
消息历史根据 channelId 提供。

直接消息¶

直接发送给其他用户的消息，以单向方式操作。

通知消息¶

通知消息分为频道通知消息和用户通知消息。

渠道通知消息：仅发送给连接到指定 channelId 的用户。
用户通知消息：仅发送给具有指定 playerId 的用户。

自定义消息¶

自定义消息用于传递大量数据，与常规聊天消息不同，并不用于用户之间的对话。

消息翻译¶

本节解释了自动和手动翻译功能，以及可用于翻译的语言代码。

自动翻译¶

游戏客户端可以设置是否在每个频道启用自动翻译。离开频道或断开与套接字服务器的连接时，设置将被重置。
消息使用连接到套接字服务器时设置的语言代码进行翻译。要更改翻译语言，请使用新的语言代码重新连接。

手动翻译¶

调用AI消息翻译API以执行原始消息的AI翻译。

语言代码¶

语言	本地名称	Hive 语言代码
韩语	한국어	ko
英语	English	en
日语	日本語	ja
中文（简体）	简体中文	zh-hans
中文（繁体）	繁體中文	zh-hant
法语	Français	fr
德语	Deutsch	de
俄语	русский	ru
西班牙语	Español	es
葡萄牙语	Português	pt
印度尼西亚语	Bahasa Indonesia	id
越南语	tiếng Việt	vi
泰语	ไทย	th
意大利语	Italiano	it
土耳其语	Türkçe	tr
阿拉伯语	العربية	ar

附加消息功能¶

可以添加到发送消息中的功能包括点赞、提及和回复。

点赞: 您可以为频道中的每条消息添加或删除“点赞”。
提及: 您可以在频道消息中提及特定用户以发送通知。
回复: 您可以对频道中发送的特定消息进行回复。

渠道消息历史检索 API¶

检索指定 messageId 在频道中之前和之后的消息历史。只有在频道设置中 chatHistoryAllowed 为 true 时才能请求此操作。

频道消息历史是通过基于游标的分页提供的，并且只能检索最近30天的消息历史。

请求 URL¶

服务器	URL
现场	`https://api-chat.withhive.com/api/v2/games/{gameIndex}/channels/{channelId}/messages`
沙盒	`https://sandbox-api-chat.withhive.com/api/v2/games/{gameIndex}/channels/{channelId}/messages`
HTTP 方法	`GET`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	是
channelId	用于检索的频道 ID	整数	是

头部参数¶

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

查询参数¶

字段名称	描述	类型	必需
prevSize	上一个频道消息检索的大小（最小 `0` ~ 最大 `50`） (默认: `0`)	整数	否
nextSize	下一个频道消息检索的大小如果未提供此值，则忽略 `messageId`。（最小 `0` ~ 最大 `50`） (默认: `0`)	整数	否
messageId	用于检索的 messageId（`null` 检索最近的频道消息）	字符串	否
order	基于日期的排序方法（`ASC`，`DESC`） (默认: `DESC`)	字符串	否

prevSize 和 nextSize¶

prevSize 和 nextSize 定义了一次请求中要检索的消息范围。

prevSize 检索先前的消息历史，而 nextSize 根据指定的 messageId 检索后续的消息历史。例如，如果指定了 prevSize=10 和 nextSize=5 以及一个 messageId，则会检索到 messageId 之前的 10 条消息和之后的 5 条消息。

如果调用频道消息历史检索 API 而不指定 messageId，则只会检索最近的消息，数量上限由 prevSize 设置，并且 nextSize 的值将不被应用。

响应体¶

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

响应主体 > 数据¶

字段名称	描述	类型
hasNext	是否可以检索更多消息	boolean
nextMessageId	用于检索下一条消息的 messageId	string
hasPrev	是否可以检索之前的消息	boolean
prevMessageId	用于检索上一条消息的 messageId	string
content	渠道消息历史	对象数组

hasNext : 如果 hasNext 为 true，则还有更多后续消息历史。在这种情况下，您可以根据 nextMessageId 指示的消息 ID 检索更多频道消息历史。
hasPrev : 如果 hasPrev 为 true，则还有更多之前的消息历史。在这种情况下，您可以根据 prevMessageId 指示的消息 ID 检索更多频道消息历史。

响应主体 > 数据 > 内容¶

字段名称	描述	类型
gameIndex	Hive 游戏索引	整数
from	接收消息的账户标识符玩家 ID	长整型
messageId	消息 ID	字符串
extraData	附加用户信息（`UTF-8` 格式）（最大 `256 字节`）	字符串
pluginData	附加消息特性	对象
to	消息发送到的频道 ID	字符串
message	消息内容	字符串
langCode	Hive 语言代码	字符串
timestamp	消息发送的日期和时间（`UTC+0` 基础，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字符串
timestampMillis	消息发送的日期和时间（Unix时间戳毫秒）	长整型

响应主体 > 数据 > 内容 > 插件数据¶

仅在使用了消息附加功能时，才会添加以下数据。

字段名称	描述	类型
like	'喜欢'信息	对象
mentions	提及信息	对象数组
reply	回复信息	对象

响应体 > 数据 > 内容 > 插件数据 > 喜欢¶

字段名称	描述	类型
playerIds	添加了“喜欢”的用户的玩家ID（多个）	长整型数组

响应主体 > 数据 > 内容 > 插件数据 > 提及¶

字段名称	描述	类型
playerId	提到的用户的玩家ID	long

响应主体 > 数据 > 内容 > 插件数据 > 回复¶

字段名称	描述	类型
originalMessageId	原始消息的ID	字符串
originalMessage	原始消息的内容	字符串
originalExtraData	原始消息的附加信息	字符串
originalTimestampMillis	原始消息发送的日期和时间（Unix时间戳毫秒）	长整型

请求示例¶

curl --request GET 'https://test-api-chat.withhive.com/api/v2/games/1/channels/open:1/messages?messageId=abcdefg&nextSize=10&prevSize=10&order=DESC' \
--header 'Authorization: hivechat 005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76'

响应示例¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "hasNext": true,
    "nextMessageId": "XY0QSDRezljxWI02",
    "hasPrev": true,
    "prevMessageId": "j2FwC8Zdq5vwX8kJ",
    "content": [
      {
        "gameIndex": 1,
        "from": 1111112,
        "messageId" : "0n4K8pkqjpWjkrUH",
        "extraData": "김하이브",
        "to": "open:10",
        "message": "안녕하세요.",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:50:59.757Z",
        "timestampMillis": 1741150259757
      },
      {
        "gameIndex": 1,
        "from": 1111111,
        "messageId" : "J3N1YYimo5o7Mpb5",
        "extraData": "",
        "to": "open:10",
        "message": "하이브",
        "langCode": "ko",
        // 메시지 추가 기능을 사용하였을 경우
        "pluginData" : {
          // 좋아요
          "like": {
            "playerIds": [
              1
            ]
          },
          // 멘션
          "mentions": [
            {
              "playerId": 101
              }
          ],
          // 답글
          "reply": {
            "originalMessageId": "yIKzxKCihLVu9VR8",
            "originalMessage": "111",
            "originalExtraData": null,
            "originalTimestampMillis": 1752487464039
            }
        },
        "timestamp": "2025-03-05T04:51:01.689Z",
        "timestampMillis": 1741150261689
      },
      // 이하 동일한 형식의 객체
    ]
  }
}

通知消息发送 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`)	字符串	是
Content-Type	请求数据类型 (`application/json`)	字符串	是

请求体¶

字段名称	描述	类型	必填
channelId	消息将发送到的频道 ID	字符串	否
langCode	Hive 语言代码，消息将发送到的语言（如果未提供，则发送到所有语言）	字符串	否
message	要发送的通知消息内容 (最多 `200` 个字符)	字符串	是

请求体 > channelId¶

如果提供了 channelId，消息将作为 频道通知消息 发送给所有连接到指定频道的用户。
如果未提供 channelId，消息将作为 用户通知消息 发送给所有连接到套接字服务器的用户。

请求体 > langCode¶

如果提供了 langCode，消息将仅发送给具有匹配语言代码的用户。例如，如果 langCode 为 en，则消息仅发送给 langCode 设置为 en 的用户。
如果未提供 langCode，则消息将发送给所有用户，无论其语言如何。

响应主体¶

字段名称	描述	类型
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."
}

用户通知消息发送 API¶

向具有指定玩家 ID 的用户发送用户通知消息。

请求 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 语言代码，消息将发送到该语言（如果未提供，则发送到所有语言）	字符串	否
message	要发送的通知消息的内容 (最多 `200` 个字符)	字符串	是

请求体 > langCode¶

如果提供了 langCode，消息将仅发送给在游戏客户端连接时语言代码与提供的 langCode 匹配的用户。例如，如果 playerId=1111 的用户连接时使用 langCode=en，而此 API 被调用时使用 playerId=1111, langCode=ja，则消息将不会发送给该用户。
如果未提供 langCode，则消息将发送给具有指定 playerId 的用户，无论其语言如何。

响应体¶

字段名称	描述	类型
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."
}

频道自定义消息发送 API¶

向所有参与特定频道的用户发送自定义消息。

请求 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 游戏索引	整数	是
channelId	接收消息的频道 ID	字符串	是

头部参数¶

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

用户自定义消息发送API¶

向最多10个指定用户发送自定义消息。

请求 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	接收消息的玩家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."
}

AI 消息翻译 API¶

将消息中的文本翻译为指定语言。

请求 URL¶

服务器	URL
生产环境	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/translate`
沙盒环境	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/translate`
HTTP 方法	`POST`
内容类型	`application/json`

路径参数¶

字段名称	描述	类型	必需
gameIndex	Hive 游戏索引	整数	Y

头部参数¶

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

请求体¶

字段名称	描述	类型	必需
text	原始消息	字符串	Y
from	Hive 语言代码的原始消息使用 `auto` 自动检测语言	字符串	Y
to	Hive 语言代码将要翻译的消息可以指定多个代码（例如 `ko, en, ja`）	字符串	Y

响应体¶

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

响应主体 > 数据¶

字段名称	描述	类型
translations	翻译结果对象	对象

响应主体 > 数据 > 翻译¶

字段名称	描述	类型
{lang}	翻译的消息	字符串

※ 请求翻译 API 时，指定的 Hive 语言代码(例如 en, ja, ar) 被用作 {lang} 字段名称。

请求示例¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/translate' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "text": "안녕하세요. 반갑습니다.",
    "from": "ko",
    "to": "en, ja, ar"
}'

响应示例¶

{
    "code": 0,
    "message": "Success.",
    "data": {     
        "translations": {
            "ar": "مرحبا. تشرفنا.",
            "ja": "こんにちは。はじめまして。",
            "en": "Hello. Nice to meet you."
        }
    }
}