콘텐츠로 이동

HTTP API

개요

HTTP 방식으로 채팅 서비스를 제공합니다. 크게 채널 API와 사용자 API, 메시지 API로 구성됩니다.

  • 채널 API
    • 전체 채널 목록 조회 API
    • 채널 조회 API
    • 채널 참여자 조회 API
    • 채널 생성 API
    • 채널 삭제 API
    • 채널 입장 API
    • 채널 퇴장 API
  • 사용자 API
    • 사용자 토큰 발급 API
    • 사용자 참여 채널 조회 API
    • 사용자 차단 목록 조회 API
    • 사용자 차단 API
    • 사용자 차단 해제 API
  • 메시지 API
    • 채널 공지 메시지 전송 API
    • 사용자 공지 메시지 전송 API
    • 채널 커스텀 메시지 전송 API
    • 사용자 커스텀 메시지 전송 API
    • 채널 메시지 조회 API

기본 정보

HTTP API 사용 시, 공통적으로 알아야 하는 기본 정보를 안내합니다.

사전 준비

HTTP API를 사용하려면 아래의 항목을 준비해야 합니다.

  • Hive Certification Key(Hive 인증키): API 호출을 위한 인증 토큰
    • Hive 콘솔 > 앱센터 > 프로젝트 관리 > 게임 상세 > 기본 정보 에서 확인 가능
  • Game Index(게임 인덱스): Hive 콘솔 > 앱센터 > 프로젝트 관리 에서 생성한 게임의 인덱스

채널 유형

HTTP API 전송 시, 사용되는 채널 유형은 아래와 같습니다.

Type 설명
PUBLIC 누구나 입장 가능한 채널
PRIVATE 비밀번호를 입력하여 입장 가능한 채널
GROUP 특정 사용자만 참여하는 채널 (ex. 길드 채널)

Request URL

서버 URL
LIVE api-chat.withhive.com
SANDBOX sandbox-api-chat.withhive.com

공통 헤더

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

응답 코드

  • API 응답 코드
HTTP 상태 코드 코드 메시지 설명
200 0 Success. 성공
400 100 Bad request. 잘못된 요청
401 101 Invalid token. 유효하지 않은 토큰
403 102 Forbidden. 권한 없음
404 103 Not found. 찾을 수 없음
405 104 Method not allowed. 허용되지 않은 메서드
500 105 Internal server error. 내부 서버 오류
  • 세부 에러 코드 (400, 403)
HTTP 상태 코드 코드 메시지 설명
400 200 Duplicate channel ID. 중복된 채널 ID
201 Channel not found or deleted. 채널을 찾을 수 없음 또는 삭제됨
202 Channel is full. 채널 참여 인원을 초과하여 채널 입장 불가
203 Invalid channel password. 유효하지 않은 채널 비밀번호
204 Message size exceeded. The maximum size is 200. 메시지 크기 초과 (최대 200자)
300 User not in session. 사용자가 세션에 없음 (Socket 서버에 접속하지 않은 상태)
301 User not in the channel. 사용자가 채널에 없음
302 User is already in the channel. 사용자가 이미 채널에 있음
303 User already blocked. 사용자가 이미 차단됨
304 Block list is full. The maximum size is 100. 차단 목록이 가득 참 (최대 100명)
305 User not in block list. 사용자가 차단 목록에 없음
306 User is blocked. 사용자가 차단됨
307 The maximum number of channels a user can enter is 10. 해당 사용자의 입장 가능한 채널 수 초과 (10개 제한)
400 Custom message size exceeded. The maximum size is 8,000 bytes. 커스텀 메시지 크기 초과 (최대 8,000바이트)
403 308 User is not the owner of the channel. 사용자가 채널 소유자가 아님

채널 API 기능

채팅 서비스에 이용되는 채널 API의 기능 별 API 요청 및 응답, 예제 코드를 설명합니다.

전체 채널 목록 조회

현재 생성된 채널 목록을 조회합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels
HTTP METHOD GET

Path parameters

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

Header parameters

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

Query parameters

필드명 설명 타입 필수 여부
type 채널 타입 (PRIVATE, PUBLIC, GROUP) string N
channelId 채널 ID로 시작하는 채널 조회 string N
channelName 채널 이름을 포함하는 채널 조회 string N
sort 정렬 기준 (channelId, channelName, regTime)
(기본값 regTime)		 string N
order 정렬 방식 (ASC, DESC)
(기본값 DESC)		 string N
size 한 페이지당 조회할 채널 수
(최소 1개 ~ 최대 10개, 기본값 10)		 integer N
page 조회할 페이지 번호
(1부터 시작, 기본값 1)		 integer N

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string
data 응답 데이터 object
Response body > data
필드명 설명 타입
content 채널 목록 object array
page 페이지 정보 object
Response body > data > content
필드명 설명 타입
channelId 채널 ID string
type 채널 타입 (PRIVATE, PUBLIC, GROUP) string
gameIndex Hive 게임 인덱스 integer
owner 채널 소유자의 Hive 플레이어 ID string
channelName 채널 이름 string
memberCount 현재 채널 참여 인원 integer
maxMemberCount 최대 채널 참여 인원 integer
chatHistoryAllowed 메시지 이력 조회 가능 여부 boolean
regTime 채널 생성 일시 (UTC+0 기준, yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식) string
regTimeMillis 채널 생성 일시 (UnixTimestamp Millisecond) long
Response body > data > page
필드명 설명 타입
size 한 페이지당 항목 수 integer
currentPage 현재 페이지 번호 integer
totalElements 전체 항목 수 integer
totalPages 전체 페이지 수 integer

Request sample

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels?type=PUBLIC&sort=regTime&order=DESC&size=10&page=1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sameple

{
  "code": 0,
  "message": "Success.",
  "data": {
    "content": [
      {
        "channelId": "open:12345",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 50,
        "chatHistoryAllowed": true,
        "regTime": "2024-12-30T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      /// ... 채널 정보
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

채널 조회

채널 상세 정보를 조회합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}
HTTP METHOD GET

Path parameters

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

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string
data 응답 데이터 object
Response body > data
필드명 설명 타입
info 채널 정보 object
members 참여자 목록 object array
Response body > data > info
필드명 설명 타입
channelId 채널 ID string
type 채널 타입 (PRIVATE, PUBLIC, GROUP) string
gameIndex Hive 게임 인덱스 integer
owner 채널 소유자 string
channelName 채널 이름 string
memberCount 현재 채널 참여 인원 integer
maxMemberCount 최대 채널 참여 인원 integer
chatHistoryAllowed 메시지 이력 조회 가능 여부 boolean
regTime 채널 생성 일시 (UTC+0 기준, yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식) string
regTimeMillis 채널 생성 일시 (UnixTimestamp Millisecond) long
Response body > data > members
필드명 설명 타입
playerId Hive 플레이어 ID long
connectedTime 접속 일시 (UTC+0 기준, yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식) string
connectedTimeMillis 접속 일시 (UnixTimestamp Millisecond) long

Request sample

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample

{
  "code": 0,
  "message": "Success.",
  "data": {
    "info": {
      "channelId": "open:12345",
      "type": "PUBLIC",
      "gameIndex": 1,
      "owner": "SYSTEM",
      "channelName": "오픈채팅방",
      "memberCount": 2,
      "maxMemberCount": 50,
      "chatHistoryAllowed": true,
      "regTime": "2024-12-30T15:01:01.004Z",
      "regTimeMillis": 1731306364351
    },
    "members": [
      {
        "playerId": 1,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

채널 참여자 조회

채널 참여자 정보를 조회합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/members
HTTP METHOD GET

Path parameters

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

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string
data 응답 데이터 object
Response body > data
필드명 설명 타입
members 채널 참여자 목록 object array
Response Body > data > members
필드명 설명 타입
playerId Hive 플레이어 ID long
connectedTime 접속 일시 (UTC+0 기준, yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식) string
connectedTimeMillis 접속 일시 (UnixTimestamp Millisecond) long

Request sample

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345/members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample

{
  "code": 0,
  "message": "Success.",
  "data": {
    "members": [
      {
        "playerId": 1,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

채널 생성

새로운 채널을 생성합니다.

Request body에 playerId를 입력할 경우, playerId에 해당하는 사용자가 생성하는 채널 소유자가 됩니다. 이 사용자는 생성한 채널에 입장합니다. 반대로, Request body에 playerId를 입력하지 않은 경우, 생성하는 SYSTEM이 채널 소유자가 됩니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channel
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channel
HTTP METHOD POST
CONTENT-TYPE application/json

Path parameters

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

Header parameters

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

Request body

채널 생성 요청시, 필요한 전송 데이터입니다.

필드명 설명 타입 필수 여부
channelId 채널 ID
(영어 대소문자, 숫자, 일부 특수문자(-, ., _, ~, :) 사용 가능, 최대 100자)		 string Y
playerId 채널 생성자의 Hive 플레이어 ID long N
password 비밀번호 (PRIVATE 채널일 경우 필수)
(최대 50자)		 string N
channelName 채널 이름
(최대 50자)		 string Y
maxMemberCount 최대 채널 참여 인원
(최소 2명 ~ 최대 5,000명)		 integer Y
type 채널 타입 (PRIVATE, PUBLIC, GROUP) string Y
chatHistoryAllowed 메시지 이력 조회 가능 여부
(기본값 false)		 boolean N

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string

Request sample

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channel' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "channelId": "open:12345",
    "playerId": 1000,
    "channelName": "오픈 채팅방",
    "maxMemberCount": 100,
    "type": "PUBLIC",
    "chatHistoryAllowed": true
}'

Response sample

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

채널 삭제

채널을 삭제합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}
HTTP Method DELETE

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 integer Y
channelId 삭제할 채널 ID string Y

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string

Request sample

curl --request DELETE 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample

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

채널 입장

채널에 사용자를 입장시킵니다.

입장할 수 있는 최대 채널 개수는 사용자당 10개입니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter
HTTP METHOD POST
CONTENT-TYPE application/json

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 integer Y
channelId 채널 ID string Y

Header parameters

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

Request body

채널 입장 요청 시 필요한 데이터입니다.

필드명 설명 타입 필수 여부
playerId 입장시킬 사용자의 Hive 플레이어 ID long Y
password 비밀번호 (PRIVATE 채널일 경우 필수) string N

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string

Request sample

curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/channels/guild:12345/enter' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
    "playerId": 1001,
    "password": "guildPass123"
}'

Response sample

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

채널 퇴장

채널에 참여한 사용자를 퇴장시킵니다. 채널 소유자가 퇴장하더라도 해당 채널은 유지됩니다. 채널 소유자가 SYSTEM이 아니면서 참여자가 없는 채널은 주기적으로 삭제됩니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit
HTTP METHOD POST
CONTENT-TYPE application/json

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 integer Y
channelId 채널 ID string Y

Header parameters

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

Request body

채널 퇴장 요청 시 필요한 전송 데이터입니다.

필드명 설명 타입 필수 여부
playerId 퇴장시킬 사용자 Hive 플레이어 ID long Y

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string

Request sample

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channels/guild:12345/exit' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
    "playerId": 1001
}'

Response sample

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

사용자 API 기능

채팅 서비스에 이용되는 사용자 API의 기능 별 API 요청 및 응답, 예제 코드를 설명합니다.

사용자 토큰 발급

Socket 서버 접속을 위한 인증 토큰을 발급합니다.

발급받은 토큰을 통해 반환된 Socket 서버 주소로 접속합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/token
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/token
HTTP METHOD POST

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 integer Y
playerId Hive 플레이어 ID long Y

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string
data 응답 데이터 object
Response body > data
필드명 설명 타입
gameIndex Hive 게임 인덱스 integer
socketAddress Socket 서버 주소 string
token 발급된 토큰 string

Request sample

curl  --request POST 'https://api-chat.withhive.com/api/v1/games/1/users/1001/token' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "socketAddress": "wss://test-socket-chat.withhive.com/ws",
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg"
  }
}

사용자 참여 채널 조회

사용자가 참여 중인 채널 목록을 조회합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/channels
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/channels
HTTP METHOD GET

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 integer Y
playerId Hive 플레이어 ID long Y

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string
data 응답 데이터 object
Response body > data
필드명 설명 타입
gameIndex Hive 게임 인덱스 integer
playerId Hive 플레이어 ID long
channels 채널 목록 object array
Response body > data > channels
필드명 설명 타입
channelId 채널 ID string
type 채널 타입 (PRIVATE, PUBLIC, GROUP) string
gameIndex Hive 게임 인덱스 integer
owner 채널 소유자 string
channelName 채널 이름 string
memberCount 현재 채널 참여 인원 integer
maxMemberCount 최대 채널 참여 인원 integer
chatHistoryAllowed 메시지 이력 조회 가능 여부 boolean
regTime 채널 생성 일시 (UTC+0 기준, yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식) string
regTimeMillis 채널 생성 일시 (UnixTimestamp Millisecond) long

Request sample

curl --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/channels' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "playerId": 1001,
    "channels": [
      {
        "channelId": "guild:12345",
        "type": "GROUP",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "길드 채팅방",
        "memberCount": 1,
        "maxMemberCount": 50,
        "chatHistoryAllowed": true,
        "regTime": "2023-12-19T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      {
        "channelId": "open:67890",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 100,
        "chatHistoryAllowed": true,
        "regTime": "2023-12-20T10:15:30.123Z",
        "regTimeMillis": 1731302348750
      }
      // ... 채널
    ]
  }
}

사용자 차단 목록 조회

사용자가 차단한 사용자 목록을 조회합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks
HTTP METHOD GET

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 string Y
playerId Hive 플레이어 ID long Y

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string
data 응답 데이터 object
Response body > data
필드명 설명 타입
gameIndex Hive 게임 인덱스 integer
playerId Hive 플레이어 ID long
blockedUsers 차단 목록 object array
Response body > data > blockedUsers
필드명 설명 타입
blockedPlayerId 차단한 사용자의 Hive 플레이어 ID long
blockedTime 차단한 일시 (UTC+0 기준, yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식) string
blockedTimeMillis 차단한 일시 (UnixTimestamp Millisecond) long

Request sample

curl  --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/blocks' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "playerId": 1001,
    "blockedUsers": [
      {
        "blockedPlayerId": 1002,
        "blockedTime": "2023-12-20T10:15:30.123Z",
        "blockedTimeMillis": 1739329550811
      },
      {
        "blockedPlayerId": 1003,
        "blockedTime": "2023-12-21T08:45:12.456Z",
        "blockedTimeMillis": 1739329553137
      },
      // ... 차단 목록
    ]
  }
}

사용자 차단

다른 사용자를 차단합니다. 실시간 메시지 전송 및 수신을 제한하는 기능입니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId}
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId}
HTTP METHOD POST

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 string Y
playerId Hive 플레이어 ID long Y
blockPlayerId 차단할 Hive 플레이어 ID long Y

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string

Request sample

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample

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

사용자 차단 해제

차단한 사용자를 차단 해제합니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId}
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId}
HTTP METHOD DELETE

Path parameters

필드명 설명 타입 필수 여부
gameIndex Hive 게임 인덱스 string Y
playerId Hive 플레이어 ID long Y
blockedPlayerId 차단 해제할 Hive 플레이어 ID long Y

Header parameters

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

Response body

필드명 설명 타입
code 응답 결과 코드 integer
message 결과 메시지 string

Request sample

curl --request DELETE 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample

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

메시지 API 기능

공지 메시지 또는 커스텀 메시지를 전송하거나, 특정 채널의 메시지 기록을 조회하는 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 Hive 게임 인덱스 integer Y

Header parameters

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

Request body

공지 메시지 전송 요청 시, 필요한 전송 데이터입니다.

필드명 설명 타입 필수 여부
channelId 메시지를 보낼 채널 ID (없을 경우 전체 채널에 전송) string N
langCode 메시지를 보낼 사용자의 Hive 언어 코드 (없을 경우 언어 상관없이 전송)
(ISO 639 alpha-2를 기준으로 하며 ISO 639 alpha-2로 구분되지 않는 언어는 Script tag를 붙여 구분)		 string N
message 전송할 공지 메시지 내용
(최대 200자)		 string Y

channelId

channelId가 없으면 Path parameter gameIndex 해당 앱에 존재하는 모든 채널로 메시지를 발송합니다.

langCode

langCode가 없으면 언어와 상관없이 모든 사용자에게 메시지를 전달합니다.

langCode가 있다면 필드 값에 따라 전달하는 사용자가 달라집니다. 예를 들어, langCode가 en이면, 클라이언트 접속 시 Request body langCode가 en인 사용자들에게만 공지 메시지를 전송합니다.

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

사용자 공지 메시지 전송

사용자에게 공지 메시지를 전송합니다.

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 Hive 게임 인덱스 integer Y
playerId Hive 플레이어 아이디 long Y

Header parameters

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

Request body

공지 메시지 전송 요청 시, 필요한 전송 데이터입니다.

필드명 설명 타입 필수 여부
langCode 메시지를 보낼 사용자의 Hive 언어 코드 (없을 경우 언어 상관없이 전송)
(ISO 639 alpha-2를 기준으로 하며 ISO 639 alpha-2로 구분되지 않는 언어는 Script tag를 붙여 구분)		 string N
message 전송할 공지 메시지 내용
(최대 200자)		 string Y

langCode

langCode가 없으면 언어와 상관없이 playerId 사용자에게 메시지를 전달합니다.

langCode가 있다면 클라이언트 접속 시 Request body langCode와 이 API Request body langCode가 일치할 때에만 사용자 공지 메시지를 전송합니다. 예를 들어, playerId=1111인 사용자가 langCode=en로 채팅 클라이언트에 접속한 상태에서, 사용자 공지 메시지 전송 API를 playerId=1111, langCode=ja로 호출 시 이 사용자에게 공지 메시지를 전송하지 않습니다.

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

채널 커스텀 메시지 전송

채널에 참여한 모든 사용자에게 커스텀 메시지를 전송합니다.

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 Hive 게임 인덱스 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."
}

사용자 커스텀 메시지 전송

사용자에게 커스텀 메시지를 전송합니다.

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 Hive 게임 인덱스 integer Y

Header parameters

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

Request body

커스텀 메시지 전송 요청 시, 필요한 전송 데이터입니다.

필드명 설명 타입 필수 여부
playerIds 메시지를 받을 계정 식별자 모음
Hive 플레이어 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."
}

채널 메시지 내역 조회

채널 메시지 내역을 조회합니다. 채널 메시지 내역은 커서 기반 페이지네이션으로 제공하며, 최근 30일 이내의 채널 메시지 내역만 조회 가능합니다. 채널 설정에 이전 대화 기록 보기가 사용 중인 경우에만 이 API를 사용할 수 있습니다. API 응답으로 받은 채널 메시지 내역에는 차단된 사용자의 과거 메시지가 포함될 수 있습니다.

페이지네이션: size와 index

Query parameter index를 사용한 페이지네이션을 제공합니다. index 기본값은 없으며 index 없이 요청하면 가장 최근 메시지부터 size만큼 채팅을 전달합니다.

예를 들어, index 없이 size=5로 API를 호출하면, 가장 최신순으로 채팅 내역 5건과 다음 내역을 받을 수 있는 nextIndex(예를 들면 68009c30780e4f2d9830d8a0와 같은 값)를 반환합니다.

이후 index=68009c30780e4f2d9830d8a0, size=5로 API를 재호출하면, 앞에서 반환받은 가장 마지막 채팅 내역 이후에 발생한 채팅 5건을 반환합니다.

페이지네이션: hasNext

응답값 hasNext가 true이면 과거 채팅 내역이 더 존재합니다. 즉, 응답값 nextIndex를 index로 사용해 이전 채널 메시지 내역을 더 조회할 수 있습니다.

Request URL

서버 URL
LIVE https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/messages
SANDBOX https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/messages
HTTP METHOD GET

Path parameters

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

Header parameters

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

Query parameters

채널 메시지 조회 요청 시, 필요한 쿼리스트링 데이터입니다.

필드명 설명 타입 필수 여부
size 채널 내역 사이즈
(최소 1 ~ 최대 50)		 integer Y
index 조회에 사용할 index (없을 경우 가장 최신 메시지 조회) string N

Response body

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

Response body > data

필드명 설명 타입
hasNext 추가 조회 가능 여부 boolean
nextIndex 다음 조회 시 사용할 index string
content 채널 메시지 내역 object array

Response body > data > content

필드명 설명 타입
gameIndex Hive 게임 인덱스 integer
from 메시지 전달받은 계정 식별자
Hive 플레이어 ID		 long
extraData 사용자 부가 정보 (UTF-8 기준)
(최대 256 Byte)		 string
to 메시지 전송한 채널 ID string
message 메시지 내용 string
langCode Hive 언어 코드
(ISO 639 alpha-2를 기준으로 하며 ISO 639 alpha-2로 구분되지 않는 언어는 Script tag를 붙여 구분)		 string
timestamp 메시지 전송한 일시 (UTC+0 기준, yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식) string
timestampMillis 메시지 전송한 일시 (UnixTimestamp Millisecond) long

Request sample

curl --request GET 'https://test-api-chat.withhive.com/api/v1/games/1/channels/open:1/messages?size=50' \
--header 'Authorization: hivechat 005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76'

Response sample

{
  "code": 0,
  "message": "Success.",
  "data": {
    "hasNext": true,
    "nextIndex": "67c7d83336af25202c1c0ad4",
    "content": [
    // size=50이므로 아래와 같은 객체들을 50개 반환함.
      {
        "gameIndex": 1,
        "from": 1111112,
        "extraData": "김하이브",
        "to": "open:10",
        "message": "zzz",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:50:59.757Z",
        "timestampMillis": 1741150259757
      },
      {
        "gameIndex": 1,
        "from": 1111111,
        "extraData": null,
        "to": "open:10",
        "message": "하이브2",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:51:01.689Z",
        "timestampMillis": 1741150261689
      },
    ]
  }
}