메시지¶

메시지 내역 조회, 메시지 유형별 전송, 메시지 번역을 위한 API 사용 방법을 안내합니다.

개요¶

API로 지원하는 메시지 유형 및 전송 방식, 메시지 번역 및 추가 기능에 대해 설명합니다.

채널 메시지¶

채널 참여자에게 전송하는 메시지로, 브로드캐스팅(broadcasting) 방식으로 동작합니다.
channelId 를 기준으로 메시지 내역을 제공합니다.

다이렉트 메시지¶

상대방에게 직접 전송하는 메시지로, 단방향으로 동작합니다.

공지 메시지¶

공지 메시지는 크게 채널 공지 메시지와 사용자 공지 메시지로 나뉩니다.

채널 공지 메시지: 해당 channelId에 접속한 유저에게만 전송되는 메시지입니다.
사용자 공지 메시지: 해당 playerId 유저에게만 전송되는 메시지입니다.

커스텀 메시지¶

커스텀 메시지는 일반적인 채팅 메시지와는 다르게, 사용자 간의 대화가 아닌 대용량의 데이터를 전달하기 위해 사용되는 메시지 유형입니다.

메시지 번역¶

메시지 번역 기능으로 자동 번역과 수동 번역, 번역 가능한 언어 코드를 설명합니다.

자동 번역¶

게임 클라이언트에서는 채널별로 자동 번역 여부를 설정할 수 있으며, 채널에서 퇴장하거나 소켓 서버와 연결이 해제되면 자동 번역 설정은 초기화됩니다.
소켓 서버 접속 시 설정한 언어 코드로 메시지가 번역됩니다. 번역 언어를 변경하려면 새로운 언어 코드로 다시 접속해야 합니다.

수동 번역¶

AI 메시지 번역 API를 호출하여 원본 메시지에 대한 AI 번역을 수행합니다.

언어 코드¶

언어	언어별 표기법	하이브 언어코드
한국어	한국어	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일 이내의 채널 메시지 내역만 조회 가능합니다.

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

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	하이브 게임 인덱스	integer	Y
channelId	조회할 채널 ID	integer	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (`Bearer`)	string	Y

Query parameters¶

필드명	설명	타입	필수 여부
prevSize	이전 채널 메시지 조회 사이즈 (최소 `0` ~ 최대 `50`) (기본값: `0`)	integer	N
nextSize	이후 채널 메시지 조회 사이즈 `messageId`가 없으면 이 값은 무시됩니다. (최소 0 ~ 최대 50) (기본값: `0`)	integer	N
messageId	조회에 사용할 messageId (`null`인 경우 가장 최신 채널 기준 메시지 조회)	string	N
order	날짜 기준 정렬 방식 (`ASC`, `DESC`) (기본값: `DESC`)	string	N

prevSize와 nextSize¶

prevSize와 nextSize는 한 번에 조회할 메시지 범위를 정의하는 파라미터입니다.

messageId에 해당되는 메시지를 기준으로 prevSize는 이전 메시지 내역을, nextSize는 이후 메시지 내역을 조회합니다. 예를 들어, messageId와 함께 prevSize=10, nextSize=5으로 지정하면 messageId에 해당하는 메시지의 이전 10개 메시지, 이후 5개 메시지를 조회할 수 있습니다.

또한 messageId를 지정하지 않고 채널 메시지 내역 조회 API를 호출하면, 채널의 가장 최신 메시지부터 prevSize로 설정된 메시지 개수만큼만 조회하며, 이때 nextSize 값은 적용되지 않습니다.

Response body¶

필드명	설명	타입
code	응답 결과 코드	integer
message	설명 결과 메시지	string
data	응답 데이터	object

Response body > data¶

필드명	설명	타입
hasNext	이후 메시지 조회 가능 여부	boolean
nextMessageId	이후 메시지 조회 시 사용할 messageId	string
hasPrev	이전 메시지 조회 가능 여부	boolean
prevMessageId	이전 메시지 조회 시 사용할 messageId	string
content	채널 메시지 내역	object array

hasNext : hasNext가 true이면 이후 메시지 내역이 더 존재합니다. 이때, nextMessageId에 해당하는 메시지 이후의 채널 메시지 내역을 더 조회할 수 있습니다.
hasPrev : hasPrev가 true이면 이전 메시지 내역이 더 존재합니다. 이때, prevMessageId에 해당하는 메시지 이전의 채널 메시지 내역을 더 조회할 수 있습니다.

Response body > data > content¶

필드명	설명	타입
gameIndex	하이브 게임 인덱스	integer
from	메시지 전달받은 계정 식별자 Player ID	long
messageId	메시지 ID	string
extraData	사용자 부가 정보 (`UTF-8` 기준) (최대 `256 Byte`)	string
pluginData	메시지 추가 기능	object
to	메시지 전송한 채널 ID	string
message	메시지 내용	string
langCode	하이브 언어 코드	string
timestamp	메시지 전송된 일시 (`UTC+0` 기준, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` 형식)	string
timestampMillis	메시지 전송된 일시 (UnixTimestamp Millisecond)	long

Response body > data > content > pluginData¶

메시지 추가 기능을 사용한 경우에만 아래의 데이터가 추가됩니다.

필드명	설명	타입
like	'좋아요' 정보	object
mentions	멘션 정보	object array
reply	답글 정보	object

Response body > data > content > pluginData > like¶

필드명	설명	타입
playerIds	'좋아요'를 추가한 유저의 player ID (복수)	long array

Response body > data > content > pluginData > mentions¶

필드명	설명	타입
playerId	멘션된 유저의 player ID	long

Response body > data > content > pluginData > reply¶

필드명	설명	타입
originalMessageId	원문 메시지의 ID	string
originalMessage	원문 메시지의 내용	string
originalExtraData	원문 메시지의 부가 정보	string
originalTimestampMillis	원문 메시지의 전송 일시 (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
      },
      // 이하 동일한 형식의 객체
    ]
  }
}

공지 메시지 전송 API¶

특정 채널에 참여한 유저 혹은 소켓 서버에 접속한 유저에게 공지 메시지를 전송합니다.

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

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	하이브 게임 인덱스	integer	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (`Bearer`)	string	Y
Content-Type	요청 데이터의 타입 (`application/json`)	string	Y

Request body¶

필드명	설명	타입	필수 여부
channelId	메시지를 보낼 채널 ID	string	N
langCode	메시지를 보낼 사용자의 하이브 언어 코드 (없을 경우 언어 상관없이 전송)	string	N
message	전송할 공지 메시지 내용 (최대 `200`자)	string	Y

Request body > channelId¶

channelId가 있으면 해당 채널에 접속한 모든 유저에게 채널 공지 메시지 를 발송합니다.
channelId가 없으면 소켓 서버에 접속한 모든 유저에게 사용자 공지 메시지 를 발송합니다.

Request body > langCode¶

langCode가 있으면 해당 필드값인 언어 코드에 해당되는 유저에게 메시지를 전송합니다. 예를 들어, langCode가 en이면, langCode가 en인 유저에게만 공지 메시지를 전송합니다.
langCode가 없으면 언어와 상관없이 모든 유저에게 메시지를 전송합니다.

Response body¶

필드명	설명	타입
code	응답 결과 코드	integer
message	설명 결과 메시지	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."
}

사용자 공지 메시지 전송 API¶

특정 player ID에 해당하는 유저에게 사용자 공지 메시지를 전송합니다.

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

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	하이브 게임 인덱스	integer	Y
playerId	하이브 플레이어 아이디	long	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (`Bearer`)	string	Y
Content-Type	요청 데이터의 타입 (`application/json`)	string	Y

Request body¶

필드명	설명	타입	필수 여부
langCode	메시지를 보낼 사용자의 하이브 언어 코드 (없을 경우 언어 상관없이 전송)	string	N
message	전송할 공지 메시지 내용 (최대 `200`자)	string	Y

Request body > langCode¶

langCode가 있으면, 해당 API 요청 시 포함하는 langCode와 게임 클라이언트 접속 시 설정된 langCode가 일치하는 유저에게만 사용자 공지 메시지를 전송합니다. 예를 들어, playerId=1111인 유저가 langCode=en로 게임 클라이언트에 접속한 상태에서, 본 API 호출 시 playerId=1111, langCode=ja로 포함하면 유저에게 공지 메시지를 전송하지 않습니다.
langCode가 없으면 언어와 상관없이 playerId 에 해당하는 유저에게 사용자 공지 메시지를 전송합니다.

Response body¶

필드명	설명	타입
code	응답 결과 코드	integer
message	설명 결과 메시지	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."
}

채널 커스텀 메시지 전송 API¶

특정 채널에 참여한 모든 유저에게 커스텀 메시지를 전송합니다.

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

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	하이브 게임 인덱스	integer	Y
channelId	메시지를 받을 채널 ID	string	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (`Bearer`)	string	Y
Content-Type	요청 데이터의 타입 (`application/json`)	string	Y

Request body¶

필드명	설명	타입	필수 여부
message	전송할 커스텀 메시지 내용 (`UTF-8` 기준) (최대 `8,000 Byte`)	string	Y

Response body¶

필드명	설명	타입
code	응답 결과 코드	integer
message	설명 결과 메시지	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."
}

사용자 커스텀 메시지 전송 API¶

최대 10명의 특정 유저에게 커스텀 메시지를 전송합니다.

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

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	하이브 게임 인덱스	integer	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (`Bearer`)	string	Y
Content-Type	요청 데이터의 타입 (`application/json`)	string	Y

Request body¶

필드명	설명	타입	필수 여부
playerIds	메시지를 받을 계정 식별자 모음 Player ID 리스트 (최대 `10`명)	long array	Y
message	전송할 커스텀 메시지 내용 (`UTF-8` 기준) (최대 `8,000 Byte`)	string	Y

Response body¶

필드명	설명	타입
code	응답 결과 코드	integer
message	설명 결과 메시지	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 메시지 번역 API¶

메시지로 입력된 텍스트를 지정된 언어로 번역합니다.

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

Path parameters¶

필드명	설명	타입	필수 여부
gameIndex	하이브 게임 인덱스	integer	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (`Bearer`)	string	Y
Content-Type	요청 데이터의 타입 (`application/json`)	string	Y

Request body¶

필드명	설명	타입	필수 여부
text	원본 메시지	string	Y
from	원본 메시지의 하이브 언어 코드 `auto` 입력 시, 자동 감지	string	Y
to	번역하려는 하이브 언어 코드 복수 지정 가능 (e.g. `ko, en, ja`)	string	Y

Response body¶

필드명	설명	타입
code	응답 결과 코드	integer
message	설명 결과 메시지	string
data	응답 데이터	object

Response body > data¶

필드명	설명	타입
translations	번역 결과 객체	object

Response body > data > translation¶

필드명	설명	타입
{lang}	번역된 메시지	string

※ 번역 API 요청 시, 지정된 하이브 언어 코드(예: en, ja, ar)가 {lang} 필드명으로 사용됩니다.

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