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 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 Fixed to `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 `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	`String`	Message ad type Fixed to `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	`Enum`	Message status `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

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

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 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	`Enum: DeviceType[]`	Device type `ANDROID`: Android `IOS`: iOS
targeting	`Targeting`	Targeting information
price	`Long`	Send unit price (Unit: won) `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 HH:mm` format

Targeting

Name	Type	Description
genderType	`Enum`	Gender overall selection type `ALL`: All selected `NOT_ALL`: Partial selection
genders	`String[]`	Gender `M`: Male `F`: Female
ageType	`Enum`	Age overall selection type `ALL`: All selected `NOT_ALL`: Partial selection
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
locationType	`Enum`	Location selection type `ALL`: All (domestic and 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

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	`String`	Message ad type Fixed to `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	`Enum`	Message status `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

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

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.

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: 50 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
title	`String`	Promotional text
items	`Item[]`	List information
buttons	`Button[]`	Button information
couponBook	`CouponBook[]`	Coupon information
introCarousel	`IntroCarousel`	Intro information
carousels	`Carousel[]`	Carousel information
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",
  "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

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.

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: 50 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
title	`String`	Promotional text
items	`Item[]`	Item information
buttons	`Button[]`	Button information
couponBook	`CouponBook[]`	Coupon information
introCarousel	`IntroCarousel`	Intro information
carousels	`Carousel[]`	Carousel information
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",
  "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

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_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 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	`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 Button 2 clicks `msg_click_carousel_share2`: Carousel 2 Button 2 clicks `msg_click_carousel_share3`: Carousel 3 Button 2 clicks `msg_click_carousel_share4`: Carousel 4 Button 2 clicks `msg_click_carousel_share5`: Carousel 5 Button 2 clicks `msg_click_carousel_share6`: Carousel 6 Button 2 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

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 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 Button 2 clicks `msg_click_carousel_share2`: Carousel 2 Button 2 clicks `msg_click_carousel_share3`: Carousel 3 Button 2 clicks `msg_click_carousel_share4`: Carousel 4 Button 2 clicks `msg_click_carousel_share5`: Carousel 5 Button 2 clicks `msg_click_carousel_share6`: Carousel 6 Button 2 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

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	`Long`	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://sandbox-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",
        "fileName": "thumb.jpg",
        "width": 1920,
        "height": 1080,
        "fileSize": 102400,
        "mineType": "image/jpeg"
      },
      "uploadThumbnail": null
    }
  ],
  "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 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

Report conditions

Request

Header

Body

Enum: Dimension

Enum: MetricsGroup

Response

Body

Data

Dimension

Enum: MetricsGroup

Sample