기본 정보¶
채팅 API 사용에 앞서, 공통적으로 알아야 하는 기본 정보를 설명합니다.
사전 준비¶
채팅 API를 사용하려면 아래의 항목이 필요합니다.
- API 호출을 위한 Client ID와 Client Secret: 보안키 설정에서 발급
- API 호출을 위한 Access Token(JWT): 위에서 발급한 Client ID와 Client Secret으로 OAuth Token 발급하기 API를 호출하여 발급(유효 기간 1시간)
- Hive 게임 인덱스: Hive 콘솔 > 앱센터 > 프로젝트 관리에서 생성한 게임의 인덱스
Note
채팅 API는 JWT 인증 방식으로 동작합니다. 모든 API 요청 헤더인 X-Access-Token에 Access Token을 반드시 포함해야 합니다.
Warning
- Client Secret과 Access Token은 민감한 보안 정보이므로 절대 외부에 노출해서는 안 됩니다. 보안을 위해 소스 코드에 직접 포함하는 것을 삼가고, 클라이언트 환경의 기능 구현이 필요할 경우 Hive SDK를 이용해 주십시오.
- 모든 채팅 API는 서버 간(Server-to-Server) 통신 방식으로 동작합니다. 게임 클라이언트에서 직접 API를 호출하는 경우, 인증 토큰 유출 및 예상치 못한 문제가 발생할 수 있으므로 각별히 유의하여 사용해야 합니다.
공통 헤더¶
| 필드명 | 설명 | 타입 | 필수 여부 |
|---|---|---|---|
| X-Access-Token | 앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고) | string | Y |
| Content-Type | 요청 데이터의 타입 (application/json) | string | Y |
공통 응답¶
모든 API 응답에는 JWT 검증 결과인 token_validation 필드가 포함됩니다.
| 필드명 | 설명 | 타입 |
|---|---|---|
| code | 응답 결과 코드 | integer |
| message | 결과 메시지 | string |
| data | 응답 데이터(응답 데이터가 있는 API만 포함) | object |
| token_validation | JWT 검증 결과 | object |
| token_validation.result_code | JWT 검증 결과 코드 (0 = 성공, 실패 시 JWT 검증 오류 코드 참고) | integer |
| token_validation.result_msg | JWT 검증 결과 메시지 | string |
JWT 검증 실패 예시¶
{
"code": 101,
"message": "Invalid token.",
"token_validation": {
"result_code": 2408,
"result_msg": "The access token is expired. Please refresh your token."
}
}
응답 코드¶
- 공통 코드
| 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. | 내부 서버 오류 |
| 503 | 108 | Server is busy. please request later. | 서버 과부하 |
- 에러 코드
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 400 | 200 | Duplicate channel ID. | 중복된 채널 ID |
| 400 | 201 | Channel not found or deleted. | 채널을 찾을 수 없음 또는 삭제됨 |
| 400 | 202 | Channel is full. | 채널 참여 인원을 초과하여 채널 입장 불가 |
| 400 | 203 | Invalid channel password. | 유효하지 않은 채널 비밀번호 |
| 400 | 204 | Message size exceeded. The maximum size is 200. | 메시지 크기 초과(최대 200자) |
| 400 | 300 | User not in session. | 사용자가 세션에 없음(소켓 서버에 접속하지 않은 상태) |
| 400 | 301 | User not in the channel. | 사용자가 채널에 없음 |
| 400 | 302 | User is already in the channel. | 사용자가 이미 채널에 있음 |
| 400 | 303 | User already blocked. | 사용자가 이미 차단됨 |
| 400 | 304 | Block list is full. The maximum size is 100. | 차단 목록이 가득 참(최대 100명) |
| 400 | 305 | User not in block list. | 사용자가 차단 목록에 없음 |
| 400 | 306 | User is blocked. | 사용자가 차단됨 |
| 400 | 307 | The maximum number of channels the user can enter has been exceeded. | 해당 사용자의 입장 가능한 채널 수 초과 |
| 403 | 308 | User is not the owner of the channel. | 사용자가 채널 소유자가 아님 |
| 400 | 400 | Custom message size exceeded. The maximum size is 8,000 Byte. | 커스텀 메시지 크기 초과(최대 8,000바이트) |
JWT 검증 오류 코드¶
JWT 검증에 실패하면 HTTP 상태 코드와 code는 공통 코드를 따르며, 상세한 실패 사유는 token_validation.result_code로 확인할 수 있습니다. 코드별 해결 방법은 JWT 검증 오류 코드를 참고하세요.
| HTTP 상태 코드 | 코드 | token_validation.result_code | 설명 |
|---|---|---|---|
| 400 | 100 | 2400 | 클라이언트 정보 없음(JWT Header의 kid가 유효하지 않음) |
| 401 | 101 | 2405 | 토큰 형식 오류(JWT 형식이 올바르지 않음) |
| 401 | 101 | 2406 | 토큰 누락(요청 헤더에 X-Access-Token이 누락됨) |
| 401 | 101 | 2407 | 토큰 서명 오류(JWT 서명 검증 실패) |
| 401 | 101 | 2408 | 토큰 만료(Access Token 재발급 필요) |
| 401 | 101 | 2410 | Grant Type 불일치(서버 간 인증에 사용할 수 없는 grant_type의 토큰 사용) |
| 401 | 101 | 2411 | Project ID 불일치(JWT Payload의 project_id가 요청한 게임과 불일치) |