Kakao Moment

Message ad management

This document describes how to use the Message ad management API for Kakao Moment message ads. The Message ad management API provides common management functions required for Message ad operation.

Message creatives, under Kakao Talk Channel x reach campaigns can be found in Ad creation: Message creative, and personalized message x reach campaign message materials can be found in Ad creation: Personalized message creative.

View list of message ads

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves a list of message ads created under the Kakao Talk Channel.

Send a POST request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes a list of message ads. If failed, see Error code.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Authorization method, authenticate with Business token	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account ID	O
channel-profile-id	`channel-profile-id: ${CHANNEL_PROFILE_ID}` Kakao Talk Channel profile ID	O
Content-Type	`Content-Type: application/json` Request data type	O

Query parameters

Name	Type	Description	Required
page	`Integer`	Page number Starts from 0	X
limit	`Integer`	Page size	X
from	`String`	Metric lookup period start date (default: 2 years before the lookup date) `yyyy-MM-dd` format	X
to	`String`	Metric lookup period end date (default: lookup date) `yyyy-MM-dd` format	X

Body

Name	Type	Description	Required
filter	`Filter`	List lookup filter	X

Filter

Name	Type	Description	Required
messageAdType	`String`	Message ad type `BROADCAST`: Message ad	X
messageAdIds	`String[]`	List of message ad numbers (identification numbers assigned when first created)	X
statuses	`String[]`	Message status `DRAFT`: Draft `READY`: Before sending `SENDING`: Sending `FINISHED`: Send complete `ADMIN_STOP`: Admin stop `DEL`: Delete	X
messageTypes	`String[]`	Message type `BASIC_TEXT_MESSAGE`: Basic text `WIDE_MESSAGE`: Wide image `WIDE_LIST_MESSAGE`: Wide list `CAROUSEL_COMMERCE_MESSAGE`: Carousel commerce `CAROUSEL_FEED_MESSAGE`: Carousel feed `PREMIUM_VIDEO_MESSAGE`: Premium video `CATALOG_MESSAGE`: Catalog	X
start	`String`	Send time start date, `YYYY-MM-DD` format Important: Required when `end` is included	X
end	`String`	Send time end date, `YYYY-MM-DD` format End date can be set from start date to lookup date Important: Required when `start` is included	X
searchKeyword	`String`	Message name search keyword Returns search results containing the keyword in the message name (`like` search)	X

Response

Body

Name	Type	Description
content	`Content[]`	Message ad list
totalPages	`Long`	Total number of pages, total number of pages that will be responded when looking up
totalElements	`Long`	Total number of message ads that can be responded
first	`Boolean`	Whether it's the first page, one of the following `true`: First page `false`: Not the first page
last	`Boolean`	Whether it's the last page, one of the following `true`: Last page `false`: Not the last page
size	`Integer`	Page size, number of message ads per page
number	`Integer`	Page number
numberOfElements	`Integer`	Number of message ads included in the current page

Content

Name	Type	Description
messageAdId	`String`	Message ad number, identification number assigned when first created
messageAdType	`String`	Message ad type `BROADCAST`: Message ad
message	`SimpleMessage`	Message simple information
name	`String`	Message name (maximum: 50 characters), value with automatic generation rules applied when not entered during first creation
status	`String`	Message status, one of the following `DRAFT`: Draft `READY`: Before sending `SENDING`: Sending `FINISHED`: Send complete `ADMIN_STOP`: Admin stop `DEL`: Delete
sendingReservation	`SendingReservation`	Message send reservation information
metrics	`Metrics`	Message summary report
createdDate	`String`	Message ad creation date, `yyyy-MM-dd HH:mm:ss` format
lastModifiedDate	`String`	Message ad last modification date, `yyyy-MM-dd HH:mm:ss` format

SimpleMessage

Name Type Description

type String Message type, one of the following
BASIC_TEXT_MESSAGE: Basic text
WIDE_MESSAGE: Wide image
WIDE_LIST_MESSAGE: Wide list
CAROUSEL_COMMERCE_MESSAGE: Carousel commerce type
CAROUSEL_FEED_MESSAGE: Carousel feed type
PREMIUM_VIDEO_MESSAGE: Premium video
CATALOG_MESSAGE: Catalog

mainImageUrl

Name	Type	Description
type	`String`	Message type, one of the following `BASIC_TEXT_MESSAGE`: Basic text `WIDE_MESSAGE`: Wide image `WIDE_LIST_MESSAGE`: Wide list `CAROUSEL_COMMERCE_MESSAGE`: Carousel commerce type `CAROUSEL_FEED_MESSAGE`: Carousel feed type `PREMIUM_VIDEO_MESSAGE`: Premium video `CATALOG_MESSAGE`: Catalog
mainImageUrl	`String`	Message image Basic text (no image registered) Responds with `NULL` Basic text, wide image, wide list Responds with `message.items.imageurl` Carousel commerce, carousel feed Carousel commerce, when intro carousel exists: responds with `introcarousel.imageurl` When intro carousel doesn't exist: responds with `message.carousel.imageurl` of the 1st carousel Catalog Image of the first item in the catalog (Responds with `items[0].imageUrl`)
mainTitle	`String`	Message representative text Basic text, wide image, wide list, catalog Responds with `message.title` (maximum 400 characters) Carousel commerce, carousel feed Carousel commerce, when intro carousel exists: responds with `introcarousel.title` When intro carousel doesn't exist: responds with `message.carousel.title` of the 1st carousel

String

Message image

Basic text (no image registered)

Responds with NULL

Basic text, wide image, wide list

Responds with message.items.imageurl

Carousel commerce, carousel feed

Carousel commerce, when intro carousel exists: responds with introcarousel.imageurl
When intro carousel doesn't exist: responds with message.carousel.imageurl of the 1st carousel

Catalog

Image of the first item in the catalog (Responds with items[0].imageUrl)

mainTitle

String

Message representative text
Basic text, wide image, wide list, catalog

Responds with message.title (maximum 400 characters)

Carousel commerce, carousel feed

Carousel commerce, when intro carousel exists: responds with introcarousel.title

When intro carousel doesn't exist: responds with message.carousel.title of the 1st carousel

SendingReservation

Name	Type	Description
deviceTypes	`String[]`	Device type `ANDROID`: Android `IOS`: iOS
targeting	`Targeting`	Targeting information
price	`Long`	Send unit price (unit: won), one of the following `15`: No targeting applied `20`: Targeting applied
contractCount	`Integer`	Purchase send count, message ad send reservation count
totalBudget	`Long`	Purchase amount, total amount for message ad send reservation
totalBudgetWithVAT	`Long`	Purchase amount including VAT, amount including VAT in `totalBudget`
date	`String`	Send start date and time, `yyyy-MM-dd'T'HH:mm` format

Targeting

Name	Type	Description
genderType	`String`	Gender overall selection type, one of the following `ALL`: All selected `NOT_ALL`: Partial selection
genders	`String[]`	Gender `M`: Male `F`: Female
ageType	`String`	Age overall selection type, one of the following `ALL`: All selected `NOT_ALL`: Partial selection
ages	`String[]`	Age group `15`: 15-19 `20`: 20-24 `25`: 25-29 `30`: 30-34 `35`: 35-39 `40`: 40-44 `45`: 45-49 `50`: 50-54 `55`: 55-59 `60`: 60-64 `65`: 65-69
locationType	`String`	Location selection type, one of the following `ALL`: All (domestic, overseas) `DOMESTIC`: Domestic only `AREA`: Area selection
depth1Locations	`Location[]`	Demographics > Administrative district > City/Province Refer to City/province lookup
depth2Locations	`Depth2Location[]`	Demographics > Administrative district > City/County/District Refer to City/County/District lookup
depth3Locations	`Depth3Location[]`	Demographics > Administrative district > Dong/Eup/Myeon Refer to Dong/Eup/Myeon lookup

Metrics

Name	Type	Description
cost	`Long`	Message send cost (VAT excluded), total cost charged for completed message ad sending
msg_send	`Long`	Message send count, cumulative number of messages sent to users
msg_send_fail	`Long`	Message send failure count, cumulative number of messages that failed to send to users
msg_open	`Long`	Message view count, number of users who viewed sent messages after entering chat room
msg_click	`Long`	Message click count, total number of clicks generated from messages

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
    -H "Content-Type: application/json" \
    -d '{
    "filter": {
        "messageAdType": "PERSONAL",
        "messageAdIds": [],
        "statuses": [],
        "messageTypes": [],
        "start": null,
        "end": null,
        "searchKeyword": "Message"
        }
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
            "messageAdId": "msg-ad-1196357486962585601",
            "messageAdType": "PERSONAL",
            "name": "Message_Ad_Test_Wide_Image",
            "status": "READY",
            "sendingReservation": {
                "deviceTypes": [],
                "targeting": {
                    "genderType": "ALL",
                    "genders": [],
                    "ageType": "ALL",
                    "ages": [],
                    "locationType": "ALL",
                    "depth1Locations": [],
                    "depth2Locations": [],
                    "depth3Locations": []
                },
                "date": "2024-01-15 16:37"
            },
            "metrics": null,
            "createdDate": "2024-01-15 16:37:32",
            "lastModifiedDate": "2024-01-15 16:37:32"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 10,
        "sort": {
            "empty": false,
            "sorted": true,
            "unsorted": false
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalElements": 19,
    "totalPages": 2,
    "first": true,
    "size": 10,
    "number": 0,
    "sort": {
        "empty": false,
        "sorted": true,
        "unsorted": false
    },
    "numberOfElements": 10,
    "empty": false
}

View message ad

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves detailed information about individual message ads.

You can check message content, send time, send target, etc.

Send a GET request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes message ad detailed information as a JSON object. If failed, see Error code.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Authorization method, authenticate with Business token	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account ID	O
channel-profile-id	`channel-profile-id: ${CHANNEL_PROFILE_ID}` Kakao Talk Channel profile ID	O
Content-Type	`Content-Type: application/json` Request data type	O

Path variable

Name	Type	Description	Required
MESSAGE_AD_ID	`String`	Message ad number (`messageAdId`)	O

Response

Body

Name	Type	Description
messageAdId	`String`	Message ad number, identification number assigned when first created
messageAdType	`String`	Message ad type `BROADCAST`: Message ad
name	`String`	Message name (maximum: 50 characters), value with automatic generation rules applied when not entered during first creation
message	`ResponseMessage`	Message information
sendingReservation	`SendingReservation`	Message send reservation information
status	`String`	Message status, one of the following `DRAFT`: Draft `READY`: Before sending `SENDING`: Sending `FINISHED`: Send complete `ADMIN_STOP`: Admin stop `DEL`: Delete
ageVerification	`Boolean`	Whether age verification is required for the message `true`: Age verification required message `false`: Regular message
createdDate	`String`	Message ad creation date, `yyyy-MM-dd HH:mm:ss` format
lastModifiedDate	`String`	Message ad last modification date, `yyyy-MM-dd HH:mm:ss` format

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
    -H "Content-Type: application/json"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "messageAdId": "msg-ad-1195183093423038464",
    "messageAdType": "BROADCAST",
    "name": "Message_Ad_Test_Wide_Image",
    "message": {
        "type": "WIDE_MESSAGE",
        "title": "Promotional Text",
        "items": [
            {
                "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/72750c9573241f3409d6f8e44cd66ac8.jpg",
                "pcLandingUrl": "https://daum.net",
                "mobileLandingUrl": "https://daum.net"
            }
        ],
        "buttons": [
            {
                "title": "Button 1 Name",
                "pcLandingUrl": "https://daum.net/1",
                "mobileLandingUrl": "https://daum.net/1"
            }
        ],
        "couponBook": {
            "title": "Coupon Detailed Description",
            "pcLandingUrl": "https://daum.net",
            "mobileLandingUrl": "https://daum.net",
            "couponBookTitle": "Coupon Title",
            "couponBookTitleType": "UPGRADE"
        },
        "ageVerification": false,
        "adFlag": true,
        "shareFlag": true
    },
    "sendingReservation": {},
    "status": "DRAFT",
    "ageVerification": false,
    "createdDate": "2024-01-12 10:50:54",
    "lastModifiedDate": "2024-01-12 10:50:54"
}

Delete message ad

Basic information

Method	URL	Authorization
`DELETE`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Deletes a message ad.

Deleted message information can no longer be retrieved and cannot be recovered.

Send a DELETE request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response returns only HTTP 200 status code without a body. If failed, see Error code.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Authorization method, authenticate with Business token	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account ID	O
channel-profile-id	`channel-profile-id: ${CHANNEL_PROFILE_ID}` Kakao Talk Channel profile ID	O
Content-Type	`Content-Type: application/json` Request data type	O

Path variable

Name	Type	Description	Required
MESSAGE_AD_ID	`String`	Message ad number (`messageAdId`)	O

Sample

Request

curl -v -X DELETE "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
    -H "Content-Type: application/json"

Response

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8

View messages

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/message`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves detailed message content.

Send a GET request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes detailed message information. If failed, see Error code.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Authorization method, authenticate with Business token	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account ID	O
channel-profile-id	`channel-profile-id: ${CHANNEL_PROFILE_ID}` Kakao Talk Channel profile ID	O
Content-Type	`Content-Type: application/json` Request data type	O

Path variable

Name	Type	Description	Required
MESSAGE_AD_ID	`String`	Message ad number (`messageAdId`)	O

Response

Body

Message ads: Message Type Components

Name	Type	Description
messageAdId	`String`	Message ad number, identification number assigned when first created
name	`String`	Message name (maximum: 50 characters), value with automatic generation rules applied when not entered during first creation
type	`String`	Message type, one of the following `BASIC_TEXT_MESSAGE`: Basic text `WIDE_MESSAGE`: Wide image `WIDE_LIST_MESSAGE`: Wide list `CAROUSEL_COMMERCE_MESSAGE`: Carousel commerce type `CAROUSEL_FEED_MESSAGE`: Carousel feed type `PREMIUM_VIDEO_MESSAGE`: Premium video `CATALOG_MESSAGE`: Catalog
title	`String`	Promotional text
items	`Item[]`	List information
buttons	`Button[]`	Button information
couponBook	`CouponBook[]`	Coupon information
introCarousel	`IntroCarousel`	Intro information
carousels	`Carousel[]`	Carousel information
ageVerification	`Boolean`	Whether age verification is required for the message `true`: Age verification required message `false`: Regular message
adFlag	`Boolean`	Ad message `true`: Ad message `false`: Information message
shareFlag	`Boolean`	Whether to use share `true`: Use share `false`: Do not use share Important: Cannot be used when `ageVerification` value is `true`

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/message" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
    -H "Content-Type: application/json"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "messageAdId": "msg-ad-1195179794616258561",
    "name": "Message_Ad_Test_Basic_Text",
    "type": "BASIC_TEXT_MESSAGE",
    "title": "Promotional Text",
    "items": [
        {
            "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/3912ceec1584f2ec1ccf8fad73145254.jpg"
        }
    ],
    "buttons": [
        {
            "title": "Button 1 Name",
            "pcLandingUrl": "https://daum.net/1",
            "mobileLandingUrl": "https://daum.net/1"
        },
        {
            "title": "Button 2 Name",
            "pcLandingUrl": "https://daum.net/1",
            "mobileLandingUrl": "https://daum.net/1"
        }
    ],
    "couponBook": {
        "title": "Coupon Detailed Description",
        "pcLandingUrl": "https://daum.net",
        "mobileLandingUrl": "https://daum.net",
        "couponBookTitle": "Coupon Title",
        "couponBookTitleType": "UPGRADE"
    },
    "ageVerification": false,
    "adFlag": false,
    "shareFlag": true
}

Copy message

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/copy`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Copies the message that will be sent from the Kakao Talk Channel.

Send a POST request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes detailed information of the copied message as a JSON object. If failed, see Error code.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Authorization method, authenticate with Business token	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account ID	O
channel-profile-id	`channel-profile-id: ${CHANNEL_PROFILE_ID}` Kakao Talk Channel profile ID	O
Content-Type	`Content-Type: application/json` Request data type	O

Path variable

Name	Type	Description	Required
MESSAGE_AD_ID	`String`	Message ad number (`messageAdId`)	O

Response

Body

Message ads: Message Type Components

Name	Type	Description
messageAdId	`String`	Message ad number, identification number assigned when first created
name	`String`	Message name (maximum: 50 characters), value with automatic generation rules applied when not entered during first creation
type	`String`	Message type, one of the following `BASIC_TEXT_MESSAGE`: Basic text `WIDE_MESSAGE`: Wide image `WIDE_LIST_MESSAGE`: Wide list `CAROUSEL_COMMERCE_MESSAGE`: Carousel commerce type `CAROUSEL_FEED_MESSAGE`: Carousel feed type `PREMIUM_VIDEO_MESSAGE`: Premium video `CATALOG_MESSAGE`: Catalog
title	`String`	Promotional text
items	`Item[]`	Item information
buttons	`Button[]`	Button information
couponBook	`CouponBook[]`	Coupon information
introCarousel	`IntroCarousel`	Intro information
carousels	`Carousel[]`	Carousel information
ageVerification	`Boolean`	Whether age verification is required for the message `true`: Age verification required message `false`: Regular message
adFlag	`Boolean`	Ad message `true`: Ad message `false`: Information message
shareFlag	`Boolean`	Whether to use share `true`: Use share `false`: Do not use share Important: Cannot be used when `ageVerification` value is `true`

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/copy" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
    -H "Content-Type: application/json"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "messageAdId": "msg-ad-1195179794616258561",
    "name": "Message_Ad_Test_Basic_Text",
    "type": "BASIC_TEXT_MESSAGE",
    "title": "Promotional Text Changed",
    "items": [
        {
            "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/3912ceec1584f2ec1ccf8fad73145254.jpg"
        }
    ],
    "buttons": [
        {
            "title": "Button 1 Name",
            "pcLandingUrl": "https://daum.net/1",
            "mobileLandingUrl": "https://daum.net/1"
        },
        {
            "title": "Button 2 Name",
            "pcLandingUrl": "https://daum.net/1",
            "mobileLandingUrl": "https://daum.net/1"
        }
    ],
    "couponBook": {
        "title": "Coupon Detailed Description",
        "pcLandingUrl": "https://daum.net",
        "mobileLandingUrl": "https://daum.net",
        "couponBookTitle": "Coupon Title",
        "couponBookTitleType": "UPGRADE"
    },
    "ageVerification": false,
    "adFlag": false,
    "shareFlag": true
}

View message ad report

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/reports`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves reports for messages.

Report metric groups (metricsGroup) can be selected multiple times.

Reports for specific dates are variable real-time metrics for reference until 8 AM the next day. If you're interested in today's (real-time) report, use datePreset=TODAY, and if you want hourly data, use dimension=HOUR.

You can request one of dataPreset or start, end. If requested in duplicate, data under start, end conditions will be retrieved.

Report lookup criteria (dimension) provides MESSAGE_TYPE (message type), DEVICE_TYPE (device), HOUR (time period).

Send a POST request with the business token and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes report data as an array under the data field. If failed, see Error code.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Authorization method, authenticate with Business token	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account ID	O
channel-profile-id	`channel-profile-id: ${CHANNEL_PROFILE_ID}` Kakao Talk Channel profile ID	O
Content-Type	`Content-Type: application/json` Request data type	O

Body

Name	Type	Description	Required
messageAdIds	`String[]`	List of message ad numbers (maximum: 100)	X
datePreset	`DatePreset`	Report lookup period, one of the following `TODAY`: Today (default) `YESTERDAY`: Yesterday `LAST_7DAY`: Last 1 week `LAST_14DAY`: Last 2 weeks `LAST_30DAY`: Last 30 days `THIS_MONTH`: This month `LAST_MONTH`: Last month	X
start	`String`	Report lookup period start date, `YYYY-MM-DD` format If either `start` or `end` is `null`, lookup based on `datePreset` If `datePreset` is also not specified, lookup based on `TODAY` in `datePreset` Start date can be set up to the day before lookup date	X
end	`String`	Report lookup period end date, `YYYY-MM-DD` format End date can be set from start date to the day before lookup date	X
dimension	`Dimension`	Report lookup criteria, criteria by which data will be grouped when looking up reports	O
metricsGroup	`MetricsGroup[]`	Report metric groups	O

Enum: Dimension

Value	Description	Code
MESSAGE_AD	Message ad	MESSAGE_AD
MESSAGE_TYPE	Message type Basic text Wide list Wide image Carousel commerce Carousel feed Catalog	BASIC_TEXT_MESSAGE WIDE_LIST_MESSAGE WIDE_MESSAGE CAROUSEL_COMMERCE_MESSAGE CAROUSEL_FEED_MESSAGE CATALOG_MESSAGE
DEVICE_TYPE	Device total PC Android iOS Others	total PC Android iOS N/A
HOUR	Hour total 00:00-00:59 01:00-01:59 02:00-02:59 03:00-03:59 04:00-04:59 05:00-05:59 06:00-06:59 07:00-07:59 08:00-08:59 09:00-09:59 10:00-10:59 11:00-11:59 12:00-12:59 13:00-13:59 14:00-14:59 15:00-15:59 16:00-16:59 17:00-17:59 18:00-18:59 19:00-19:59 20:00-20:59 21:00-21:59 22:00-22:59 23:00-23:59	total 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23

MetricsGroup

Value	Description	Code
MESSAGE	Message basic metrics Cost Send count View count Total click count Send failure count	cost msg_send msg_open msg_click msg_send_fail
MESSAGE_ADDITION	Message additional metrics Cost per send Cost per view Cost per total click View rate Message click rate	cost_per_msg_send cost_per_msg_open cost_per_msg_click msg_open_rate msg_click_rate
PIXEL_SDK_CONVERSION	Pixel & SDK conversion metrics Complete a signup (1 day) Complete a signup (7 days) View cart (1 day) View cart (7 days) Purchase (1 day) Purchase (7 days) Purchase price (1 day) Purchase price (7 days) Potential customer (1 day) Potential customer (7 days) Service registration (1 day) Service registration (7 days) Install app (1 day) Install app (7 days) Cost per sign up (1 day) Cost per sign up (7 days) Signup rate (1 day) Signup rate (7 days) Adding to wishlist (1 Day) Cost per adding wishlist (1 Day) Rate of adding to wishlist (1 Day) Adding to wishlist (7 Days) Cost per adding wishlist (7 Days) Rate of adding to wishlist (7 Days) Adding to cart (1 Day) Cost per adding to cart (1 Day) Rate of adding to cart (1 Day) Adding to cart (7 Days) Cost per adding to cart(7 Days) Rate of adding to cart (7 Days) Cost per cart viewing (1 day) Cost per cart viewing (7 days) Cart viewing rate (1 day) Cart viewing rate (7 days) Cost per purchase (1 day) Cost per purchase (7 days) Purchase rate (1 day) Purchase rate (7 days) Cost per potential customer (1 day) Cost per potential customer (7 days) Potential customer rate (1 day) Potential customer rate (7 days) Cost per service registration (1 day) Cost per service registration (7 days) Service registration rate (1 day) Service registration rate (7 days) Cost per app installation (1 day) Cost per app installation (7 days) App installation rate (1 day) App installation rate (7 days)	conv_cmpt_reg_1d conv_cmpt_reg_7d conv_view_cart_1d conv_view_cart_7d conv_purchase_1d conv_purchase_7d conv_purchase_p_1d conv_purchase_p_7d conv_participation_1d conv_participation_7d conv_signup_1d conv_signup_7d conv_app_install_1d conv_app_install_7d cost_per_conv_cmpt_reg_1d cost_per_conv_cmpt_reg_7d conv_cmpt_reg_1d_rate conv_cmpt_reg_7d_rate conv_add_to_wishlist_1d cost_per_conv_add_to_wishlist_1d conv_add_to_wishlist_1d_rate conv_add_to_wishlist_7d cost_per_conv_add_to_wishlist_7d conv_add_to_wishlist_7d_rate conv_add_to_cart_1d cost_per_conv_add_to_cart_1d conv_add_to_cart_1d_rate conv_add_to_cart_7d cost_per_conv_add_to_cart_7d conv_add_to_cart_7d_rate cost_per_conv_view_cart_1d cost_per_conv_view_cart_7d conv_view_cart_1d_rate conv_view_cart_7d_rate cost_per_conv_purchase_1d cost_per_conv_purchase_7d conv_purchase_1d_rate conv_purchase_7d_rate cost_per_conv_participation_1d cost_per_conv_participation_7d conv_participation_1d_rate conv_participation_7d_rate cost_per_conv_signup_1d cost_per_conv_signup_7d conv_signup_1d_rate conv_signup_7d_rate cost_per_conv_app_install_1d cost_per_conv_app_install_7d conv_app_install_1d_rate conv_app_install_7d_rate
MESSAGE_CLICK	Message click metrics Share button clicks Image/Video clicks Title clicks Text clicks List 1 clicks List 2 clicks List 3 clicks List 4 clicks List 5 clicks Button 1 clicks Button 2 clicks Carousel 1 Button 1 clicks Carousel 2 Button 1 clicks Carousel 3 Button 1 clicks Carousel 4 Button 1 clicks Carousel 5 Button 1 clicks Carousel 6 Button 1 clicks Carousel 1 Button 2 clicks Carousel 2 Button 2 clicks Carousel 3 Button 2 clicks Carousel 4 Button 2 clicks Carousel 5 Button 2 clicks Carousel 6 Button 2 clicks Carousel 1 Coupon Button clicks Carousel 2 Coupon Button clicks Carousel 3 Coupon Button clicks Carousel 4 Coupon Button clicks Carousel 5 Coupon Button clicks Carousel 6 Coupon Button clicks Item 1 clicks Item 2 clicks Item 3 clicks Item 4 clicks Item 5 clicks Item 6 clicks Item 7 clicks More button clicks Coupon Button clicks Other clicks	msg_click_share msg_click_media msg_click_title msg_click_text msg_click_list1 msg_click_list2 msg_click_list3 msg_click_list4 msg_click_list5 msg_click_button1 msg_click_button2 msg_click_carousel_button1 msg_click_carousel_button2 msg_click_carousel_button3 msg_click_carousel_button4 msg_click_carousel_button5 msg_click_carousel_button6 msg_click_carousel_share1 msg_click_carousel_share2 msg_click_carousel_share3 msg_click_carousel_share4 msg_click_carousel_share5 msg_click_carousel_share6 msg_click_carousel1_coupon msg_click_carousel2_coupon msg_click_carousel3_coupon msg_click_carousel4_coupon msg_click_carousel5_coupon msg_click_carousel6_coupon msg_click_catalog_item1 msg_click_catalog_item2 msg_click_catalog_item3 msg_click_catalog_item4 msg_click_catalog_item5 msg_click_catalog_item6 msg_click_catalog_item7 msg_click_carousel_more msg_click_coupon msg_click_others
MESSAGE_CAROUSEL_VIEW	Message impression metrics Carousel intro impressions Carousel 1 impressions Carousel 2 impressions Carousel 3 impressions Carousel 4 impressions Carousel 5 impressions Carousel 6 impressions	msg_carousel_intro_view msg_carousel1_view msg_carousel2_view msg_carousel3_view msg_carousel4_view msg_carousel5_view msg_carousel6_view

Response

Body

Name	Type	Description
code	`Integer`	Response code
message	`String`	Result notification message
data	`Data`	Each report detailed data

Data

Name	Type	Description
start	`String`	Start date, `YYYY-MM-DD` format
end	`String`	End date, `YYYY-MM-DD` format
dimensions	`Dimension`	Report criteria and values
metrics	`MetricsGroup`	Report metrics and values

Dimension

Value	Description	Code
message_ad_id	Message ad number Identification number assigned when first created	-
MESSAGE_AD	Message ad	MESSAGE_AD
MESSAGE_TYPE	Message type Basic text Wide list Wide image Carousel commerce Carousel feed Catalog	BASIC_TEXT_MESSAGE WIDE_LIST_MESSAGE WIDE_MESSAGE CAROUSEL_COMMERCE_MESSAGE CAROUSEL_FEED_MESSAGE CATALOG_MESSAGE
DEVICE_TYPE	Device total PC Android iOS Others	total PC Android iOS N/A
HOUR	Hour total 00:00-00:59 01:00-01:59 02:00-02:59 03:00-03:59 04:00-04:59 05:00-05:59 06:00-06:59 07:00-07:59 08:00-08:59 09:00-09:59 10:00-10:59 11:00-11:59 12:00-12:59 13:00-13:59 14:00-14:59 15:00-15:59 16:00-16:59 17:00-17:59 18:00-18:59 19:00-19:59 20:00-20:59 21:00-21:59 22:00-22:59 23:00-23:59	total 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23

MetricsGroup

Value	Description	Code
MESSAGE	Message basic metrics Cost Send count View count Total click count Send failure count	cost msg_send msg_open msg_click msg_send_fail
MESSAGE_ADDITION	Message additional metrics Cost per send Cost per view Cost per total click View rate Message click rate	cost_per_msg_send cost_per_msg_open cost_per_msg_click msg_open_rate msg_click_rate
PIXEL_SDK_CONVERSION	Pixel & SDK conversion metrics Complete a signup (1 day) Complete a signup (7 days) View cart (1 day) View cart (7 days) Purchase (1 day) Purchase (7 days) Purchase price (1 day) Purchase price (7 days) Potential customer (1 day) Potential customer (7 days) Service registration (1 day) Service registration (7 days) Install app (1 day) Install app (7 days) Cost per sign up (1 day) Cost per sign up (7 days) Signup rate (1 day) Signup rate (7 days) Adding to wishlist (1 Day) Cost per adding wishlist (1 Day) Rate of adding to wishlist (1 Day) Adding to wishlist (7 Days) Cost per adding wishlist (7 Days) Rate of adding to wishlist (7 Days) Adding to cart (1 Day) Cost per adding to cart (1 Day) Rate of adding to cart (1 Day) Adding to cart (7 Days) Cost per adding to cart(7 Days) Rate of adding to cart (7 Days) Cost per cart viewing (1 day) Cost per cart viewing (7 days) Cart viewing rate (1 day) Cart viewing rate (7 days) Cost per purchase (1 day) Cost per purchase (7 days) Purchase rate (1 day) Purchase rate (7 days) Cost per potential customer (1 day) Cost per potential customer (7 days) Potential customer rate (1 day) Potential customer rate (7 days) Cost per service registration (1 day) Cost per service registration (7 days) Service registration rate (1 day) Service registration rate (7 days) Cost per app installation (1 day) Cost per app installation (7 days) App installation rate (1 day) App installation rate (7 days)	conv_cmpt_reg_1d conv_cmpt_reg_7d conv_view_cart_1d conv_view_cart_7d conv_purchase_1d conv_purchase_7d conv_purchase_p_1d conv_purchase_p_7d conv_participation_1d conv_participation_7d conv_signup_1d conv_signup_7d conv_app_install_1d conv_app_install_7d cost_per_conv_cmpt_reg_1d cost_per_conv_cmpt_reg_7d conv_cmpt_reg_1d_rate conv_cmpt_reg_7d_rate conv_add_to_wishlist_1d cost_per_conv_add_to_wishlist_1d conv_add_to_wishlist_1d_rate conv_add_to_wishlist_7d cost_per_conv_add_to_wishlist_7d conv_add_to_wishlist_7d_rate conv_add_to_cart_1d cost_per_conv_add_to_cart_1d conv_add_to_cart_1d_rate conv_add_to_cart_7d cost_per_conv_add_to_cart_7d conv_add_to_cart_7d_rate cost_per_conv_view_cart_1d cost_per_conv_view_cart_7d conv_view_cart_1d_rate conv_view_cart_7d_rate cost_per_conv_purchase_1d cost_per_conv_purchase_7d conv_purchase_1d_rate conv_purchase_7d_rate cost_per_conv_participation_1d cost_per_conv_participation_7d conv_participation_1d_rate conv_participation_7d_rate cost_per_conv_signup_1d cost_per_conv_signup_7d conv_signup_1d_rate conv_signup_7d_rate cost_per_conv_app_install_1d cost_per_conv_app_install_7d conv_app_install_1d_rate conv_app_install_7d_rate
MESSAGE_CLICK	Message Click Metrics Share button clicks Image/Video clicks Title clicks Text clicks List 1 clicks List 2 clicks List 3 clicks List 4 clicks List 5 clicks Button 1 clicks Button 2 clicks Carousel 1 Button 1 clicks Carousel 2 Button 1 clicks Carousel 3 Button 1 clicks Carousel 4 Button 1 clicks Carousel 5 Button 1 clicks Carousel 6 Button 1 clicks Carousel 1 Button 2 clicks Carousel 2 Button 2 clicks Carousel 3 Button 2 clicks Carousel 4 Button 2 clicks Carousel 5 Button 2 clicks Carousel 6 Button 2 clicks Carousel 1 Coupon Button clicks Carousel 2 Coupon Button clicks Carousel 3 Coupon Button clicks Carousel 4 Coupon Button clicks Carousel 5 Coupon Button clicks Carousel 6 Coupon Button clicks Item 1 clicks Item 2 clicks Item 3 clicks Item 4 clicks Item 5 clicks Item 6 clicks Item 7 clicks More button clicks Coupon button clicks Other clicks	msg_click_share msg_click_media msg_click_title msg_click_text msg_click_list1 msg_click_list2 msg_click_list3 msg_click_list4 msg_click_list5 msg_click_button1 msg_click_button2 msg_click_carousel_button1 msg_click_carousel_button2 msg_click_carousel_button3 msg_click_carousel_button4 msg_click_carousel_button5 msg_click_carousel_button6 msg_click_carousel_share1 msg_click_carousel_share2 msg_click_carousel_share3 msg_click_carousel_share4 msg_click_carousel_share5 msg_click_carousel_share6 msg_click_carousel1_coupon msg_click_carousel2_coupon msg_click_carousel3_coupon msg_click_carousel4_coupon msg_click_carousel5_coupon msg_click_carousel6_coupon msg_click_catalog_item1 msg_click_catalog_item2 msg_click_catalog_item3 msg_click_catalog_item4 msg_click_catalog_item5 msg_click_catalog_item6 msg_click_catalog_item7 msg_click_carousel_more msg_click_coupon msg_click_others

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/reports" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
    -H "Content-Type: application/json" \
    -d '{
        "dimension": "MESSAGE_AD",
        "start": null,
        "end": null,
        "datePreset": "LAST_30DAY",
        "messageAdIds": ["msg-ad-1164368618878062593"],
        "metricsGroup": ["MESSAGE", "MESSAGE_ADDITION", "MESSAGE_CLICK", "PIXEL_SDK_CONVERSION"]
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "code":200,
  "message":"Success",
  "data":[
    {
      "start":"2023-10-10",
      "end":"2023-10-10",
      "dimensions":{
        "message_ad_id":"msg-ad-1"
      },
      "metrics":{
        "msg_click":0,
        "msg_send":0,
        "cost":0.0,
        "msg_send_fail":0,
        "msg_open":1
      }
    }
  ]
}

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

Message ad management

View list of message ads

Basic information

Request

Header

Query parameters

Body

Filter

Response

Body

Content

SimpleMessage

SendingReservation

Targeting

Metrics

Sample

Request

Response

View message ad

Basic information

Request

Header

Path variable

Response

Body

Sample

Request

Response

Delete message ad

Basic information

Request

Header

Path variable

Sample

Request

Response

View messages

Basic information

Request

Header

Path variable

Response

Body

Sample

Request

Response

Copy message

Basic information

Request

Header

Path variable

Response

Body

Sample

Request

Response

View message ad report

Basic information

Request

Header

Body

Enum: Dimension

MetricsGroup

Response

Body

Data

Dimension

MetricsGroup

Sample