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로 재요청하면 됩니다.

• • timestamp}

  • 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

우편함 고유 아이디

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)

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)

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)

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)

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)

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)