Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y앱

시크릿App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디App Id

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자User ID issued by the platform (Item sender)

senderAppId

String

N

발신자 Sender App ID (빈 값인 경우 appId로 설정set to appId if left blank)

appId

String

Y

수신자 Receiver App ID

senderId

String

Y

발신자 Sender ID

receiverId

String

Y

수신자 Receiver ID

message

Message

Y

메시지Message

items

List<Item>

N아이템

목록Item list

checkPlayer

Boolean

N유저 체크 여부

Whether to check the user

receiverIdType

String

N

유저 타입 User type (기본값default: playerId)

messageId

String

N

고유한 메시지 Unique message UUID.

• 동일한 messageId로 요청 시 중복해서 처리 하지 않습니다.

• messageId 생성을 권장합니다.

  예제

  If the same messageId is used in a request, it won't be processed twice.

• It is recommended to generate a messageId.

  messageId 최대길이는 64로 제한됩니다

  • Example: {kgAppId}_{playerId}_{timestamp}

  • 빈 값으로 호출된 경우 플랫폼에서 UUID를 자체적으로 생성합니다.

• 메시지 등록 요청시에 생성하고 정상적인 응답을 받지 못했을때 기존에 생성한 messageId로 재요청하면 됩니다.

• • If called with an empty value, the platform will automatically generate a UUID.

• If a message registration request is made and a valid response is not received, the previously generated messageId can be used to resend the request.

• The maximum length of messageId is limited to 64 characters.

messageBoxId

String

N

우편함 고유 아이디

• 빈 값으로 호출된 경우 기본 우편함(inbox)으로 우편이 전송됩니다.

Unique mailbox ID.

• If left blank, the mail will be sent to the default mailbox (inbox).

title

String

N

제목Title

body

String

N

본문Body

titleMap

Map<String, String>

N제목 - 다국어 처리 필요 시 사용

Title (used for multilingual processing)

bodyMap

Map<String, String>

N본문 - 다국어 처리 필요 시 사용

Body (used for multilingual processing)

resourceMap

Map<String, String>

N

메시지를 표현할때 필요한 데이터 값

제한 사항

Data values required to display the message

Limitations

• 1-dimensional Key-Value

• 10개의 Key

• 각 각의 Value Size 100ByteMaximum of 10 keys

• Each value size is limited to 100 bytes

expiryTime

Long

N

만료시각. 지정될 경우, 실제적으로 수령인이 처리할 시간이 필요하기 때문에 등록시점보다 최소 10초 이후의 시각이어야 합니다.

expiry time 설정시 message box 설정값을 넘을 수 없습니다Expiration time. If specified, it must be at least 10 seconds after the registration time.

Cannot exceed the message box's expiration time.

itemCode

String

Y아이템

코드Item code

quantity

Long

Y아이템

수량Item quantity

validityTime

Long

N유효기간 
미입력시

Validity period.

If not specified, set to -1 입력됨 (무제한unlimited) .

200정상

응답Normal response

정상Normal

400

Bad Request파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

Unparsable request data, missing required parameters, or parameter type error

401

Unauthenticated인증

실패Authentication failed

406

Not Acceptable

처리 불가Cannot process

461

Invalid Message Box

messageBoxId로 요청된 메시지 박스가 존재하지 않음The requested message box with messageBoxId does not exist.

500

Internal Server Error서버

시스템 내부 오류Internal server system error

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 Service is unavailable (e.g., internal server timeout)

messageId

String

전달되는 메시지의 messageIdThe messageId of the delivered message

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG

App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageBoxId

String

N우편함

아이디
- 특정 메시지 박스에 대해서만 조회 시에 사용 (미 입력 시 기본 우편함으로 설정됨Mailbox Id
- Used to query only a specific message box (Default mailbox if not entered)

count

Integer

Y

조회할 메시지 개수 (최대 100씩Number of messages to retrieve (maximum 100)

nextPageKey

Long

N

조회할 페이지의 시작 offset

null 입력시 첫페이지를 요청함

Long Max (9223372036854775807) 값을 입력해도 동일한 첫페이지를 요청함Offset to query the starting offset of the page.

If null, the first page is requested.

Even if you enter the Long Max value (9223372036854775807), the first page is requested.

states

List<String>

N조회할 메시지 상태 값 목록

List of message state values to query:

unread, read, error, deleted, expired미 입력시 unread, read 상태의 메시지목록이 반환됨.

If not entered, a list of messages in unread and read states is returned.

200정상

응답Normal Response

정상Normal

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류Unparsable request data. Lack of required parameters or parameter type error

401

Unauthenticated인증되지

않은 요청Unauthenticated request

406

Not Acceptable존재하지 않는 사용자

Non-existent user

461

Restricted제재된

사용자Restricted User

463

Removed탈퇴한 사용자 ( 사용자가 탈퇴 신청을하여 탈퇴 처리 중인 경우임. 실제 사용자 데이터는

존재함 Unregistered User (The user has applied to unregister, and the process is ongoing. The actual user data still exists.)

500

Internal Server Error서버

시스템 내부 오류Internal server system error

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 Service is unavailable (e.g., internal server timeout)

nextPageKey

Long

다음 페이지 요청시 사용될

nextPageKey

Next page key

to be used for the next page request.

• If -1, there is no more data.

messages

List<MessagePacket>메시지

목록Message list

maxCount

Integer최대 보유 가능 메시지 개수

• Maximum number of messages that can be stored

totalCount

Integer

현재 메시지 개수 (전체 페이지Current number of messages (total pages)

message

Message메시지

데이터Message data

items

List<Item>첨부 아이템 목록 

List of attached items 

existUnconfirmedItems

Boolean미확인 아이템 존재 여부

Whether there are unconfirmed items

deliverySeq

Long메시지 고유번호

Unique message number

messageId

String

메시지 Message ID

messageBoxId

String

우편함 Mailbox ID

senderAppId

String

발신자 Sender App ID

senderId

String

발신자 Sender ID

receiverAppId

String

수신자 Receiver App ID

receiverId

String

수신자 Receiver ID

title

String

제목Title

body

String

본문Body

resourceMap

Map메시지를 표현할때 필요한 데이터 값

Data values required to represent the message

state

String메시지 상태 값

Message state value

unread, read, error, deleted, expired

regTime

Long등록

시각Registration time

modTime

Long최종 수정 시각

Last modification time

readTime

Long

확인 처리 시각 (읽음 처리Confirmation processing time (read processing)

expiredTime

Long만료시각

Expiration time

itemId

String

아이템 고유 Unique item ID

itemCode

String아이템

코드Item code

itemName

String아이템

명Item name

quantity

Long아이템

수량Item quantity

state

String처리 상태값

Processing state value

registered, sent, confirmed, error, deleted, expired

sentCount

Integer

아이템 클레임 처리 횟수

Number of times the item claim has been processed.

• It is considered abnormal operation if claimed more than twice.

validityTime

Long아이템 유효시간

Item validity time

regTime

Long등록

시각Registration time

modTime

Long최종 수정 시각

Last modification time

sentTime

Long

requestItem 요청 시각Time when the requestItem was sent

confirmedTime

Long확인 처리 시각

Confirmation processing time

expiredTime

Long만료시각

Expiration time

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG

App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y아이템을 수령할 메시지 ID 목록

List of message IDs for which to claim items

200정상

응답Normal Response

정상Normal

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류Unparsable request data. Lack of required parameters or parameter type error.

401

Unauthenticated인증되지

않은 요청Unauthenticated request

406

Not Acceptable존재하지 않는 메시지

Non-existent message

500

Internal Server Error서버

시스템 내부 오류Internal server system error

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 Service is unavailable (e.g., internal server timeout)

results

List<Result>아이템 정보 목록

• List of item information

messageId

String

messageId

status

Integer

아이템 클레임 처리 상태 코드

Item claim processing status code

• Normal processing: 200

• 에러 발생 Error occurred: 406

  • 아이템이 ‘등록된’ 상태가 아닌 경우

  • 이미 ‘클레임’ 처리된 경우

  • 20초 이내로 중복 클레임 처리 요청이 들어온 경우

  • 클레임 횟수가 2번 이상인 경우When the item is not in a 'registered' state

  • When the item has already been 'claimed'

  • When a duplicate claim request is made within 20 seconds

  • When the number of claims exceeds 2 times

receiverId

String

수신자 Receiver ID

senderId

String

발신자 Sender ID

resourceMap

Map<String, String>메시지 표현 시 필요한 값

Values required to represent the message

items

List<Item>아이템 정보 목록

List of item information

appId

String

App ID

itemCode

String아이템

코드Item code

quantity

Long아이템

수량Item quantity

itemId

String

아이템 고유 Unique item ID

validityTime

Long

유효기한

Validity period.

• If this field is empty at the time of message sending, it will be recorded as -1 (e.g., in the case of items sent through promotions).

senderId

String

발신자 Sender ID

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG

App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y완료 처리할 메시지 ID 목록

List of message IDs to be marked as completed

200정상

응답Normal Response

정상Normal

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류Unparsable request data. Lack of required parameters or parameter type error.

401

Unauthenticated인증되지

않은 요청Unauthenticated request

406

Not Acceptable존재하지 않는 메시지

Non-existent message

500

Internal Server Error서버

시스템 내부 오류Internal server system error

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 Service is unavailable (e.g., internal server timeout)

results

List<Result>아이템 정보 목록

List of item information

messageId

String

messageId

status

Integer

처리 결과 Processing result (200 성공 success)

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG

App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y읽음 처리할 메시지 ID 목록

List of message IDs to be marked as read

200

Normal Response

Normal

400

Bad Request

Unparsable request data. Lack of required parameters or parameter type error.

401

Unauthenticated

Unauthenticated request

406

Not Acceptable

Non-existent message

500

Internal Server Error

Internal server system error

503

Service Unavailable

Service is unavailable (e.g., internal server timeout)

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG

App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y아이템 지급 완료 처리할 메시지 ID 목록

List of message IDs to be processed for item delivery completion

200

Normal Response

Normal

400

Bad Request

Unparsable request data. Lack of required parameters or parameter type error.

401

Unauthenticated

Unauthenticated request

406

Not Acceptable

Non-existent message

500

Internal Server Error

Internal server system error

503

Service Unavailable

Service is unavailable (e.g., internal server timeout)

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG

App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y

삭제 처리할 메시지 ID 목록

Y

List of message IDs to be processed for deletion

200

Normal Response

Normal

400

Bad Request

Unparsable request data. Lack of required parameters or parameter type error.

401

Unauthenticated

Unauthenticated request

406

Not Acceptable

Non-existent message

500

Internal Server Error

Internal server system error

503

Service Unavailable

Service is unavailable (e.g., internal server timeout)