/message/getList

Description

The list of messages delivered by the message delivery server is queried.
The query retrieves the most recent messages in the first page in reverse time order. Up to 100 messages can be queried in pages.
If the returned nextPageKey value is not -1, the next page can be queried using the key.
A message has a list of multiple attached items.
The attached items are processed by calling /message/finish after the items are applied to the game with /message/claim.

Method

POST

Request Headers

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
appId	String	Y	Game app ID
appSecret	String	Y	Authentication key issued for each game
playerId	String	Y	User ID issued by the platform
Authorization	String	Y	Authorization: KakaoAK {ADMIN_KEY} (Ex) Authorization: KakaoAK 11118035a320f23423585acae3ded1111 {Admin_Key} can be seen in [Kakao GameCenter > Select App > Detail Info > Admin Key].

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
messageBoxId	String	Y	Message Box ID Used to query a specific Message Box only.
count	Integer	Y	Number of messages to query (up to 100)
nextPageKey	Long	N	Beginning offset of queried page The first page is requested if null is entered The first page is requested even if the long max (9223372036854775807) value is entered.
states	List<String>	N	List of message statuses to be queried unread, read, error, deleted, expired Unread, read messages are returned if a value is not specified.

Response Status Code

Status Code	Description	Details

Status Code	Description	Details
200	Success	Normal
400	Bad Request	Request data not parsed. Lack of required parameters or parameter type error
401	Unauthenticated	Authentication failure (e.g., invalid appSecret)
406	Not Acceptable	Cannot be processed
461	Invalid Message Box	The Message Box requested with the messageBoxId does not exist
463	Removed	Unregistered user (The user has requested unregistration, and the Unregistration is being processed. The actual user data exists.)
500	Internal Server Error	Server system internal error
503	Service Unavailable	Service unavailable (e.g., timeout between internal servers)

Response Content

Name	Type	Description

Name	Type	Description
nextPageKey	Long	The nextPageKey to be used when requesting the next page There is no more data if the value is -1
messages	List<MessagePacket>	Message list
maxCount	Integer	Maximum number of messages that can be kept.
totalCount	Integer	Current number of messages (total pages)

MessagePacket

Name	Type	Description

Name	Type	Description
senderAppId	String	Sending App ID
senderId	String	Sender ID (playerId) Is displayed as (admin, coupon, promotion, leaderboard) if sent from the platform’s internal function.
appId	String	Receiving App ID
receiverId	String	Receiver ID (playerId)
message	Message	Message data
items	List<Item>	List of attached items

Message

Name	Type	Description

Name	Type	Description
deliverySeq	Long	Message data
messageId	String	Message ID
messageBoxId	String	Message Box ID
title	String	Title
body	String	Main body
resourceMap	Map	Data value needed to display the message
state	String	Message status value unread, read, error, deleted, expired
regTime	Long	Time of registration, epochTime milliseconds
modTime	Long	Time of last modification, epochTime milliseconds
readTime	Long	Time the message was processed as viewed (read), epochTime milliseconds
expiryTime	Long	Expiration time, epochTime milliseconds

Item

Name	Type	Description

Name	Type	Description
messageId	String	Message ID
itemId	String	Unique item ID
itemCode	String	Item code
quantity	Long	Item quantity
state	String	Processing status value registered, sent, confirmed, error, deleted, expired
validityTime	Long	Time item remains valid
regTime	Long	Time of registration, epochTime milliseconds
modTime	Long	Time of last modification, epochTime milliseconds
sentTime	Long	Time requestItem was requested, epochTime milliseconds
confirmedTime	Long	Time of confirmation, epochTime milliseconds
expiryTime	Long	Expiration time, epochTime milliseconds

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 11118035a320f23423585acae3ded1111
   
{
        "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

The API is called after game provision is successfully processed in the game server after /message/claim.
The delivery transaction of the items contained in a message is processed as complete (item provision completed), and the message is deleted.

Method

POST

Request Headers

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
appId	String	Y	Game app ID
appSecret	String	Y	Authentication key issued for each game
playerId	String	Y	User ID issued by the platform
Authorization	String	Y	Authorization: KakaoAK {ADMIN_KEY} (Ex) Authorization: KakaoAK 11118035a320f23423585acae3ded1111 {Admin_Key} can be seen in [Kakao GameCenter > Select App > Detail Info > Admin Key].

Request Body Parameters

Name	Type	Mandatory	Description

Name	Type	Mandatory	Description
messageIds	List<String>	Y	List of message IDs to be processed as complete

Response Status Code

Status Code	Description	Details

Status Code	Description	Details
200	Success	Normal
400	Bad Request	Request data not parsed. Lack of required parameters or parameter type error
401	Unauthenticated	Authentication failure (e.g., invalid appSecret)
406	Not Acceptable	Cannot be processed
500	Internal Server Error	Server system internal error
503	Service Unavailable	Service unavailable (e.g., timeout between internal servers)

Response Content

Name	Type	Description

Name	Type	Description
results	List<Result>	Item data list

Result

Name	Type	Description

Name	Type	Description
messageId	String	messageId
status	Integer	Processing result (Success 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 11118035a320f23423585acae3ded1111
   
{
   "messageIds": [
      "3729694e-913b-4b29-94ef-36fd66f44ce8",
      "4234554e-783b-b4g4-3f43-nfc34987fn38"
   ]
}

Example Response

Kakaogame SDK 3.0 Guide for Channeling

8.2. Server API Example (/message)

/message/getList

Example Request

Example Response

/message/finish

Example Request