/
우편함 (/message)

우편함 (/message)

Owned by gameplatform1
Last updated: 8월 29, 2024 by Eric
8 min read

연동가이드 > 우편함

 

/message/send

Description

메시지 배송 서버로 다른 유저에게 메시지를 전달 요청합니다.

messageBoxId로 발송 대상 그룹을 지정하여 발송하게 됩니다. messageBox는 어드민 툴을 통해서 사전에 등록되어야합니다.

메시지 발송시에 아이템 목록을 첨부할 수 있습니다. 첨부할 아이템은 발송 전에 어드민 툴을 통해서 아이템 정보가 등록되어 있어야합니다.

Method

POST

Request Headers 

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

앱 시크릿

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자)

Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

senderAppId

String

N

발신자 App ID (빈 값인 경우 appId로 설정)

appId

String

Y

수신자 App ID

senderId

String

Y

발신자 ID

receiverId

String

Y

수신자 ID

message

Message

Y

메시지

items

List<Item>

N

아이템 목록

checkPlayer

Boolean

N

유저 체크 여부

receiverIdType

String

N

유저 타입 (기본값: playerId)

 

Message

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

messageId

String

N

고유한 메시지 UUID.

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

  • messageId 생성을 권장합니다.

    • 예제 : {kgAppId}_{playerId}_{timestamp}

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

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

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

messageBoxId

String

N

우편함 고유 아이디

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

title

String

N

제목

body

String

N

본문

titleMap

Map<String, String>

N

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

bodyMap

Map<String, String>

N

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

resourceMap

Map<String, String>

N

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

제한 사항

  • 1차원 Key - Value

  • 10개의 Key

  • 각 각의 Value Size 100Byte

expiryTime

Long

N

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

expiry time 설정시 message box 설정값을 넘을 수 없습니다.

Item

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

itemCode

String

Y

아이템 코드

quantity

Long

Y

아이템 수량

validityTime

Long

N

유효기간 
미입력시 -1 입력됨 (무제한) 

Response Status Code

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

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

401

Unauthenticated

인증 실패

406

Not Acceptable

처리 불가

461

Invalid Message Box

messageBoxId로 요청된 메시지 박스가 존재하지 않음.

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Response Content

Name

Type

Description

Name

Type

Description

messageId

String

전달되는 메시지의 messageId

 

Example Request

POST /service/v5/message/send HTTP/1.1 Host: kr-openapi-zinny3.game.kakao.com:10443 kgAppId: 103815 appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9 playerId: 1527701800 Content-Type: application/json;charset=UTF-8 Authorization: KakaoAK c0948035a320f789f585acae3dedcd70    {        "receiverId": "1527701800",     "message": {         "messageBoxId": "inbox",         "title": "타이틀",         "body": "본문"     },     "items": [         {             "itemCode": "TEST_ITEM_QA2",             "quantity": 10,             "validityTime": 25900000         }     ] }

Example Response 

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8   {     "messageId": "c21c6dfe-c13b-46ff-9946-961d28beb914" }

 

/message/getList

Description

메시지 배송 서버로 전달된 메시지 목록을 조회합니다.

조회된 목록은 시간 역순으로 가장 최신 메시지가 첫페이지로 조회 됩니다. 최대 100개 씩 페이징 처리되어 조회할 수 있습니다.

응답값에 nextPageKey 값이 -1이 아니면 해당 키를 이용해서 다음 페이지 조회가 가능합니다.

메시지에는 복수개의 첨부아이템 목록이 존재합니다.

첨부된 아이템은 /message/claim 후에 게임에 아이템 적용후 /message/finish 를 호출하여 처리합니다.

Method

POST

Request Headers 

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

앱 시크릿

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자)

Request Body Parameters

Name

Type

 Mandatory

Description

Name

Type

 Mandatory

Description

messageBoxId

String

N

우편함 아이디
- 특정 메시지 박스에 대해서만 조회 시에 사용 (미 입력 시 기본 우편함으로 설정됨)

count

Integer

Y

조회할 메시지 개수 (최대 100씩)

nextPageKey

Long

N

조회할 페이지의 시작 offset

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

Long Max (9223372036854775807) 값을 입력해도 동일한 첫페이지를 요청함

states

List<String>

N

조회할 메시지 상태 값 목록

unread, read, error, deleted, expired

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

Response Status Code

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

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

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 사용자

461

Restricted

제재된 사용자

463

Removed

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

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

 

Response Content

Name

Type

Description

Name

Type

Description

nextPageKey

Long

다음 페이지 요청시 사용될

nextPageKey

  • -1 이면 더이상 데이터가 없음

messages

List<MessagePacket>

메시지 목록

maxCount

Integer

최대 보유 가능 메시지 개수

totalCount

Integer

현재 메시지 개수 (전체 페이지)

MessagePacket  

Name

Type

Description

Name

Type

Description

message

Message

메시지 데이터

items

List<Item>

첨부 아이템 목록 

existUnconfirmedItems

Boolean

미확인 아이템 존재 여부

Message

Name

Type

Description

Name

Type

Description

deliverySeq

Long

메시지 고유번호

messageId

String

메시지 ID

messageBoxId

String

우편함 ID

senderAppId

String

발신자 App ID

senderId

String

발신자 ID

receiverAppId

String

수신자 App ID

receiverId

String

수신자 ID

title

String

제목

body

String

본문

resourceMap

Map

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

state

String

메시지 상태 값

unread, read, error, deleted, expired

regTime

Long

등록 시각

modTime

Long

최종 수정 시각

readTime

Long

확인 처리 시각 (읽음 처리)

expiredTime

Long

만료시각

Item

Name

Type

Description

Name

Type

Description

itemId

String

아이템 고유 ID

itemCode

String

아이템 코드

itemName

String

아이템 명

quantity

Long

아이템 수량

state

String

처리 상태값

registered, sent, confirmed, error, deleted, expired

sentCount

Integer

아이템 클레임 처리 횟수

  • 2회 이상 클레임 처리 시 이상 동작으로 간주합니다

validityTime

Long

아이템 유효시간

regTime

Long

등록 시각

modTime

Long

최종 수정 시각

sentTime

Long

requestItem 요청 시각

confirmedTime

Long

확인 처리 시각

expiredTime

Long

만료시각

 Example Request 

POST /service/v5/message/getList HTTP/1.1 Host: kr-openapi-zinny3.game.kakao.com:10443 Content-Type: application/json;charset=UTF-8 kgAppId: 103815 appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9 playerId: 23423432453 Authorization: KakaoAK c0948035a320f789f585acae3dedcd70     { "count": 50 }

Example Response 

 

/message/claimItems

Description

메시지에 포함된 아이템들의 수령 요청을 플랫폼 서버에 알립니다. 

위 API 호출시 지급할 아이템 목록을 반환하고 ‘지급중(발송처리중)’ 상태로 변경 되며 처리가 완료된 이후 /message/finish 를 호출해야 지급완료 상태가 되어 트랜잭션이 종료 됩니다.

만약 /message/finish를 호출하지 않으면 처리가 완료되지 않은 것으로 간주되어 동일한 요청이 들어오면 이전과 같은 목록을 반환합니다.

위 API로 동일한 messageId에 대해서 2회 이상 호출 시 에러 처리 되며 지급 처리 목록에서 제외됩니다.

이미 finish까지 처리된 messageId에 대해서는 해당 result의 status 값이 406으로 에러 처리됩니다.  

finish 처리가 끝나기전에 동일한 messageId로 20초 이내에 다시 claimItems 를 호출시에도 406 에러처리가 됩니다. 

Request Headers 

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

앱 시크릿

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자)

Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

messageIds

List<String>

Y

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

Response Status Code

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

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

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)


Response Content 

Name

Type

Description

Name

Type

Description

results

List<Result>

아이템 정보 목록

Result Content 

Name

Type

Description

Name

Type

Description

messageId

String

messageId

status

Integer

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

  • 정상 처리 : 200

  • 에러 발생 : 406

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

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

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

    • 클레임 횟수가 2번 이상인 경우

receiverId

String

수신자 ID

senderId

String

발신자 ID

resourceMap

Map<String, String>

메시지 표현 시 필요한 값

items

List<Item>

아이템 정보 목록

 

Item 

Name

Type

Description

Name

Type

Description

appId

String

App ID

itemCode

String

아이템 코드

quantity

Long

아이템 수량

itemId

String

아이템 고유 ID

validityTime

Long

유효기한

  • 메시지 전송 시점에 해당필드가 비어있으면 -1로 기록 (예: 프로모션 통해서 아이템 전송받은 경우)

senderId

String

발신자 ID

 

Example Request

 

Example Response 

 

/message/finish

Description

 /message/claim 이후에 게임서버에서 게임 지급이 정상적으로 처리된 후에 호출합니다.

메시지에 포함된 아이템의 배송 트랜잭션을 종료 처리(아이템 지급완료)하고 메시지를 삭제합니다.

Method

POST

Request Headers  

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

앱 시크릿

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자)

Request Body Parameters 

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

messageIds

List<String>

Y

완료 처리할 메시지 ID 목록

 

Response Status Code 

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

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

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

 

Response Content 

Name

Type

Description

Name

Type

Description

results

List<Result>

아이템 정보 목록

 

Result Content 

Name

Type

Description

Name

Type

Description

messageId

String

messageId

status

Integer

처리 결과 ( 200 성공 )

 

Example Request 

 

Example Response 

 

/message/markAsRead

 

Description 

메시지를 읽음 처리합니다.

아이템 정보 및 상태는 유지되고 메시지만 ‘읽음' 상태로 변경됩니다.

Method

POST

Request Headers 

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

앱 시크릿

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자)

Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

messageIds

List<String>

Y

읽음 처리할 메시지 ID 목록

Response Status Code 

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

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

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

 

Example Request


Example Response 

 

/message/confirmItems

 

Description 

아이템 지급 완료 후 호출하여 메시지 상태를 변경합니다.

  • 메시지 상태 → “읽음”

  • 미확인 아이템 존재여부 → “없음”

Method

POST

Request Headers 

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

앱 시크릿

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자)

Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

messageIds

List<String>

Y

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

Response Status Code 

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

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

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

 

Example Request


Example Response 

 

/message/deleteMessages

 

Description 

메시지 상태를 ‘삭제완료’ 상태로 변경합니다.

Method

POST

Request Headers 

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

앱 시크릿

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG 앱 아이디

playerId

String

Y

플랫폼에서 발급한 사용자 ID (아이템 발신자)

Request Body Parameters

Name

Type

Mandatory

Description

Name

Type

Mandatory

Description

messageIds

List<String>

Y

삭제 처리할 메시지 ID 목록

Response Status Code 

Status Code

Status Code 설명

Status Code 상세 설명

Status Code

Status Code 설명

Status Code 상세 설명

200

정상 응답

정상

400

Bad Request

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

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

 

Example Request


Example Response 

Related content

Mailbox (/message)
Mailbox (/message)
Kakaogame SDK 4.0 Guide for Channeling
More like this
04 Server to Server API
04 Server to Server API
Kakaogame SDK 3.0 Guide for Channeling
Read with this
4. 멤버 키 조회 (/player)
4. 멤버 키 조회 (/player)
Kakaogame SDK 3.0 Guide for Channeling
More like this
Member (/member)
Member (/member)
Kakaogame SDK 4.0 Guide for Channeling
Read with this
인증 (/auth)
인증 (/auth)
Kakaogame SDK 4.0 Guide for Channeling
Read with this
회원 (/member)
회원 (/member)
Kakaogame SDK 4.0 Guide for Channeling
Read with this