메시지¶

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

개요¶

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

채널 메시지¶

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

Direct 메시지¶

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

공지 메시지¶

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

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

커스텀 메시지¶

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

메시지 번역¶

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

자동 번역¶

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

수동 번역¶

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

언어 코드¶

메시지 추가 기능¶

전송한 메시지에 추가할 수 있는 기능으로 좋아요, 멘션, 답글이 있습니다.

• 좋아요: 채널의 각 메시지에 '좋아요'를 추가하거나 취소할 수 있습니다.
• 멘션: 채널 메시지에서 특정 유저를 언급(멘션)하여 알림을 보낼 수 있습니다.
• 달기: 채널 내 전송된 특정 메시지에 답글을 입력할 수 있습니다.

채널 메시지 내역 조회 API¶

messageId를 기준으로 해당 채널 메시지 이전 및 이후 내역을 조회합니다. 단, 채널 설정에서 chatHistoryAllowed가 true 인 경우에만 요청할 수 있습니다.

채널 메시지 내역은 커서 기반 페이지네이션으로 제공하며, 최근 30일 이내의 채널 메시지 내역만 조회 가능합니다.

Request URL¶

Path parameters¶

Header parameters¶

Query parameters¶

prevSize와 nextSize¶

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

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

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

Response body¶

Response body > data¶

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

Response body > data > content¶

Response body > data > content > pluginData¶

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

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

공지 메시지 전송 API¶

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

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Request body > channelId¶

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

Request body > langCode¶

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

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

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

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

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Request body > langCode¶

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

• langCode가 없으면 언어와 상관없이 playerId 에 해당하는 유저에게 메시지를 사용자 공지 메시지를 전송합니다.

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

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

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

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

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

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

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 메시지 번역 API¶

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

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

Response body > data¶

Response body > data > translation¶

※ 번역 API 요청시, 지정된 Hive 언어 코드(예: 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."
        }
    }
}