Kakao Moment

Message ad operation

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.

Basic text (BASIC_TEXT_MESSAGE)

Component and Field Path	Specification	Required
Promotional Area `message.items.imageUrl`	Images that comply with Promotional area common specifications can be applied. Landing: Connects to Button1 element landing URL (separate setting not available).	X
Title `message.messageTitle`	Character count: Maximum 16 characters Links cannot be entered. Line breaks not allowed.	X
Promotional Text `message.description`	Character count: Maximum 1,300 characters regardless of whether promotional elements are included, links cannot be entered. Line breaks: Maximum 99. Landing: Not available.	O
Button1 `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.	X
Button2 `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.	X
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.	X

Wide image (WIDE_MESSAGE)

Component and Field Path	Specification	Required
Promotional Area `message.items.imageUrl`	Images that comply with Promotional area common specifications can be applied. Landing: Connects to registered item landing URL.	O
Title `message.messageTitle`	Character count: Maximum 20 characters Links cannot be entered. Line breaks not allowed.	X
Promotional Text `message.description`	Character count: Maximum 76 characters, links cannot be entered. Line breaks: Maximum 5. Landing: Connects to registered item landing URL.	O
Creative Landing `message.items.landing`	Landing connected when the promotional area is clicked. Landing can be registered.	O
Button1 `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.	X
Button2 `message.buttons`	When share flag (`message.shareFlag`) is set, operates as `Share` button, button name and landing setting not available. 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.	X
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.	X

Wide list (WIDE_LIST_MESSAGE)

Component and Field Path	Specification	Required
Promotional Area `message.items.imageUrl`	Images that comply with Promotional area common specifications can be applied. Landing: Connects to registered item landing URL. Required status: List1 to List3 required, List4 and List5 optional.	X
Title `message.messageTitle`	Character count: Maximum 20 characters, links cannot be entered, line breaks not allowed. Landing: Connects to registered item landing URL.	O
Item Promotional Text `message.items.description`	List1 character count: Maximum 25 characters, links cannot be entered, line breaks not allowed. List2 to List5 character count: Maximum 30 characters, links cannot be entered, line breaks not allowed. Landing: Connects to registered item landing URL. Required status: List2 and List3 required, List1, List4, and List5 optional.	X
Creative Landing `message.items.landing`	Landing connected when the promotional area is clicked. Landing can be registered.	O
Button1 `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.	X
Button2 `message.buttons`	When share flag (`message.shareFlag`) is set, operates as `Share` button.	X
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.	X

Carousel commerce (CAROUSEL_COMMERCE_MESSAGE)

Divided into intro and carousel (1 to 6).
When intro is included, carousel1 is required; when not included, carousel1 and carousel2 are required.

Intro

Component and Field Path	Specification	Required
Title `message.introCarousel.messageTitle`	Character count: Maximum 20 characters, links cannot be entered, line breaks not allowed.	O
Promotional Image `message.introCarousel.imageUrl`	Only images that comply with Promotional area common specifications can be applied. Recommended size: 800x400 pixels (2:1 ratio), 800x800 pixels (1:1 ratio), 800x600 pixels (4:3 ratio). Landing: Connects to registered intro landing URL.	O
Promotional Text `message.introCarousel.description`	Character count: Maximum 50 characters, links cannot be entered, line breaks not allowed. Landing: Connects to registered intro URL.	O
Intro Landing URL `message.introCarousel.landing`	When separate URL landing is needed for PC KakaoTalk, intro PC landing URL can be additionally registered.	X

Carousel

Component and Field Path	Specification	Required
Title `message.carousels.messageTitle`	Character count: Maximum 25 characters, links cannot be entered, line breaks not allowed.	O
Promotional Image `message.carousels.imageUrl`	Only images that comply with Promotional area common specifications can be applied. Recommended size: 800x400 pixels (2:1 ratio), 800x800 pixels (1:1 ratio), 800x600 pixels (4:3 ratio). Landing: Connects to Button1 landing URL.	O
Promotional Text `message.carousels.description`	Character count: Maximum 50 characters, links cannot be entered. Line breaks: Maximum 2. Landing: Connects to Button1 landing URL.	O
Carousel Landing URL `message.carousels.landing`	Applied to Button1 landing URL. 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.buttons`	When share flag (`message.shareFlag`) is set, operates as `Share` button for all carousels (1 to 6). Button name and landing setting not available. 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.	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. Landing: Connects to Button1 landing URL.	O
Promotional Image `message.carousels.imageUrl`	Only images that comply with Promotional area common specifications can be applied. Carousel1 to carousel6 must all register images with the same ratio. Recommended size: 800x400 pixels (2:1 ratio), 800x600 pixels (4:3 ratio). Landing: Connects to Button1 landing URL.	O
Promotional Text `message.carousels.description`	Character count: Maximum 180 characters, links cannot be entered, line breaks: Maximum 10. Landing: Connects to Button1 landing URL.	O
Button1 `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.	O
Button2 `message.buttons`	When share flag (`message.shareFlag`) is set, operates as share button for Button2. Button name and landing setting not available. 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.	X
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.	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.catalog.messageTitle`	Character count: Maximum 36 characters, links cannot be entered, line breaks not allowed.	O
Promotional Text `message.catalog.description`	Character count: Maximum 36 characters, links cannot be entered. Line breaks: Maximum 1.	X
Item Promotional Area `message.catalog.imageUrl`	Only images that comply with Promotional area common specifications can be applied. Recommended size: 800x400 pixels (2:1 ratio), 800x600 pixels (4:3 ratio). Landing: Connects to registered item landing URL. Required status: Item1 to Item3 required, Item4 to Item7 optional.	X
Item Title `message.items.title`	Character count: Maximum 20 characters, links cannot be entered, line breaks not allowed. Required: Item1 to Item3 required, Item4 to Item7 optional.	X
Item Promotional Text `message.item.description`	Field available only for catalog item content type (CONTENTS). Character count: Maximum 22 characters, links cannot be entered, line breaks not allowed. Landing: Connects to Button1 landing URL. Required status: Item1 to Item3 required, Item4 to Item7 optional.	X
Item Price Currency Code `message.items.priceCurrencyCode`	Sets the currency unit for price information. 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.	X
Item Discounted Price `message.items.discountedPriceAmount`	Field available only for catalog item discount rate highlight type (DISCOUNT_RATE_HIGHLIGHT) and price highlight type (PRICE_HIGHLIGHT). 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
Item Discounted Price Name `message.items.discountedPriceName`	Field available only for catalog item discount rate highlight type (DISCOUNT_RATE_HIGHLIGHT) and price highlight type (PRICE_HIGHLIGHT). Character count: Maximum 5 characters, links cannot be entered, line breaks not allowed. When highlighted price is entered, highlighted price name and regular price must be entered.	X
Price Label `message.pricelabel.title`	Character count: Maximum 4 characters for regular price, maximum 5 characters for highlighted price, links cannot be entered.	O
Creative Landing `message.items.landing`	Landing connected when the catalog item is selected. Landing can be registered.	O
Button1 `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.	X
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.	X

Spotlight (SPOTLIGHT_MESSAGE)

Component and Field Path	Specification	Required
Title `message.messageTitle`	Character count: Maximum 20 characters, links cannot be entered, line breaks not allowed.	O
Promotional Text `message.description`	Character count: Maximum 45 characters, links cannot be entered. Line breaks: Maximum 1.	O
Button Title `message.buttonTitle`	Character count: Maximum 8 characters.	O
Landing URL `message.landingUrl`	App links cannot be used. Links to services within Kakao Talk cannot be used.	O
Item Promotional Area `message.items.imageUrl`	Only images that comply with Promotional area common specifications can be applied. Recommended size: 800x400 pixels (2:1 ratio), 800x600 pixels (4:3 ratio). Landing: Connects to registered item landing URL. Required status: Item1 to Item3 required, Item4 to Item7 optional.	X

Promotional area common specifications

Image
- Format: JPG, JPEG, PNG
- Size: Width greater than 80 pixels (Recommended: 800x400, 800x800, 800x600 pixels)
- Capacity: 10MB or less
- 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.

Save message ad

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/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

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}`	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
name	`String`	Message name (Maximum: 50 characters).	X
ageVerification	`Boolean`	Whether age verification is required for the message `true`: Age verification required message `false`: Regular message (Default)	X
message	`Message`	Message information to create	O

Response

Body

Name	Type	Description
-	`ResponseMessage`	Message information

Sample

Request

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)

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Message_Ad_Test_Basic_Text",
  "ageVerification": false,
  "message": {
    "type": "BASIC_TEXT_MESSAGE",
    "description": "Promotional Text",
    "shareFlag": true,
    "adFlag": true,
    "items": [
      {
        "imageUrl": "https://partner.com/img/message/001.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": {
      "couponBookTitleType": "UPGRADE",
      "couponBookTitle": "Coupon Title",
      "title": "Coupon Detailed Description",
      "pcLandingUrl": "https://daum.net",
      "mobileLandingUrl": "https://daum.net"
    }
  }
}'

Request: Body when requesting a Kakao Talk Channel video

{
  "name": "Message_Ad_Test_Wide_Image_Video",
  "ageVerification": false,
  "message": {
    "type": "WIDE_MESSAGE",
    "messageTitle": "Wide Image Title",
    "description": "Wide Image Promotional Text",
    "adFlag": true,
    "items": [
      {
        "video": {
          "mediaId": 408
        }
      }
    ],
    "buttons": [
      {
        "title": "Button1",
        "pcLandingUrl": "https://daum.net/1",
        "mobileLandingUrl": "https://daum.net/1"
      }
    ]
  }
}

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1402922220759433217",
  "name": "Message_Ad_Test_Basic_Text",
  "type": "BASIC_TEXT_MESSAGE",
  "description": "Promotional Text",
  "items": [
    {
      "imageUrl": "https://partner.com/img/message/001.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": true,
  "shareFlag": true
}

Edit message

Basic information

Method	URL	Authorization
`PATCH`	`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

Modifies the message ad content that will be sent from the Kakao Talk Channel.

Usage policy

The message modification policy is as follows:

Must be in the same format as the existing message.
After 5 minutes before the scheduled send time, only the message name can be modified. Other parameters except the name are ignored.
Images and text that do not match the message execution guide cannot be used.

For parameter conditions by message type, refer to Message type components.

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

Body

Name	Type	Description	Required
name	`String`	Message name (Maximum: 50 characters).	X
ageVerification	`Boolean`	Whether age verification is required for the message `true`: Age verification required message `false`: Regular message (Default)	X
message	`Message`	Message information to create	O

Response

Body

Name	Type	Description
-	`ResponseMessage`	Message information

Sample

Request

curl -X PATCH "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" \
  -d '{
    "name": "MessageAd_Test_Basic_Text",
    "ageVerification": false,
    "message": {
        "type": "BASIC_TEXT_MESSAGE",
        "title": "Promotional text changed",
        "shareFlag": true,
        "adFlag": false,
        "items": [
            {
                "imageUrl": "https://partner.com/img/message/001.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": {
            "couponBookTitleType": "UPGRADE",
            "couponBookTitle": "Coupon Title",
            "title": "Coupon Detail Description",
            "pcLandingUrl": "https://daum.net",
            "mobileLandingUrl": "https://daum.net"
        }
    }
}'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1195179794616258561",
  "name": "MessageAd_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 Detail Description",
    "pcLandingUrl": "https://daum.net",
    "mobileLandingUrl": "https://daum.net",
    "couponBookTitle": "Coupon Title",
    "couponBookTitleType": "UPGRADE"
  },
  "ageVerification": false,
  "adFlag": false,
  "shareFlag": true
}

Send test message ad

Basic information

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

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

Sends a test message.

Conditions for use

Can only be sent to phone numbers that are channel friends.
Adds [Test Send] to the promotional text area.

Rate limit

This API is limited to one request every 30 seconds per user account and ad account.

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

Body

Name	Type	Description	Required
phoneNumbers	`String`	Target phone number for sending, in `010-1234-5678` format	O

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/send-test" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "phoneNumbers": ["014-0042-4549"]
    }'

Response

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

Create scheduled message ad

Basic information

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

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

Sets the message send start time and send target.

Send time conditions

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 device/targeting information set, 15 won.
Target: Messages with at least one device or targeting setting, 20 won. However, 15 won when only the Domestic location type is set.

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

Body

Name	Type	Description	Required
targeting	`Targeting`	Targeting Gender, age, location targeting can be set	O
date	`String`	Send start date and time, in `yyyy-MM-dd HH:mm` format	O
immediateSend	`Boolean`	Whether to send immediately `true`: Send immediately `false`: Scheduled send	X
pushAlarm	`Boolean`	Whether to send push alarm `true`: Send push alarm `false`: Do not send push alarm	X
trackId	`String`	Conversion tracking settings, pixel & SDK settings for providing message conversion metrics	X
sendRate	`Integer`	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	X

Targeting

Name	Type	Description	Required
type	`Enum`	Targeting type `WHOLE`: All friends `SMART`: Recommended friends `DIRECT`: Direct setting	O
devices	`Enum: DeviceType[]`	Device selection type. `ANDROID`: Android `IOS`: iOS	X
demographics	`Demographics[]`	Gender, age, location information	X
customs	`CustomTargeting[]`	Custom target specification	X
friendPeriod	`FriendPeriod[]`	Friend period setting Send only to users who have been channel friends for the set period	X
ufoInterests	`UfoInterest[]`	Custom target > Kakao data > Category > Interests Refer to Custom target category type lookup Note: View only	X
ufoBusinessTypes	`UfoBusinessType[]`	Custom target > Kakao data > Category > Business type Refer to Custom target category type lookup Note: View only	X

Response

Body

Name	Type	Description
messageAdId	`String`	Message ad number, identification number assigned when first created
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, in `yyyy-MM-dd HH:mm` format

View scheduled message ads

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation`	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 the message ad send reservation.

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
deviceTypes	`Enum: DeviceType[]`	Device type (all selected when empty array is specified) `ANDROID`: Android `IOS`: iOS
targeting	`Targeting`	Targeting Gender, age, location targeting can be set
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, in `yyyy-MM-dd HH:mm` format

Edit scheduled message ad

Basic information

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

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

Modifies the message send start time and send target.

Send reservation modification is possible until 5 minutes before the send start time.

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

Body

Name	Type	Description	Required
deviceTypes	`Enum: DeviceType[]`	Device type (all selected when empty array is specified) `ANDROID`: Android `IOS`: iOS	O
targeting	`Targeting`	Targeting Gender, age, location targeting can be set	O
date	`String`	Send start date and time, in `yyyy-MM-dd HH:mm` format	O

Response

Body

Name	Type	Description
messageAdId	`String`	Message ad number Identification number assigned when first created
deviceTypes	`Enum: DeviceType[]`	Device type (all selected when empty array is specified) `ANDROID`: Android `IOS`: iOS
targeting	`Targeting`	Targeting Gender, age, location targeting can be set
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, in `yyyy-MM-dd HH:mm` format

View targeting locations

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/sending-reservation/location`	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 for location settings used in message ad send reservations.

For the complete list, refer to the Administrative District Type Information CSV file (download).

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
codes	`String`	Location code Multiple location codes can be specified as comma-separated strings (Example: `A7000A001,Q20000025`)	X

Response

Body

Name	Type	Description
id	`String`	City/Province value
name	`String`	`depth1Name` of the city/province value
children	`Children[]`	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

Sample

Request

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

Request: Specify location codes

curl -v -G GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/sending-reservation/location" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d "codes=A7000A001,Q20000025"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": "A",
  "name": "Gangwon Special Self-Governing Province",
  "children": [
    {
      "id": "A7000",
      "name": "Gangneung-si",
      "children": [
        {
          "id": "A7000A001",
          "name": "Gangnam-dong"
        }
      ]
    }
    // ...
  ]
  // ...
}

Response: Specify location codes

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
  {
    "id": "A7000A001",
    "name": "Gangwon Special Self-Governing Province Gangneung-si Gangnam-dong",
    "deprecated": true
  },
  {
    "id": "Q20000025",
    "name": "Sejong Special Self-Governing City Sejong-si Haemil-dong",
    "deprecated": false
  }
]

View targeting audience and price

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation/targeting-price`	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 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}`	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

Body

Name	Type	Description	Required
deviceTypes	`Enum: DeviceType[]`	Device type (all selected when empty array is specified) `ANDROID`: Android `IOS`: iOS	X
targeting	`Targeting`	Targeting.	O

Response

Body

Name	Type	Description
messageAdId	`String`	Message ad ID assigned when the message ad is first created.
price	`Long`	Unit price for sending (Unit: KRW) `15`: Targeting not applied. `20`: Targeting applied.
contractCount	`Integer`	Number of purchased sends, the number of reserved message ad sends.
totalBudget	`Long`	Purchase amount, the total amount reserved for sending the message ad.
totalBudgetWithVAT	`Long`	Purchase amount including VAT, `totalBudget` with VAT added.

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation/targeting-price" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "deviceTypes": [],
        "targeting": {
            "genderType": "ALL",
            "ageType": "ALL",
            "locationType": "ALL"
        }
    }'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1164046062704201728",
  "price": 15,
  "contractCount": 2,
  "totalBudget": 30,
  "totalBudgetWithVAT": 33.0
}

Finish message ad

Basic information

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

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

Terminates the message ad.

Messages currently being sent will be stopped, and scheduled messages will be cancelled.

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 -X PUT "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/finish" \
  -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

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

Message ad operation

Before you begin

Available message types

Message type components

Basic text (BASIC_TEXT_MESSAGE)

Wide image (WIDE_MESSAGE)

Wide list (WIDE_LIST_MESSAGE)

Carousel commerce (CAROUSEL_COMMERCE_MESSAGE)

Intro

Carousel

Carousel feed (CAROUSEL_FEED_MESSAGE)

Premium video (PREMIUM_VIDEO_MESSAGE)

Catalog (CATALOG_MESSAGE)

Spotlight (SPOTLIGHT_MESSAGE)

Promotional area common specifications

Encoding

Save message ad

Basic information

Request

Header

Body

Response

Body

Sample

Request

Request: Body when requesting a Kakao Talk Channel video

Response

Edit message

Basic information

Usage policy

Request

Header

Path variable

Body

Response

Body

Sample

Request

Response

Send test message ad

Basic information

Conditions for use

Rate limit

Request

Header

Path variable

Body

Sample

Request

Response

Create scheduled message ad

Basic information

Send time conditions

Send cost

Request

Header

Path variable

Body

Targeting

Response

Body

View scheduled message ads

Basic information

Request

Header

Path variable

Response

Body

Edit scheduled message ad

Basic information