8.2. Server API 예제 (/message)
/message/getList
Description
메시지 배송 서버로 전달된 메시지 목록을 조회합니다.
조회된 목록은 시간 역순으로 가장 최신 메시지가 첫페이지로 조회 됩니다. 최대 100개 씩 페이징 처리되어 조회할 수 있습니다.
응답값에 nextPageKey 값이 -1이 아니면 해당 키를 이용해서 다음 페이지 조회가 가능합니다.
메시지에는 복수개의 첨부아이템 목록이 존재합니다.
첨부된 아이템은 /message/finish 후에 게임 우편함에 지급합니다.
게임 우편함에 지급한 후에 /message/finish 할 경우 처리가 되지 않을 경우 카카오 플렛폼에서 삭제되지 않으므로 중복 지급될 우려가 있습니다.
이에대한 예외처리가 되어 있다면 게임 내 우편함에 지급한 후에 /message/finish 호출해도 무방합니다.
Method
POST
Request Headers
Name | Type | Mandatory | Description |
appId | String | Y | 게임 앱 ID |
appSecret | String | Y | 게임마다 발급한 인증 key |
playerId | String | Y | 플랫폼에서 발급한 사용자 ID |
Authorization | String | Y | 서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보
|
Request Body Parameters
Name | Type | Mandatory | Description |
|---|---|---|---|
messageBoxId | String | Y | 메시지 박스 ID |
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 상세 설명 |
|---|---|---|
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 |
|---|---|---|
nextPageKey | Long | 다음 페이지 요청시 사용될 nextPageKey
|
messages | List<MessagePacket> | 메시지 목록 |
maxCount | Integer | 최대 보유 가능 메시지 개수 |
totalCount | Integer | 현재 메시지 개수 (전체 페이지) |
MessagePacket
Name | Type | Description |
|---|---|---|
senderAppId | String | 발신자 App ID |
senderId | String | 발신자 ID (playerId) 플랫폼 내부기능에서 발송되는 경우 ( admin, coupon, promotion, leaderboard )로 표시 됩니다. |
appId | String | 수신자 App ID |
receiverId | String | 수신자 ID (playerId) |
message | Message | 메시지 데이터 |
items | List<Item> | 첨부 아이템 목록 |
Message
Name | Type | Description |
|---|---|---|
deliverySeq | Long | 메시지 데이터 |
messageId | String | 메시지 ID |
messageBoxId | String | 메시지 Box 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 |
|---|---|---|
messageId | String | 메시지 ID |
itemId | String | 아이템 고유 ID |
itemCode | String | 아이템 코드 |
quantity | Long | 아이템 수량 |
state | String | 처리 상태값 registered, sent, confirmed, error, deleted, expired |
validityTime | Long | 아이템 유효시간 |
regTime | Long | 등록 시각 |
modTime | Long | 최종 수정 시각 |
sentTime | Long | requestItem 요청 시각 |
confirmedTime | Long | 확인 처리 시각 |
expiredTime | Long | 만료시각 |
Example Request
POST /service/v3/message/getList HTTP/1.1
Host: openapi-zinny3.game.kakao.com:10443
Content-Type: application/json;charset=UTF-8
appId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 23423432453
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
{
"messageBoxId":"inBox",
"count": 1
} |
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"maxCount": 10,
"totalCount": 3,
"nextPageKey": 6,
"messages": [
{
"appId": "103815",
"senderAppId": "103815",
"senderId": "23423432453",
"receiverId": "23423432453",
"message": {
"deliverySeq": 7,
"messageId": "fcc794be-002b-4ec4-abce-b40407a95a93",
"messageBoxId": "inBox",
"title": "test message title",
"body": "test message body",
"resourceMap": {
"imageLink": "test://12221212"
},
"state": "read",
"regTime": 1427350711000,
"modTime": 1427350711000,
"readTime": 1427350711000,
"expiredTime": 1435126739000
},
"items": [
{
"itemId": "e3b35f9f-b556-4473-9aff-6232d9532f61",
"quantity": 100,
"itemCode": "testItem111",
"state": "confirmed",
"regTime": 1427350711000,
"modTime": 1427350711000,
"sentTime": 1427350711000,
"confirmedTime": 1427350711000,
"expiredTime": 1435126739000,
"validityTime": -1
}
]
}
]
} |
/message/finish
Description
메시지에 포함된 아이템의 배송 트랜잭션을 종료 처리(아이템 지급완료)하고 메시지를 삭제합니다.
첨부된 아이템은 /message/finish 후에 게임 우편함에 지급합니다.
게임 우편함에 지급한 후에 /message/finish 할 경우 처리가 되지 않을 경우 카카오 플렛폼에서 삭제되지 않으므로 중복 지급될 우려가 있습니다.
이에대한 예외처리가 되어 있다면 게임 내 우편함에 지급한 후에 /message/finish 호출해도 무방합니다.
Method
POST
Request Headers
Name | Type | Mandatory | Description |
appId | String | Y | 게임 앱 ID |
appSecret | String | Y | 게임마다 발급한 인증 key |
playerId | String | Y | 플랫폼에서 발급한 사용자 ID |
Authorization | String | Y | 서버인증정보: 이 API 호출권한이있는서버인지확인하기위한정보
|
Request Body Parameters
Name | Type | Mandatory | Description |
|---|---|---|---|
messageIds | List<String> | Y | 완료 처리할 메시지 ID 목록 |
Response 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 |
|---|---|---|
results | List<Result> | 아이템 정보 목록 |
Result Content
Name | Type | Description |
|---|---|---|
messageId | String | messageId |
status | Integer | 처리 결과 ( 200 성공 ) |
Example Request
POST /service/v3/message/finish HTTP/1.1
Host: openapi-zinny3.game.kakao.com:10443
Content-Type: application/json;charset=UTF-8
appId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 21792586
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
{
"messageIds": [
"3729694e-913b-4b29-94ef-36fd66f44ce8",
"4234554e-783b-b4g4-3f43-nfc34987fn38"
]
} |
Example Response