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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

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

Request

Header

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

Query parameter

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 Fixed to `BROADCAST` (Message ad). Note: The response also includes `MULTI_BROADCAST` (Optimized 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 `PAUSE`: Paused `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 `SPOTLIGHT_MESSAGE`: Spotlight	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 `true`: First page `false`: Not the first page
last	`Boolean`	Whether it's the last page `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	`Enum`	Message ad type `BROADCAST`: Regular message ad `MULTI_BROADCAST`: Optimized message ad
message	`SimpleMessage`	Message simple information Condition: Provided only if `messageAdType` is `BROADCAST`.
messages	`SimpleMessage[]`	List of simple information for each creative of the optimized message ad, provided in the order of the creatives Condition: Provided only if `messageAdType` is `MULTI_BROADCAST`.
name	`String`	Message name (Maximum: 150 characters), value with automatic generation rules applied when not entered during first creation
status	`Enum`	Message status `DRAFT`: Draft `READY`: Before sending `SENDING`: Sending `PAUSE`: Paused `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	`Enum`	Message type `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 `SPOTLIGHT_MESSAGE`: Spotlight
mainImageUrl	`String`	Message representative image Basic text, wide image, wide list, catalog, spotlight: Responds with `imageUrl` of the first `message.items` When the item has no image: Responds with `video.thumbnailUrl` of the first item, responds with `null` when there is no image or video Carousel commerce, when the intro carousel has an image: Responds with `message.introCarousel.imageUrl` Carousel commerce, carousel feed: Responds with `imageUrl` of the first `message.carousels`
mainTitle	`String`	Message representative text Basic text, wide image, wide list, premium video, catalog, spotlight: Responds with `message.messageTitle`, responds with `message.description` when there is no value Carousel commerce, when the intro carousel has a title: Responds with `message.introCarousel.messageTitle` Carousel commerce, carousel feed: Responds with `messageTitle` of the first `message.carousels`

SendingReservation

Name	Type	Description
targeting	`Targeting`	Targeting information
price	`Long`	Send unit price (Unit: won) `15`: No targeting applied `20`: Targeting applied
contractCount	`Long`	Purchase send count, message ad send reservation count
totalBudget	`Long`	Purchase amount, total amount for message ad send reservation
totalBudgetWithVAT	`Double`	Purchase amount including VAT, amount including VAT in `totalBudget`
date	`String`	Send start date and time, `yyyy-MM-dd HH:mm` format
trackId	`String`	Conversion tracking settings, pixel & SDK settings for providing message conversion metrics
sendRate	`Integer`	Distributed send setting `0` if distributed sending is not used Distributed cycle count: `100`, `500`, `1000`, `1500`, `2000`
pushAlarm	`Boolean`	Whether to send push alarm `true`: Send push alarm `false`: Do not send push alarm
immediateSend	`Boolean`	Whether to send immediately `true`: Send immediately `false`: Scheduled send

Targeting

Name	Type	Description
type	`Enum`	Targeting type `WHOLE`: All friends `DIRECT`: Direct setting `SMART`: Recommended friends Note: Values provided only when viewing an optimized message ad `OPTIMIZATION_WHOLE`: All friends optimization `OPTIMIZATION_DIRECT`: Direct setting optimization
optimizationTarget	`TargetingOptimization`	Optimization settings Condition: Provided only when viewing an optimized message ad.
devices	`Enum: DeviceType[]`	Device type `ANDROID`: Android `IOS`: iOS
businessTypes	`UfoBusinessType[]`	Business type targeting information
interests	`UfoInterest[]`	Interest targeting information
demographics	`Demographics`	Gender, age, and location targeting information
friendPeriod	`FriendPeriod`	Targeting information on the period when users added the Kakao Talk Channel as a friend
customs	`CustomTargeting[]`	Custom target information

Demographics

Name	Type	Description
genders	`String[]`	Gender `M`: Male `F`: Female
ages	`String[]`	Age group `15`: 15 to 19 `20`: 20 to 24 `25`: 25 to 29 `30`: 30 to 34 `35`: 35 to 39 `40`: 40 to 44 `45`: 45 to 49 `50`: 50 to 54 `55`: 55 to 59 `60`: 60 to 64 `65`: 65 to 69 `70`: Over 70
locationType	`Enum`	Location selection type `ALL`: All (domestic and overseas) `DOMESTIC`: Domestic only `AREA`: Area selection
depth1Locations	`String[]`	List of city/province location values
depth2Locations	`String[]`	List of city/county/district location values
depth3Locations	`String[]`	List of dong/eup/myeon location values

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": "BROADCAST",
        "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": "BROADCAST",
      "name": "Message_Ad_Test_Wide_Image",
      "status": "READY",
      "sendingReservation": {
        "targeting": {
          "type": "DIRECT",
          "devices": [],
          "businessTypes": [],
          "interests": [],
          "demographics": {
            "genders": [],
            "ages": [],
            "locationType": "ALL",
            "depth1Locations": [],
            "depth2Locations": [],
            "depth3Locations": []
          },
          "customs": []
        },
        "date": "2024-01-15 16:37"
      },
      "metrics": null,
      "createdDate": "2024-01-15 16:37:32",
      "lastModifiedDate": "2024-01-15 16:37:32",
      "message": {
        "type": "WIDE_MESSAGE",
        "mainTitle": "Promotional Text",
        "mainImageUrl": "https://t1.kakaocdn.net/b2/creative/56493/72750c9573241f3409d6f8e44cd66ac8.jpg"
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "empty": false,
      "sorted": true,
      "unsorted": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "size": 10,
  "number": 0,
  "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
  },
  "numberOfElements": 1,
  "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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns detailed information about an individual message ad.

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

Request

Header

Name	Description	Required
Authorization	Authorization method, authenticate with Business token `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account ID `adAccountId: ${AD_ACCOUNT_ID}`	O
channel-profile-id	Kakao Talk Channel profile ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	Request data type `Content-Type: application/json`	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	`Enum`	Message ad type `BROADCAST`: Regular message ad `MULTI_BROADCAST`: Optimized message ad
name	`String`	Message name (Maximum: 150 characters), value with automatic generation rules applied when not entered during first creation
message	`ResponseMessage` or `ResponseMultiMessage`	Message information Regular message ad: `ResponseMessage` format Optimized message ad: `ResponseMultiMessage` format, creative information included in `message.messages` Note: `messageAdId` and `name` are omitted. You can check whether the ad requires age verification with the top-level `ageVerification`.
sendingReservation	`SendingReservation`	Message send reservation information
status	`Enum`	Message status `DRAFT`: Draft `READY`: Before sending `SENDING`: Sending `PAUSE`: Paused `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",
    "items": [
      {
        "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/72750c9573241f3409d6f8e44cd66ac8.jpg",
        "landing": {
          "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,
    "description": "Promotional Text"
  },
  "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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Deletes a message ad.

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

Request

Header

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

Path variable

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

Response

No response body

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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns detailed message information.

A regular message ad is returned in the format of the response body, and an optimized message ad is returned in the ResponseMultiMessage format.

Request

Header

Name	Description	Required
Authorization	Authorization method, authenticate with Business token `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account ID `adAccountId: ${AD_ACCOUNT_ID}`	O
channel-profile-id	Kakao Talk Channel profile ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	Request data type `Content-Type: application/json`	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: 150 characters), value with automatic generation rules applied when not entered during first creation
type	`Enum`	Message type `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 `SPOTLIGHT_MESSAGE`: Spotlight
messageTitle	`String`	Message title Condition: Provided only if the message type uses a title.
description	`String`	Promotional text Condition: Provided only if the message type uses promotional text.
items	`Item[]`	List information
buttons	`Button[]`	Button information
couponBook	`CouponBook`	Coupon information
introCarousel	`IntroCarousel`	Intro information
carousels	`Carousel[]`	Carousel information
moreButton	`Landing`	Carousel More button landing information Condition: Provided only if a value exists.
buttonTitle	`String`	Spotlight message button name
landingUrl	`String`	Spotlight message landing URL
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",
  "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,
  "description": "Promotional Text"
}

Copy message

Basic information

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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

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

A regular message ad is returned in the format of the response body, and an optimized message ad is returned in the ResponseMultiMessage format.

Request

Header

Name	Description	Required
Authorization	Authorization method, authenticate with Business token `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account ID `adAccountId: ${AD_ACCOUNT_ID}`	O
channel-profile-id	Kakao Talk Channel profile ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	Request data type `Content-Type: application/json`	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: 150 characters), value with automatic generation rules applied when not entered during first creation
type	`Enum`	Message type `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 `SPOTLIGHT_MESSAGE`: Spotlight
messageTitle	`String`	Message title Condition: Provided only if the message type uses a title.
description	`String`	Promotional text Condition: Provided only if the message type uses promotional text.
items	`Item[]`	Item information
buttons	`Button[]`	Button information
couponBook	`CouponBook`	Coupon information
introCarousel	`IntroCarousel`	Intro information
carousels	`Carousel[]`	Carousel information
moreButton	`Landing`	Carousel More button landing information Condition: Provided only if a value exists.
buttonTitle	`String`	Spotlight message button name
landingUrl	`String`	Spotlight message landing URL
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",
  "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,
  "description": "Promotional Text Changed"
}

View message ad report

Basic information

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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns reports for messages.

Report conditions

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 datePreset or start, end. If requested in duplicate, data under start, end conditions will be retrieved.

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

Request

Header

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

Body

Name	Type	Description	Required
messageAdIds	`String[]`	List of message ad numbers (Maximum: 100)	X
datePreset	`Enum: DatePreset`	Report lookup period (Default: `TODAY`)	X
start	`String`	Report lookup period start date, `YYYY-MM-DD` format Start date can be set up to lookup date Important: Required when `end` is included Note: If both `start` and `end` are omitted, lookup based on `datePreset`	X
end	`String`	Report lookup period end date, `YYYY-MM-DD` format End date can be set from start date to lookup date Important: Required when `start` is included	X
dimension	`Enum: Dimension`	Report lookup criteria, criteria by which data will be grouped when looking up reports	O
metricsGroup	`Enum: MetricsGroup[]`	Report metric groups	O

Enum: Dimension

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

Enum: MetricsGroup

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

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	`JSON`	Report criteria and values. Note: For the keys and values included by the report criteria, refer to Dimension.
metrics	`JSON`	Report metrics and values Note: Refer to Enum: MetricsGroup for the metric codes.

Dimension

Name	Description	Value
message_ad_id	Message ad number Identification number assigned when first created	Actual message ad number (`messageAdId`)
message_type	Message type Basic text Wide list Wide image Carousel commerce Carousel feed Catalog Spotlight	BASIC_TEXT_MESSAGE WIDE_LIST_MESSAGE WIDE_MESSAGE CAROUSEL_COMMERCE_MESSAGE CAROUSEL_FEED_MESSAGE CATALOG_MESSAGE SPOTLIGHT_MESSAGE
device_type	Device total PC Android iOS Others	total PC Android iOS N/A
hour	Hour total 00:00 to 00:59 01:00 to 01:59 02:00 to 02:59 03:00 to 03:59 04:00 to 04:59 05:00 to 05:59 06:00 to 06:59 07:00 to 07:59 08:00 to 08:59 09:00 to 09:59 10:00 to 10:59 11:00 to 11:59 12:00 to 12:59 13:00 to 13:59 14:00 to 14:59 15:00 to 15:59 16:00 to 16:59 17:00 to 17:59 18:00 to 18:59 19:00 to 19:59 20:00 to 20:59 21:00 to 21:59 22:00 to 22:59 23:00 to 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

Enum: MetricsGroup

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

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

View list of channel videos

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/talk-channel-videos`	Business token

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns a list of Kakao Talk Channel videos that can be used in a Message creative.

Videos are returned from the Kakao Talk Channel determined by the authentication information.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O

Query parameter

Name	Type	Description	Required
page	`Integer`	Page number to retrieve. Starts from 0 (Default: 0)	X
size	`Integer`	Number of videos per page. (Default: 20, Maximum: 1000)	X

Response

Body

Name	Type	Description
items	`TalkChannelVideo[]`	List of channel videos.
totalElements	`Long`	Total number of videos available for retrieval.

TalkChannelVideo

Name	Type	Description
url	`String`	Video URL.
title	`String`	Video title.
talkChannelProfileId	`String`	Kakao Talk Channel profile ID.
vid	`String`	Video VID.
mediaId	`Long`	Video media ID.
status	`String`	Video status.
duration	`Integer`	Video playback duration.
width	`Integer`	Video width.
height	`Integer`	Video height.
playCount	`Integer`	Number of video plays.
autoThumbnail	`TalkChannelVideoThumbnail`	Auto-generated thumbnail information.
uploadThumbnail	`TalkChannelVideoThumbnail`	User-uploaded thumbnail information.

TalkChannelVideoThumbnail

Name	Type	Description
url	`String`	Thumbnail URL.
fileName	`String`	Thumbnail file name.
width	`Integer`	Thumbnail width.
height	`Integer`	Thumbnail height.
fileSize	`Long`	Thumbnail file size.
mineType	`String`	Thumbnail MIME type.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/talk-channel-videos?page=0&size=20" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "items": [
    {
      "url": "https://pf.kakao.com/_Xxju/vod/svbjfjfy6nip184ci0zq1maf3",
      "title": "Test video",
      "talkChannelProfileId": "_Xxju",
      "vid": "svbjfjfy6nip184ci0zq1maf3",
      "mediaId": 408,
      "status": "PUBLIC",
      "duration": 15,
      "width": 1920,
      "height": 1080,
      "playCount": 0,
      "autoThumbnail": {
        "url": "https://thumb.kakaocdn.net/dna/kamp-sbox/.../thumb.jpg",
        "width": 0,
        "height": 0,
        "fileSize": 0
      }
    }
  ],
  "totalElements": 1
}

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

Message ad management

View list of message ads

Basic information

Request

Header

Query parameter

Body

Filter

Response

Body

Content

SimpleMessage

SendingReservation

Targeting

Demographics

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

Response

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

Report conditions

Request

Header

Body

Enum: Dimension

Enum: MetricsGroup

Response

Body

Data

Dimension