연동가이드 >/wiki/spaces/KS4GFP/pages/533463104

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.

...

코드 블럭
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.

...

Name	Type	Description
nextPageKey	Long 다음 페이지 요청시 사용될 nextPageKey	-1 이면 더이상 데이터가 없음 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 아이템 클레임 처리 횟수 2회 이상 클레임 처리 시 이상 동작으로 간주합니다	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	requestItem 요청 시각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보상0802 Reward",
                        "body": "0802보상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

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

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

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

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

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

finish 처리가 끝나기전에 동일한 messageId로 20초 이내에 다시 claimItems 를 호출시에도 406 에러처리가 됩니다. 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 /message/finish is not called, the process is considered incomplete, and if the same request is received again, the same list as before will be returned.

If the same messageId is called more than once through this API, it will be handled as an error and excluded from the delivery processing list.

If the messageId has already been processed through finish, the status value of the result will be handled as an error with a status of 406.

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)

...

Name	Type	Mandatory	Description
messageIds	List<String>	Y	아이템을 수령할 메시지 ID 목록		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	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류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

Result Content

Name	Type	Description
messageId	String	messageId
status	Integer 아이템 클레임 처리 상태 코드	정상 처리 Item claim processing status code Normal processing: 200 에러 발생 Error occurred: 406 아이템이 ‘등록된’ 상태가 아닌 경우 이미 ‘클레임’ 처리된 경우 20초 이내로 중복 클레임 처리 요청이 들어온 경우 클레임 횟수가 2번 이상인 경우When the item is not in a 'registered' state When the item has already been 'claimed' When a duplicate claim request is made within 20 seconds When the number of claims exceeds 2 times
receiverId	String	수신자 Receiver ID
senderId	String	발신자 Sender ID
resourceMap	Map<String, String>메시지 표현 시 필요한 값	Values required to represent the message
items	List<Item>아이템 정보 목록	List of item information

Item

Name	Type	Description
appId	String	App ID
itemCode	String아이템	코드Item code
quantity	Long아이템	수량Item quantity
itemId	String	아이템 고유 Unique item ID
validityTime	Long 유효기한	메시지 전송 시점에 해당필드가 비어있으면 -1로 기록 (예: 프로모션 통해서 아이템 전송받은 경우) Validity period. If this field is empty at the time of message sending, it will be recorded as -1 (e.g., in the case of items sent through promotions).
senderId	String	발신자 Sender ID

Example Request

코드 블럭

POST /service/v5/message/claimItems 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,
                    "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
messageIds	List<String>	Y완료 처리할 메시지 ID 목록	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	파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류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

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
messageIds	List<String>	Y읽음 처리할 메시지 ID 목록	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

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

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)

Example Request

코드 블럭

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"
   ]
}

...

코드 블럭
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
messageIds	List<String>	Y아이템 지급 완료 처리할 메시지 ID 목록	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

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

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)

Example Request

코드 블럭

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"
   ]
}

...

코드 블럭

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
messageIds	List<String>	Y삭제 처리할 메시지 ID 목록	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

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

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)

Example Request

코드 블럭

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"
   ]
}

...

버전	이전 버전 2	새 버전 3
변경한 사람	QATEAM	QATEAM
에 저장	8월 23, 2024	8월 23, 2024

버전 비교

키

/message/send

Description

/message/getList

Description

MessagePacket

Message

Item

Example Request

/message/claimItems

Description

Request Headers

Response Status Code

Response Content

/message/finish

Description

Method

Request Headers

Response Status Code

Result Content

Example Request

/message/markAsRead

Method

Request Headers

Response Status Code

/message/confirmItems

Method

Request Headers

Response Status Code

/message/deleteMessages

Method

Request Headers

Response Status Code

Content Comparison

버전 비교

키

/message/send

Description

/message/getList

Description

MessagePacket

Message

Item

Example Request

/message/claimItems

Description

Request Headers

Response Status Code

Response Content

/message/finish

Description

Method

Request Headers

Response Status Code

Result Content

Example Request

/message/markAsRead

Method

Request Headers

Response Status Code

/message/confirmItems

Method

Request Headers

Response Status Code

/message/deleteMessages

Method

Request Headers

Response Status Code