訊息¶

本指南解釋如何使用 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 遊戲索引	整數	Y
channelId	用於檢索的頻道 ID	整數	Y

標頭參數¶

欄位名稱	描述	類型	必需
授權	API 呼叫的身份驗證令牌 (`Bearer`)	字串	Y

查詢參數¶

欄位名稱	描述	類型	是否必需
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 指示的 messageId 檢索更多頻道消息歷史。
hasPrev : 如果 hasPrev 為 true，則有更多之前的消息歷史。在這種情況下，您可以根據 prevMessageId 指示的 messageId 檢索更多頻道消息歷史。

回應主體 > 數據 > 內容¶

字段名稱	描述	類型
gameIndex	Hive 遊戲索引	整數
from	接收消息的帳戶識別碼玩家 ID	長整數
messageId	消息 ID	字串
extraData	附加用戶信息（`UTF-8` 基礎）（最大 `256 Byte`）	字串
pluginData	附加消息功能	物件
to	消息發送的頻道 ID	字串
message	消息內容	字串
langCode	Hive 語言代碼	字串
timestamp	消息發送的日期和時間（`UTC+0` 基礎，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字串
timestampMillis	消息發送的日期和時間（UnixTimestamp 毫秒）	長整數

回應主體 > 數據 > 內容 > 插件數據¶

只有在使用了消息附加功能的情況下，才會添加以下數據。

欄位名稱	描述	類型
like	'喜歡' 資訊	物件
mentions	提及資訊	物件陣列
reply	回覆資訊	物件

回應主體 > 數據 > 內容 > 插件數據 > 喜歡¶

欄位名稱	描述	類型
playerIds	添加了「喜歡」的用戶的玩家ID（多個）	長整數陣列

回應主體 > 數據 > 內容 > 插件數據 > 提及¶

欄位名稱	描述	類型
playerId	提到的用戶的玩家ID	long

回應主體 > 數據 > 內容 > 插件數據 > 回覆¶

null

請求範例¶

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
實時	`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	字串	N
langCode	Hive 語言代碼將要發送消息的語言（如果未提供，則發送到所有語言）	字串	N
message	要發送的通知消息內容 (最多 `200` 個字符)	字串	Y

請求主體 > channelId¶

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

請求主體 > 語言代碼¶

如果提供了 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
直播	`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 語言代碼將要發送消息的語言（如果未提供，則發送到所有語言）	字串	N
message	要發送的通知消息內容（最多 `200` 個字元）	字串	Y

請求主體 > 語言代碼¶

如果提供了 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 字節`)	字串	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."
}

用戶自定義消息發送 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

標頭參數¶

欄位名稱	描述	類型	必需
授權	API 呼叫的認證令牌 (`Bearer`)	字串	是
內容類型	請求資料類型 (`application/json`)	字串	是

請求主體¶

欄位名稱	描述	類型	必填
playerIds	接收消息的玩家ID列表 (最多 `10` 名玩家)	長整數陣列	Y
message	要發送的自定義消息內容 (`UTF-8` 基礎) (最大 `8,000 字節`)	字串	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": "커스텀 메시지입니다."
}'

回應範例¶

{
    "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	原始訊息	字串	是
from	Hive 語言代碼的原始訊息使用 `auto` 自動檢測語言	字串	是
to	Hive 語言代碼將要翻譯的訊息可以指定多個代碼（例如 `ko, en, ja`）	字串	是

回應主體¶

欄位名稱	描述	類型
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."
        }
    }
}