연동가이드 >https:/wiki/spaces/KS4GFP/pages/533463104kakaogames.atlassian.net/wiki/x/TA8GLw

minLevel	1
maxLevel	1
outline	false
type	list
printable	false

/message/send

Description

This API allows the delivery of a message request to another user through the message delivery server.

...

When sending a message, it is possible to attach a list of items. The items to be attached must also be pre-registered via the admin tool before sending.

Method

POST

Request Headers

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)

Request Body Parameters

Name	Type	Mandatory	Description
senderAppId	String	N	Sender App ID (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)

...

Name

Type

Mandatory

Description

itemCode

String

Y

Item code

quantity

Long

Y

Item quantity

validityTime

Long

N

Validity period.

If not specified, set to -1 (unlimited).

Response Status Code

Status Code	Status Code Description	Status Code Detailed Description
200	Normal response	Normal
400	Bad Request	Unparsable request data, missing required parameters, or parameter type error
401	Unauthenticated	Authentication failed
406	Not Acceptable	Cannot process
461	Invalid Message Box	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)

Response Content

Name	Type	Description
messageId	String	The messageId of the delivered message

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": "Title",
        "body": "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

Retrieve a list of messages delivered to the message delivery server.

...

Attached items should be processed by calling /message/claim after applying them in the game, and then /message/finish should be called to complete the process.

Method

POST

Request Headers

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)

Request Body Parameters

Name	Type	Mandatory	Description
messageBoxId	String	N	Mailbox Id - Used to query only a specific message box (Default mailbox if not entered)
count	Integer	Y	Number of messages to retrieve (maximum 100)
nextPageKey	Long	N	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. If not entered, a list of messages in unread and read states is returned.

Response Status Code

Status Code	Status Code Description	Status Code Detailed Description
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 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)

Response Content

Name	Type	Description
nextPageKey	Long	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)

MessagePacket

Name	Type	Description
message	Message	Message data
items	List<Item>	List of attached items
existUnconfirmedItems	Boolean	Whether there are unconfirmed items

Message

Name	Type	Description
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

Item

Name	Type	Description
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	Time when the requestItem was sent
confirmedTime	Long	Confirmation processing time
expiredTime	Long	Expiration time

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
}

...

코드 블럭

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
   
{
        "status": 200,
        "desc": "OK",
        "content": {
            "nextPageKey": -1,
            "messages": [
                {
                    "appId": "103815",
                    "senderId": "admin",
                    "receiverId": "990566329112884",
                    "message": {
                        "deliverySeq": 21519071,
                        "messageId": "6fec1bc2-e3b2-4fd2-a31e-6c192154f61e",
                        "messageBoxId": "inbox",
                        "senderAppId": "103815",
                        "senderId": "admin",
                        "receiverAppId": "103815",
                        "receiverId": "990566329112884",
                        "title": "0802 Reward",
                        "body": "0802 Reward",
                        "titleMap": {},
                        "bodyMap": {},
                        "resourceMap": {},
                        "state": "unread",
                        "regTime": 1690939713000,
                        "modTime": 1690939713000,
                        "readTime": null,
                        "expiredTime": 1691544513000,
                        "expiryTime": 1691544513000
                    },
                    "items": [
                        {
                            "itemId": "f0d1aea9-2c9c-43fd-b227-cd315799b216",
                            "itemCode": "worldcon",
                            "itemName": "Worldcon",
                            "quantity": 5,
                            "state": "registered",
                            "sentCount": 0,
                            "regTime": 1690939713000,
                            "modTime": 1690939713000,
                            "sentTime": null,
                            "confirmedTime": null,
                            "expiredTime": 1691544513000,
                            "expiryTime": 1691544513000,
                            "validityTime": 604800000
                        }
                    ],
                    "existUnconfirmedItems": true
                }
            ],
            "totalCount": 1,
            "maxCount": 1000000
        }
}

...

/message/claimItems

Description

Notifies the platform server to request the receipt of items included in the message.

When this API is called, the list of items to be delivered is returned, and the status is changed to 'In Delivery (Processing Delivery)'. After the process is completed, you must call /message/finish to set the status to completed, thereby concluding the transaction.

...

If claimItems is called again within 20 seconds with the same messageId before finish processing is completed, it will also be handled as a 406 error.

Request Headers

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)

Request Body Parameters

Name	Type	Mandatory	Description
messageIds	List<String>	Y	List of message IDs for which to claim items

Response Status Code

Status Code	Status Code Description	Status Code Detailed Description
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)

Response Content

Name	Type	Description
results	List<Result>	List of item information

...

코드 블럭

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
  
{
            "results": [
                {
                    "messageId": "6fec1bc2-e3b2-4fd2-a31e-6c192154f61e",
                    "status": 200,
                    "receiverId": "990566329112884",
                    "senderId": "admin",
                    "resourceMap": {},
                    "items": [
                      {
                            "appId": "103815",
                            "itemCode": "worldcon",
                            "quantity": 5,
                            "itemId": "f0d1aea9-2c9c-43fd-b227-cd315799b216",
                            "validityTime": 604800000,
                            "senderId": "admin"
                      }
                  ]
              }
          ]
  }

...

/message/finish

Description

Called after the game server has successfully processed the item delivery following the /message/claim.

It finalizes the transaction for the delivery of items included in the message (item delivery completion) and deletes the message.

Method

POST

Request Headers

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)

Request Body Parameters

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

Response Status Code

Status Code	Status Code Description	Status Code Detailed Description
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	Description
results	List<Result>	List of item information

Result Content

Name	Type	Description
messageId	String	messageId
status	Integer	Processing result (200 success)

Example Request

코드 블럭

POST /service/v5/message/finish HTTP/1.1
Host: kr-openapi-zinny3.game.kakao.com:10443
Content-Type: application/json;charset=UTF-8
kgAppId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 21792586
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
   
{
   "messageIds": [
      "6fec1bc2-e3b2-4fd2-a31e-6c192154f61e"
   ]
}

...

코드 블럭
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "results": [ { "messageId": "6fec1bc2-e3b2-4fd2-a31e-6c192154f61e", "status": 200 } ] }

...

/message/markAsRead

Description

Marks the message as read.

The item information and status are retained, but the message is changed to a 'read' state.

Method

POST

Request Headers

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)

Request Body Parameters

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

Response Status Code

Status Code	Status Code Description	Status Code Detailed Description
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)

...

코드 블럭

POST /service/v5/message/markAsRead HTTP/1.1
Host: kr-openapi-zinny3.game.kakao.com:10443
Content-Type: application/json;charset=UTF-8
kgAppId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 21792586
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
  
{
   "messageIds": [
      "3729694e-913b-4b29-94ef-36fd66f44ce8",
      "4234554e-783b-b4g4-3f43-nfc34987fn38"
   ]
}

Example Response

코드 블럭
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { }

...

/message/confirmItems

Description

After the item delivery is completed, this call changes the message status.

Message Status → "Read"
Existence of Unconfirmed Items → "None"

Method

POST

Request Headers

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)

Request Body Parameters

Name	Type	Mandatory	Description
messageIds	List<String>	Y	List of message IDs to be processed for item delivery completion

Response Status Code

Status Code	Status Code Description	Status Code Detailed Description
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)

...

코드 블럭

POST /service/v5/message/confirmItems HTTP/1.1
Host: kr-openapi-zinny3.game.kakao.com:10443
Content-Type: application/json;charset=UTF-8
kgAppId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 21792586
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
  
{
   "messageIds": [
      "3729694e-913b-4b29-94ef-36fd66f44ce8",
      "4234554e-783b-b4g4-3f43-nfc34987fn38"
   ]
}

Example Response

코드 블럭

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
  
{
  "results" : [
    {
      "messageId" : "3729694e-913b-4b29-94ef-36fd66f44ce8",
      "status" : 200
    },
    {
      "messageId" : "4234554e-783b-b4g4-3f43-nfc34987fn38",
      "status" : 200
    }
  ]
}

...

/message/deleteMessages

Description

Changes the message status to 'Deleted'.

Method

POST

Request Headers

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)

Request Body Parameters

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

Response Status Code

Status Code	Status Code Description	Status Code Detailed Description
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)

...

코드 블럭

POST /service/v5/message/deleteMessages HTTP/1.1
Host: kr-openapi-zinny3.game.kakao.com:10443
Content-Type: application/json;charset=UTF-8
kgAppId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 21792586
Authorization: KakaoAK c0948035a320f789f585acae3dedcd70
  
{
   "messageIds": [
      "3729694e-913b-4b29-94ef-36fd66f44ce8",
      "4234554e-783b-b4g4-3f43-nfc34987fn38"
   ]
}

Example Response

코드 블럭
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { }

버전	이전 버전 3	새 버전 현재
변경한 사람	QATEAM	KG_SDKDEV
에 저장	8월 23, 2024	8월 29, 2024

Content Comparison

버전 비교

키

/message/send

Description

Method

Request Headers

Request Body Parameters

Response Status Code

Response Content

Example Request

Example Response

/message/getList

Description

Method

Request Headers

Request Body Parameters

Response Status Code

Response Content

MessagePacket

Message

Item

Example Request

/message/claimItems

Description

Request Headers

Request Body Parameters

Response Status Code

Response Content

/message/finish

Description

Method

Request Headers

Request Body Parameters

Response Status Code

Result Content

Example Request

/message/markAsRead

Method

Request Headers

Request Body Parameters

Response Status Code

Example Response

/message/confirmItems

Method

Request Headers

Request Body Parameters

Response Status Code

Example Response

/message/deleteMessages

Method

Request Headers

Request Body Parameters

Response Status Code

Example Response