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	채널 소유자의 Player 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	Player 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	Player 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	채널 생성자의 Player 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	입장시킬 사용자의 Player 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	퇴장시킬 사용자 Player 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	Player 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	Player 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	Player 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	Player 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	Player ID	long
blockedUsers	차단 목록	object array

Response body > data > blockedUsers¶

필드명	설명	타입
blockedPlayerId	차단한 사용자의 Player 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	Player ID	long	Y
blockPlayerId	차단할 Player 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	Player ID	long	Y
blockedPlayerId	차단 해제할 Player 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가 있으면 채널에 접속한 모든 사용자에게 채널 공지 메시지를 발송합니다.

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	메시지를 받을 계정 식별자 모음 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."
}

채널 메시지 내역 조회¶

채널 메시지 내역을 조회합니다. 채널 메시지 내역은 커서 기반 페이지네이션으로 제공하며, 최근 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	메시지 전달받은 계정 식별자 Player 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
      },
    ]
  }
}