メッセージ¶

メッセージ履歴の照会、メッセージタイプ別の送信、メッセージ翻訳のための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
LIVE	`https://api-chat.withhive.com/api/v2/games/{gameIndex}/channels/{channelId}/messages`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v2/games/{gameIndex}/channels/{channelId}/messages`
HTTP メソッド	`GET`

パスパラメータ¶

フィールド名	説明	タイプ	必須
gameIndex	Hive ゲームインデックス	整数	Y
channelId	取得するチャンネルID	整数	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	API呼び出しの認証トークン (`Bearer`)	文字列	Y

クエリパラメータ¶

フィールド名	説明	タイプ	必須
prevSize	前のチャンネルメッセージ取得のサイズ（最小 `0` ~ 最大 `50`） (デフォルト: `0`)	整数	N
nextSize	次のチャンネルメッセージ取得のサイズ `messageId`はこの値が提供されない場合無視されます。（最小 `0` ~ 最大 `50`） (デフォルト: `0`)	整数	N
messageId	取得に使用するmessageId（`null`は最も最近のチャンネルメッセージを取得します）	文字列	N
order	日付ベースのソート方法（`ASC`, `DESC`） (デフォルト: `DESC`)	文字列	N

prevSize と nextSize¶

prevSize と nextSize は、一度のリクエストで取得するメッセージの範囲を定義します。

prevSizeは前のメッセージ履歴を取得し、nextSizeは指定されたmessageIdに基づいて次のメッセージ履歴を取得します。例えば、prevSize=10とnextSize=5がmessageIdと共に指定された場合、messageIdの前に10件、後に5件のメッセージが取得されます。

messageIdを指定せずにチャンネルメッセージ履歴取得APIが呼び出された場合、prevSizeで設定された数までの最新のメッセージのみが取得され、nextSizeの値は適用されません。

応答本文¶

フィールド名	説明	タイプ
コード	レスポンス結果コード	整数
メッセージ	結果の説明	文字列
データ	レスポンスデータ	オブジェクト

レスポンスボディ > データ¶

フィールド名	説明	タイプ
hasNext	さらにメッセージを取得できるかどうか	boolean
nextMessageId	次のメッセージを取得するために使用するmessageId	string
hasPrev	前のメッセージを取得できるかどうか	boolean
prevMessageId	前のメッセージを取得するために使用するmessageId	string
content	チャンネルメッセージ履歴	object array

hasNext : hasNextがtrueの場合、さらに続くメッセージ履歴があります。この場合、nextMessageIdで示されたmessageIdに従って、さらにチャンネルメッセージ履歴を取得できます。
hasPrev : hasPrevがtrueの場合、さらに前のメッセージ履歴があります。この場合、prevMessageIdで示されたmessageIdに先行するチャンネルメッセージ履歴を取得できます。

レスポンスボディ > データ > コンテンツ¶

フィールド名	説明	タイプ
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	メッセージが送信された日時（UnixTimestampミリ秒）	長整数

レスポンスボディ > データ > コンテンツ > プラグインデータ¶

以下のデータは、メッセージの追加機能が使用された場合にのみ追加されます。

フィールド名	説明	タイプ
like	'いいね'情報	オブジェクト
mentions	メンション情報	オブジェクト配列
reply	返信情報	オブジェクト

レスポンスボディ > データ > コンテンツ > プラグインデータ > いいね¶

フィールド名	説明	型
playerIds	「いいね」を追加したユーザーのプレイヤーID（複数）	long array

レスポンスボディ > データ > コンテンツ > プラグインデータ > メンション¶

フィールド名	説明	タイプ
playerId	言及されたユーザーのプレイヤーID	long

レスポンスボディ > データ > コンテンツ > プラグインデータ > 返信¶

フィールド名	説明	タイプ
originalMessageId	元のメッセージのID	string
originalMessage	元のメッセージの内容	string
originalExtraData	元のメッセージの追加情報	string
originalTimestampMillis	元のメッセージ送信日時（UnixTimestampミリ秒）	long

リクエストサンプル¶

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
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/notice`
SANDBOX	`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 言語コード（指定がない場合はすべての言語に送信されます）	文字列	N
message	送信される通知メッセージの内容 (最大 `200` 文字)	文字列	Y

リクエストボディ > チャンネルID¶

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
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/notice/users/{playerId}`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/notice/users/{playerId}`
HTTP メソッド	`POST`
CONTENT-TYPE	`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 が提供されている場合、メッセージはゲームクライアント接続時に提供された langCode と一致するユーザーにのみ送信されます。たとえば、playerId=1111 のユーザーが langCode=en で接続している場合、このAPIが playerId=1111, langCode=ja で呼び出されると、メッセージはそのユーザーに送信されません。
langCode が提供されていない場合、メッセージは言語に関係なく指定された playerId のユーザーに送信されます。

応答本文¶

フィールド名	説明	タイプ
コード	レスポンス結果コード	整数
メッセージ	結果の説明	文字列

リクエストサンプル¶

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
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId}`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId}`
HTTP メソッド	`POST`
CONTENT-TYPE	`application/json`

パスパラメータ¶

フィールド名	説明	タイプ	必須
gameIndex	Hive ゲームインデックス	整数	Y
channelId	メッセージを受信するためのチャネルID	文字列	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	API呼び出しの認証トークン（`Bearer`）	文字列	Y
Content-Type	リクエストデータタイプ（`application/json`）	文字列	Y

リクエストボディ¶

フィールド名	説明	タイプ	必須
message	送信されるカスタムメッセージの内容（`UTF-8`ベース） (最大 `8,000 バイト`)	文字列	Y

レスポンスボディ¶

フィールド名	説明	タイプ
コード	レスポンス結果コード	整数
メッセージ	結果の説明	文字列

リクエストサンプル¶

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
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/users`
SANDBOX	`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": "커스텀 메시지입니다."
}'

レスポンスサンプル¶

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

AIメッセージ翻訳API¶

メッセージ内のテキストを指定された言語に翻訳します。

リクエストURL¶

サーバー	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/translate`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/translate`
HTTP メソッド	`POST`
CONTENT-TYPE	`application/json`

パスパラメータ¶

フィールド名	説明	タイプ	必須
gameIndex	Hive ゲームインデックス	整数	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	API呼び出しの認証トークン（`Bearer`）	文字列	Y
Content-Type	リクエストデータタイプ（`application/json`）	文字列	Y

リクエストボディ¶

フィールド名	説明	タイプ	必須
text	元のメッセージ	文字列	Y
from	Hive 言語コードの元のメッセージ言語を自動検出するには `auto` を使用します	文字列	Y
to	Hive 言語コードにメッセージが翻訳される複数のコードを指定できます (例: `ko, en, ja`)	文字列	Y

レスポンスボディ¶

フィールド名	説明	型
コード	レスポンス結果コード	整数
メッセージ	結果の説明	文字列
データ	レスポンスデータ	オブジェクト

レスポンスボディ > データ¶

フィールド名	説明	タイプ
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."
        }
    }
}