Message¶

This section describes how to use APIs for retrieving 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¶

Language	Local name	Hive language code
Korean	한국어	ko
English	English	en
Japanese	日本語	ja
Chinese (Simplified)	简体中文	zh-hans
Chinese (Traditional)	繁體中文	zh-hant
French	Français	fr
German	Deutsch	de
Russian	русский	ru
Spanish	Español	es
Portuguese	Português	pt
Indonesian	Bahasa Indonesia	id
Vietnamese	tiếng Việt	vi
Thai	ไทย	th
Italian	Italiano	it
Turkish	Türkçe	tr
Arabic	العربية	ar

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¶

Server	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 METHOD	`GET`

Path parameters¶

Field name	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID to retrieve	integer	Y

Header parameters¶

Field name	Description	Type	Required
Authorization	Authentication token for API call (`Bearer`)	string	Y

Query parameters¶

Field name	Description	Type	Required
prevSize	Size of the previous channel message retrieval (minimum `0` ~ maximum `50`) (Default: `0`)	integer	N
nextSize	Size of the next channel message retrieval `messageId` is ignored if this value is not provided. (Minimum `0` ~ Maximum `50`) (Default: `0`)	integer	N
messageId	messageId to use for retrieval (`null` retrieves the most recent channel message)	string	N
order	Date-based sorting method (`ASC`, `DESC`) (Default: `DESC`)	string	N

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¶

Field name	Description	Type
code	Response result code	integer
message	Description of the result	string
data	Response data	object

Response body > data¶

Field name	Description	Type
hasNext	Whether more messages can be retrieved	boolean
nextMessageId	messageId to use for retrieving the next message	string
hasPrev	Whether previous messages can be retrieved	boolean
prevMessageId	messageId to use for retrieving the previous message	string
content	Channel message history	object array

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¶

Field name	Description	Type
gameIndex	Hive game index	integer
from	Identifier of the account that received the message Player ID	long
messageId	Message ID	string
extraData	Additional user information (`UTF-8` based) (Maximum `256 Byte`)	string
pluginData	Additional message features	object
to	Channel ID to which the message was sent	string
message	Message content	string
langCode	Hive language code	string
timestamp	Date and time when the message was sent (`UTC+0` based, format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
timestampMillis	Date and time when the message was sent (UnixTimestamp Millisecond)	long

Response body > data > content > pluginData¶

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

Field name	Description	Type
like	'Like' information	object
mentions	Mention information	object array
reply	Reply information	object

Response body > data > content > pluginData > like¶

Field name	Description	Type
playerIds	Player IDs of users who added the 'like' (multiple)	long array

Response body > data > content > pluginData > mentions¶

Field name	Description	Type
playerId	Player ID of the mentioned user	long

Response body > data > content > pluginData > reply¶

Field name	Description	Type
originalMessageId	ID of the original message	string
originalMessage	Content of the original message	string
originalExtraData	Additional information of the original message	string
originalTimestampMillis	Original message sent date and time (UnixTimestamp Millisecond)	long

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¶

Server	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 METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field name	Description	Type	Required
gameIndex	Hive game index	integer	Y

Header parameters¶

Field name	Description	Type	Required
Authorization	Authentication token for API call (`Bearer`)	string	Y
Content-Type	Request data type (`application/json`)	string	Y

Request body¶

Field name	Description	Type	Required
channelId	Channel ID to which the message will be sent	string	N
langCode	Hive language code to which the message will be sent (if not provided, sent to all languages)	string	N
message	Content of the notice message to be sent (Maximum `200` characters)	string	Y

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¶

Field name	Description	Type
code	Response result code	integer
message	Description of the result	string

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¶

Server	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 METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field name	Description	Type	Required
gameIndex	Hive game index	integer	Y
playerId	Hive player ID	long	Y

Header parameters¶

Field name	Description	Type	Required
Authorization	Authentication token for API call (`Bearer`)	string	Y
Content-Type	Request data type (`application/json`)	string	Y

Request body¶

Field name	Description	Type	Required
langCode	Hive language code to which the message will be sent (if not provided, sent to all languages)	string	N
message	Content of the notice message to be sent (Maximum `200` characters)	string	Y

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¶

Field name	Description	Type
code	Response result code	integer
message	Description of the result	string

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¶

Server	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 METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field name	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID to receive the message	string	Y

Header parameters¶

Field name	Description	Type	Required
Authorization	Authentication token for API call (`Bearer`)	string	Y
Content-Type	Request data type (`application/json`)	string	Y

Request body¶

Field name	Description	Type	Required
message	Content of the custom message to be sent (`UTF-8` based) (Maximum `8,000 Byte`)	string	Y

Response body¶

Field name	Description	Type
code	Response result code	integer
message	Description of the result	string

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¶

Server	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 METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field name	Description	Type	Required
gameIndex	Hive game index	integer	Y

Header parameters¶

Field name	Description	Type	Required
Authorization	Authentication token for API call (`Bearer`)	string	Y
Content-Type	Request data type (`application/json`)	string	Y

Request body¶

Field name	Description	Type	Required
playerIds	List of Player IDs to receive the message (Up to `10` players)	long array	Y
message	Content of the custom message to be sent (`UTF-8` based) (Maximum `8,000 Byte`)	string	Y

Response body¶

Field name	Description	Type
code	Response result code	integer
message	Description of the result	string

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¶

Server	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 METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field name	Description	Type	Required
gameIndex	Hive game index	integer	Y

Header parameters¶

Field name	Description	Type	Required
Authorization	Authentication token for API call (`Bearer`)	string	Y
Content-Type	Request data type (`application/json`)	string	Y

Request body¶

Field name	Description	Type	Required
text	Original message	string	Y
from	Hive language code of the original message Use `auto` to auto-detect the language	string	Y
to	Hive language code to which the message will be translated Multiple codes can be specified (e.g. `ko, en, ja`)	string	Y

Response body¶

Field name	Description	Type
code	Response result code	integer
message	Description of the result	string
data	Response data	object

Response body > data¶

Field name	Description	Type
translations	Translation result object	object

Response body > data > translation¶

Field name	Description	Type
{lang}	Translated message	string

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