メッセージ¶

このガイドでは、メッセージ履歴の表示、タイプ別のメッセージ送信、およびメッセージの翻訳に関するAPIの使用方法を説明します。

概要¶

このセクションでは、APIがサポートするメッセージタイプと送信方法、メッセージ翻訳および追加機能について説明します。

チャンネルメッセージ¶

• ブロードキャスト方式で動作するチャンネル参加者に送信されたメッセージ。
• メッセージ履歴はchannelIdに基づいて提供されます。

ダイレクトメッセージ¶

• 他のユーザーに直接送信されるメッセージで、一方向で動作します。

通知メッセージ¶

通知メッセージは、チャネル通知メッセージとユーザー通知メッセージに分かれています。

• チャンネル通知メッセージ: 指定された channelId に接続されているユーザーのみに送信されます。
• ユーザー通知メッセージ: 指定された playerId を持つユーザーのみに送信されます。

カスタムメッセージ¶

• カスタムメッセージは、通常のチャットメッセージとは異なり、大量のデータを配信するために使用され、ユーザー間の会話には適していません。

メッセージ翻訳¶

このセクションでは、自動翻訳と手動翻訳の機能、および翻訳に利用可能な言語コードについて説明します。

自動翻訳¶

• ゲームクライアントは、チャンネルごとに自動翻訳を有効にするかどうかを設定できます。この設定は、チャンネルを離れたり、ソケットサーバーから切断したりするとリセットされます。
• メッセージは、ソケットサーバーに接続する際に設定された言語コードを使用して翻訳されます。翻訳言語を変更するには、新しい言語コードで再接続してください。

手動翻訳¶

• AIメッセージ翻訳APIを呼び出して、元のメッセージのAI翻訳を実行します。

言語コード¶

追加のメッセージ機能¶

送信されたメッセージに追加できる機能には、いいね、メンション、返信が含まれます。

• いいね: チャンネル内の各メッセージに「いいね」を追加または削除できます。
• メンション: チャンネルメッセージ内で特定のユーザーをメンションして通知を送信できます。
• 返信: チャンネル内で送信された特定のメッセージに返信を送信できます。

チャンネルメッセージ履歴取得API¶

指定されたmessageIdの前後のメッセージ履歴を取得します。これは、チャネル設定でchatHistoryAllowedが**true**の場合にのみ要求できます。

チャンネルメッセージ履歴はカーソルベースのページネーションで提供され、過去30日間のメッセージ履歴のみが取得できます。

リクエストURL¶

パスパラメータ¶

ヘッダーパラメータ¶

クエリパラメータ¶

prevSize と nextSize¶

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

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

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

応答本文¶

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

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

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

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

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

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

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

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

リクエストサンプル¶

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¶

パスパラメータ¶

ヘッダーパラメータ¶

リクエストボディ¶

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

• channelIdが提供されている場合、メッセージは指定されたチャネルに接続されているすべてのユーザーに**チャネル通知メッセージ**として送信されます。
• channelIdが提供されていない場合、メッセージはソケットサーバーに接続されているすべてのユーザーに**ユーザー通知メッセージ**として送信されます。

リクエストボディ > langCode¶

• langCode が提供されている場合、メッセージは一致する言語コードを持つユーザーにのみ送信されます。たとえば、langCode が en の場合、メッセージは langCode が en に設定されているユーザーにのみ送信されます。
• langCode が提供されていない場合、メッセージは言語に関係なくすべてのユーザーに送信されます。

応答本文¶

リクエストサンプル¶

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¶

パスパラメータ¶

ヘッダーパラメータ¶

リクエストボディ¶

リクエストボディ > 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¶

パスパラメータ¶

ヘッダーパラメータ¶

リクエストボディ¶

レスポンスボディ¶

リクエストサンプル¶

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¶

パスパラメータ¶

ヘッダーパラメータ¶

リクエストボディ¶

応答本文¶

リクエストサンプル¶

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¶

パスパラメータ¶

ヘッダーパラメータ¶

リクエストボディ¶

レスポンスボディ¶

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

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

※ 翻訳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."
        }
    }
}