Message¶

This guide explains how to use the APIs for viewing message history, sending messages by type, and translating messages.

Overview¶

This section describes the message types and sending methods supported by the API, as well as message translation and additional features.

Channel message¶

• Messages sent to channel participants, operating in a broadcasting manner.
• Message history is provided based on channelId.

Direct message¶

• Messages sent directly to another user, operating in a one-way manner.

Notice message¶

Notice messages are divided into channel notice messages and user notice messages.

• Channel notice message: Sent only to users connected to the specified channelId.
• User notice message: Sent only to the user with the specified playerId.

Custom message¶

• Custom messages are used to deliver large amounts of data, unlike regular chat messages, and are not for user-to-user conversation.

Message translation¶

This section explains automatic and manual translation features, as well as the language codes available for translation.

Automatic translation¶

• The game client can set whether to enable automatic translation per channel. The setting is reset when leaving the channel or disconnecting from the socket server.
• Messages are translated using the language code set when connecting to the socket server. To change the translation language, reconnect with a new language code.

Manual translation¶

• Call the AI message translation API to perform AI translation of the original message.

Language codes¶

Additional message features¶

Features that can be added to sent messages include likes, mentions, and replies.

• Like: You can add or remove 'likes' to each message in the channel.
• Mention: You can mention specific users in channel messages to send notifications.
• Reply: You can send replies to specific messages sent in the channel.

Channel message history retrieval API¶

Retrieves the message history before and after the specified messageId in the channel. This can only be requested if chatHistoryAllowed is true in the channel settings.

Channel message history is provided with cursor-based pagination, and only message history from the last 30 days can be retrieved.

Request URL¶

Path parameters¶

Header parameters¶

Query parameters¶

prevSize and nextSize¶

prevSize and nextSize define the range of messages to be retrieved in one request.

prevSize retrieves the previous message history, and nextSize retrieves the subsequent message history based on the specified messageId. For example, if prevSize=10 and nextSize=5 are specified with a messageId, 10 messages prior to the messageId and 5 messages following it will be retrieved.

If the channel message history retrieval API is called without specifying a messageId, only the most recent messages up to the count set by prevSize will be retrieved, and the value of nextSize will not be applied.

Response body¶

Response body > data¶

• hasNext : If hasNext is true, there are more subsequent message histories. In this case, you can retrieve more channel message histories following the messageId indicated by nextMessageId.
• hasPrev : If hasPrev is true, there are more previous message histories. In this case, you can retrieve more channel message histories preceding the messageId indicated by prevMessageId.

Response body > data > content¶

Response body > data > content > pluginData¶

• The following data is added only if message additional features were used.

Response body > data > content > pluginData > like¶

Response body > data > content > pluginData > mentions¶

Response body > data > content > pluginData > reply¶

Request sample¶

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'

Response sample¶

{
  "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
      },
      // 이하 동일한 형식의 객체
    ]
  }
}

Notice message sending API¶

Sends a notice message to users connected to a specific channel or the socket server.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Request body > channelId¶

• If channelId is provided, the message is sent to all users connected to the specified channel as a channel notice message.
• If channelId is not provided, the message is sent to all users connected to the socket server as a user notice message.

Request body > langCode¶

• If langCode is provided, the message is sent only to users with the matching language code. For example, if langCode is en, the message is sent only to users with langCode set to en.
• If langCode is not provided, the message is sent to all users regardless of language.

Response body¶

Request sample¶

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": "서버 점검이 있습니다. 잠시 후 다시 접속해 주세요."
}'

Response sample¶

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

User notice message sending API¶

Sends a user notice message to the user with the specified player ID.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Request body > langCode¶

• If langCode is provided, the message is sent only to the user whose language code matches the provided langCode at the time of game client connection. For example, if the user with playerId=1111 is connected with langCode=en, and this API is called with playerId=1111, langCode=ja, the message will not be sent to the user.
• If langCode is not provided, the message is sent to the user with the specified playerId regardless of language.

Response body¶

Request sample¶

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 님에게 보내는 공지 메시지입니다."
}'

Response sample¶

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

Channel custom message sending API¶

Sends a custom message to all users participating in a specific channel.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

Request sample¶

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": "커스텀 메시지입니다."
}'

Response sample¶

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

User custom message sending API¶

Sends a custom message to up to 10 specified users.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

Request sample¶

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": "커스텀 메시지입니다."
}'

Response sample¶

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

AI message translation API¶

Translates the text in the message to the specified language.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

Response body > data¶

Response body > data > translation¶

※ When requesting the translation API, the specified Hive language code(e.g. en, ja, ar) is used as the {lang} field name.

Request sample¶

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"
}'

Response sample¶

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