This document describes how to use the Message ad operation API for Kakao Moment message ads.
Before you begin
Message ads have different components depending on the message type, so the available parameters differ from each other. For detailed information, refer to Message type components.
Available message types
Message ads can send the following types of messages. For detailed information on each message type, refer to the Kakao Business Channel Message Guide.
Name
Message type
Basic Text
BASIC_TEXT_MESSAGE
Wide Image
WIDE_MESSAGE
Wide List
WIDE_LIST_MESSAGE
Carousel Commerce
CAROUSEL_COMMERCE_MESSAGE
Carousel Feed
CAROUSEL_FEED_MESSAGE
Premium Video
PREMIUM_VIDEO_MESSAGE
Catalog
CATALOG_MESSAGE
Spotlight
SPOTLIGHT_MESSAGE
Premium Video (PREMIUM_VIDEO_MESSAGE) message type cannot be sent via the Message ad API.
Message type components
This section provides information about the field path, specifications, and required status for each message type component.
When separate URL landing is needed for PC KakaoTalk, carousel PC landing URL can be additionally registered.
O
Price Information message.carousels.priceAmount
When currency information is Korean Won (₩) or Japanese Yen (￥), only integers with 8 digits or less (0 to 99999999) can be entered.
When currency information is Dollar ($) or Euro (€), integers with 8 digits or less or numbers with up to 2 decimal places (0 to 99999999.99) can be entered.
O
Currency Information message.carousels.priceCurrencyCode
Sets the currency unit for price information.
Can be applied as one of Korean Won (₩), Dollar ($), Japanese Yen (￥), Euro (€).
O
Discounted Price Information message.carousels.discountedPriceAmount
Must enter a value that differs by 1% or more from the price information value.
Discount rate: Automatically calculated and applied with decimal places truncated when discounted price information is entered (1% to 100%).
X
Button1 message.carousels
Cannot be set by user, automatically generated as a button with the following attributes.
Button name: Purchase.
Landing: Connects to registered carousel landing URL.
O
Button2 message.shareFlag
When share flag (message.shareFlag) is set, operates as Share button for all carousels (1 to 6). Button name and landing setting not available.
X
More message.moreButton
Connects to registered landing URL.
X
Carousel feed (CAROUSEL_FEED_MESSAGE)
Carousel1 and Carousel2 required, Carousel3 to Carousel6 optional.
Component and Field Path
Specification
Required
Title message.carousels.messageTitle
Character count: Maximum 20 characters, links cannot be entered, line breaks not allowed.
Character count: Maximum 180 characters, links cannot be entered, line breaks: Maximum 10.
Landing: Connects to Button1 landing URL.
O
Button1 message.carousels.buttons
Button name: Maximum 8 characters including spaces.
Landing: Connects to registered button landing URL.
Required when this element is included: Button name, button mobile landing URL.
O
Button2 message.carousels.buttons
Button name: Maximum 8 characters including spaces.
Landing: Connects to registered button landing URL.
Required when this element is included: Button name, button mobile landing URL.
Cannot be set together when share (message.carousels.shareFlag) is set to true.
X
Share Setting message.carousels.shareFlag
Whether to use share
true: Use share
false: Do not use share
Cannot be set together with Button2.
When share is set, button name and landing setting not available.
X
Coupon message.carousels.couponBook
Landing: Connects to registered coupon landing URL.
Required when this element is included: Coupon type, coupon title, coupon detailed description, coupon mobile landing URL.
X
More message.moreButton
Connects to registered landing URL.
X
Premium video (PREMIUM_VIDEO_MESSAGE)
Component and Field Path
Specification
Promotional Video message.items.video.url
Promotional video URL registered by user.
Promotional Video Auto Thumbnail message.items.video.autoThumbnailUrl
Automatically generated promotional video thumbnail. Thumbnail is set when uploaded thumbnail is not available.
Promotional Video Upload Thumbnail message.items.video.uploadThumbnailUrl
Promotional video upload thumbnail registered by user.
Title message.messageTitle
Character count: Maximum 20 characters, links cannot be entered, line breaks not allowed.
Promotional Text message.description
Character count: Maximum 76 characters, links cannot be entered, line breaks: Maximum 5.
Button message.buttons
Button name: Maximum 8 characters including spaces.
Landing: Connects to registered button landing URL.
Required when this element is included: Button name, button mobile landing URL.
Coupon message.couponBook
Landing: Connects to registered coupon landing URL.
Required when this element is included: Coupon type, coupon title, coupon detailed description, coupon mobile landing URL.
* Premium video creation is not possible, but premium videos created in [Kakao Moment] > [Message] > [Create Message] in Kakao Business can be retrieved.
Catalog (CATALOG_MESSAGE)
Item1 to Item3 required, Item4 to Item7 optional.
Component and Field Path
Specification
Required
Title message.messageTitle
Character count: Maximum 36 characters, links cannot be entered, line breaks not allowed.
O
Promotional Text message.description
Character count: Maximum 36 characters, links cannot be entered.
Can be applied as one of Korean Won (₩), Dollar ($), Japanese Yen (￥), Euro (€).
O
Item Price message.items.priceAmount
Field available only for catalog item discount rate highlight type (DISCOUNT_RATE_HIGHLIGHT) and price highlight type (PRICE_HIGHLIGHT).
When currency information is Korean Won (₩) or Japanese Yen (￥), only integers with 8 digits or less (0 to 99999999) can be entered.
When currency information is Dollar ($) or Euro (€), integers with 8 digits or less or numbers with up to 2 decimal places (0 to 99999999.99) can be entered.
O
Item Price Name message.items.priceName
Field available only for catalog item discount rate highlight type (DISCOUNT_RATE_HIGHLIGHT) and price highlight type (PRICE_HIGHLIGHT).
Character count: Maximum 4 characters, links cannot be entered, line breaks not allowed.
Ratio: Width: Height ratio less than 1:2.5 (Recommended: 2:1, 1:1, 4:3)
Encoding
If URLs contain special characters or Korean text that are not encoded in UTF-8, ads may not land properly in the Kakao Talk in-app browser on iOS devices. Below are examples of special characters that may cause landing errors.
%
|
"
Additionally, deep link (Deeplink) format URLs that require parameter and macro substitution are not officially supported.
Saves the message ad content that will be sent from the Kakao Talk Channel.
The availability and required status of parameters differ depending on the message type (type). For related detailed information, refer to Message type components.
This API is limited to 1 request per second per user account and ad account.
Request
Header
Name
Description
Required
Authorization
Authorization method, authenticate with Business token Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
When using a Kakao Talk Channel video in Basic Text, Wide Image, or Wide List Item, send the request with only video.mediaId instead of imageUrl. (Reference: Body when requesting a Kakao Talk Channel video)
When using a Kakao Talk Channel video in Basic Text, Wide Image, or Wide List Item, send the request with only video.mediaId instead of imageUrl. (Reference: Body when requesting a Kakao Talk Channel video)
The send start time can be set in 1-minute intervals from 5 minutes after the reservation time. If it is set within 1 hour, sending may be delayed until target population generation is complete, depending on the target population size.
The send start time can be set from 08:00 to 20:50. Messages that have not been sent after 20:55 are sent after 08:00 the next day.
Send cost
Non-target: Messages without targeting information set, 15 won.
Target: Messages with targeting information set, 20 won. However, 15 won when only the Domestic location type or devices are set.
Request
Header
Name
Description
Required
Authorization
Authorization method, authenticate with Business token Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Targeting Gender, age, location targeting can be set
O
date
String
Send start date and time, in yyyy-MM-dd HH:mm format
Important: Required if immediateSend (whether to send immediately) is false (scheduled send). Cannot be passed if immediateSend is true (send immediately).
Distributed send setting Set to 0 if you don't want distributed sending If you want distributed sending, enter the distributed cycle count: 100, 500, 1000, 1500, 2000
Distributed send setting Set to 0 if you don't want distributed sending If you want distributed sending, enter the distributed cycle count: 100, 500, 1000, 1500, 2000
Distributed send setting Set to 0 if you don't want distributed sending If you want distributed sending, enter the distributed cycle count: 100, 500, 1000, 1500, 2000
Targeting Gender, age, location targeting can be set
O
date
String
Send start date and time, in yyyy-MM-dd HH:mm format
Important: Required if immediateSend (whether to send immediately) is false (scheduled send). Cannot be passed if immediateSend is true (send immediately).
X
immediateSend
Boolean
Whether to send immediately
true: Send immediately
false: Scheduled send (Default)
X
pushAlarm
Boolean
Whether to send push alarm
true: Send push alarm (Default)
false: Do not send push alarm
X
trackId
String
Conversion tracking settings, pixel & SDK settings for providing message conversion metrics If omitted, conversion tracking is not set.
X
sendRate
Integer
Distributed send setting (Default: 0) Set to 0 if you don't want distributed sending If you want distributed sending, enter the distributed cycle count: 100, 500, 1000, 1500, 2000
X
Response
Body
Name
Type
Description
messageAdId
String
Message ad number Identification number assigned when first created
Distributed send setting Set to 0 if you don't want distributed sending If you want distributed sending, enter the distributed cycle count: 100, 500, 1000, 1500, 2000
Sub-location data Not provided when query parameter codes is used
deprecated
Boolean
Whether the location information is deleted, true means deleted location and is only included in the response when codes is included in the query parameter
Children
Name
Type
Description
id
String
Location value
name
String
Location name
children
Children[]
Sub-location data
deprecated
Boolean
Whether the location information is deleted, true means deleted location and is only included in the response when codes is included in the query parameter
Returns the available audience and price for sending.
This API does not reflect the existing messageAdId settings or affect existing send reservations; it returns the audience and price based only on the targeting conditions in the request.
Request
Header
Name
Description
Required
Authorization
Authorization method, authenticate with Business token Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
List of creative information to create (Minimum: 2 items, Maximum: 5 items) For parameters and specifications by message type, refer to Message type components.
Modifies the name and creative content of an optimized message ad.
Notes
The number of creatives cannot be changed after creation, even in draft status.
After the send is registered, the message type and age verification of the creative at each position cannot be changed.
Modification is available in the Draft, Scheduled, and Paused statuses, and the conditions for each status, such as whether the send is registered and the modifiable time, must also be met.
Request
Header
Name
Description
Required
Authorization
Authorization method, authenticate with Business token Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Position of the creative to send as a test in the messages array of the save or edit request (Minimum: 0) (Example: 0 is the first creative, 1 is the second creative)
Important: Pass a value less than the number of items in messages.
O
phoneNumbers
String[]
List of target phone numbers (Example: ["010-0000-0000"])
Important: Empty arrays and empty strings cannot be passed.
Send start date and time, in yyyy-MM-dd HH:mm format
Important: Required if immediateSend (whether to send immediately) is false (scheduled send) or omitted. Cannot be passed if immediateSend is true (send immediately).
Modifies the send time, targeting, and message optimization settings of an optimized message ad.
Notes
Modification is available until 5 minutes before the send start time. Reservations in the Sending or Finished status, or reservations stopped after sending has started, cannot be modified.
Pass the entire settings to modify in targeting. Omitting optional parameters does not keep the existing values, so you must also pass the settings to keep.
Send start date and time, in yyyy-MM-dd HH:mm format
Important: Required if immediateSend (whether to send immediately) is false (scheduled send) or omitted. Cannot be passed if immediateSend is true (send immediately).
Retrieves the available audience, unit price, and expected purchase amount for sending an optimized message ad.
Notes
The values are calculated with the requested targeting conditions, and the existing send reservation is not changed.
Pass the messageAdId of an optimized message ad as the path variable.
targeting uses the same request type as the Create scheduled optimized message ad API, and the optimizationTarget method and sendRatios format conditions also apply.
The result is calculated with the conditions at the time of the request and is verified again when the send is reserved.
Request
Header
Name
Description
Required
Authorization
Authorization method, authenticate with Business token Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
