Kakao Moment

Ad creation: Ad group

This document describes how to use the Ad group APIs.

View list of ad groups

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	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 ad groups.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Query parameter

Name	Type	Description	Required
campaignId	`Long`	Campaign's ID.	O
config	`Enum: Config[]`	Ad group's status (Default: `ON`, `OFF`).	X

Response

Body

Name	Type	Description
content	`AdGroup[]`	List of ad group information.

AdGroup

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group' name.
config	`Enum: Config`	Ad group's status.
userConfig	`Enum: Config`	Ad group's status. Note: `userConfig` has the same value as `config`. This field is deprecated and provided for reference.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups?campaignId=1234&config=ON" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "content": [
    {
      "id": 1111,
      "name": "ad_group_1",
      "config": "ON",
      "userConfig": "ON",
      "systemConfig": "ON"
    },
    {
      "id": 1112,
      "name": "ad_group_2",
      "config": "OFF",
      "userConfig": "OFF",
      "systemConfig": "ADMIN_STOP"
    }
  ]
}

View ad group

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${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 the specified ad group.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Path variable

Name	Type	Description	Required
ID	`Long`	Ad group's ID.	O

Response

Body: Display ad group

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`Enum: Config`	Ad group's status.
pacing	`Enum: Pacing`	Spending method.
pricingType	`Enum: PricingType`	Pricing type. `CPM`: Cost per Mille `CPC`: Cost per Click `CPA`: Cost per Action
bidAmount	`Integer`	Maximum bid.
bidStrategy	`Enum`	Bidding method. `MANUAL`: Manual bidding `AUTOBID`: Automatic bidding `OPTIMIZATION`: Optimized bidding for purpose
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.
statusDescription	`String`	Status of the ad group.
status	`Enum: Status[]`	Status.
optimizationStatus	`Enum: OptimizationStatus[]`	Status of optimization.
deviceTypes	`Enum: DeviceType[]`	Device type.
adServingCategories	`String[]`	Categories under Network for ad placements.
sectionCategories	`String[]`	Section category. Note: Provided only if the campaign type is 'Kakao Bizboard', 'Display', 'Video', or 'Product catalog'.
placements	`Enum: Placement[]`	Placements where ads are displayed.
targeting	`Targeting`	Targeting.
schedule	`Schedule`	Schedule.
campaign	`Campaign`	Campaign.
useWifiOnly	`Boolean`	Whether to display ads when WiFi is connected.
creativeCount	`Integer`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices.
allAvailablePlacement	`Boolean`	Whether to display ads on all available places.
adult	`Boolean`	Whether to use adult targeting. `true`: Adult targeting allowed `false`: Adult targeting not allowed
dailyBudgetAmount	`Long`	Daily budget.
isDailyBudgetAmountOver	`Boolean`	Whether or not the daily budget is exceeded.
isValidPeriod	`Boolean`	Whether or not the delivery period is valid.
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Body: Message ad group

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group' name.
config	`Enum: Config`	Ad group's status.
smartMessage	`Boolean`	Whether to use a Smart message.
pricingType	`Enum: PricingType`	Pricing type. `CPMS`: Cost per Message Send
bidAmount	`Integer`	Bid amount.
bidStrategy	`String`	Bidding method. Fixed to `MANUAL`.
totalBudget	`Long`	Total budget.
totalBudgetWithVAT	`Long`	Budget including a Value-Added Tax (VAT).
status	`Enum: Status[]`	Status.
placements	`Enum: Placement[]`	Placements where ads are displayed.
targeting	`Targeting`	Targeting.
schedule	`Schedule`	Schedule.
messageSendingInfo	`MessageSendingInfo`	Message information.
profileId	`String`	Kakao Talk Channel's profile ID.
campaign	`Campaign`	Campaign.
useWifiOnly	`Boolean`	Whether to display ads when WiFi is connected.
creativeCount	`Long`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices.
allAvailablePlacement	`Boolean`	Whether to display ads on all available places.
adult	`Boolean`	Whether to use adult targeting. Fixed to `false` (adult targeting not allowed).
isDailyBudgetAmountOver	`Boolean`	Whether or not the daily budget is exceeded.
isValidPeriod	`Boolean`	Whether or not the delivery period is valid.
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 54322,
  "name": "kakao_bizboard_visit_202205201557",
  "config": "ON",
  "dynamicTarget": null,
  "creativeOptimization": false,
  "smartMessage": null,
  "pacing": "NONE",
  "pricingType": "CPC",
  "bidAmount": 0,
  "bidStrategy": "AUTOBID",
  "statusDescription": "운영중",
  "status": ["LIVE"],
  "deviceTypes": ["ANDROID", "IOS"],
  "placements": ["DAUM", "NETWORK", "KAKAO_TALK", "KAKAO_SERVICE"],
  "targeting": {
    "type": "NORMAL",
    "adAccountId": null,
    "ageType": "ALL",
    "genderType": "ALL",
    "locationType": "AREA",
    "locations": [
      {
        "value": "E",
        "description": "광주광역시",
        "depth1Name": "광주광역시"
      },
      {
        "value": "O",
        "description": "충청남도",
        "depth1Name": "충청남도"
      }
    ],
    "depth2Locations": [
      {
        "value": "B7222",
        "description": "경기도 여주시",
        "depth1Name": "경기도",
        "depth2Name": "여주시"
      },
      {
        "value": "I1009",
        "description": "서울특별시 도봉구",
        "depth1Name": "광주광역시",
        "depth2Name": "도봉구"
      }
    ],
    "depth3Locations": [
      {
        "value": "A70052424",
        "description": "강원도 삼척시 원덕읍",
        "depth1Name": "강원도",
        "depth2Name": "삼척시",
        "depth3Name": "원덕읍"
      },
      {
        "value": "M55550301",
        "description": "전북특별자치도 전주시 덕진구 금암1동",
        "depth1Name": "전북특별자치도",
        "depth2Name": "전주시 덕진구",
        "depth3Name": "금암1동",
        "deprecated": true
      }
    ],
    "ufoInterests": ["I0202", "I020601", "I03", "I320104"],
    "ufoDeprecatedInterests": ["I320104"],
    "ufoBusinessTypes": ["P1021", "P2003"],
    "ufoDeprecatedBusinessTypes": ["P2003"]
  },
  "schedule": {
    "detailTime": false,
    "beginDate": "2022-05-20",
    "beginTime": "00:00:00",
    "mondayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "tuesdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "wednesdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "thursdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "fridayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "saturdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "sundayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "lateNight": false
  },
  "campaign": {
    "id": 33626,
    "name": "modified_pixel&SDK_kakao_bizboard_visit_202204211136",
    "campaignTypeGoal": {
      "campaignType": "TALK_BIZ_BOARD",
      "goal": "VISITING"
    },
    "objective": null,
    "dailyBudgetAmount": null,
    "config": "ON",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 27429,
    "status": ["LIVE"],
    "systemConfig": "ON",
    "isDailyBudgetAmountOver": false,
    "adminStop": false
  },
  "useWifiOnly": false,
  "creativeCount": 0,
  "systemConfig": "ON",
  "allAvailableDeviceType": false,
  "allAvailablePlacement": true,
  "adult": false,
  "dailyBudgetAmount": 100000,
  "isDailyBudgetAmountOver": false,
  "isValidPeriod": true,
  "createdDate": "2022-05-20T15:57:51",
  "lastModifiedDate": "2022-05-20T15:57:51",
  "adminStop": false
}

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 32001,
    "detailMsg": "광고그룹이 존재하지 않습니다."
  }
}

Create Display ad group

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	Business token

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

Creates a Display ad group under a campaign.

See the descriptions below for detailed conditions on targeting and delivery strategy settings.

Delivery strategies settings

Bidding method

Bidding method	Type	Bid amount setting
Manual bidding	`CPA` `CPC` `CPM` `CPV`	Set the maximum bid amount. You can bid with the input bid amount but are charged less than the input value. Required: Yes Input range: Minimum defined by each campaign preset, maximum 100,000 won or 50 % of your daily budget set for the ad group Unit: 1 won (KRW) Default: Defined by each campaign preset
Automatic bidding	Maximizing the number of clicks Maximizing the number of conversions Maximizing the value of conversions	Unnecessary. The system automatically bids with the best amount.
Automatic bidding	CPC cost targeting	Set the target bid amount. Bid with the target bid amount, but the amount may be above or below the target value due to the optimization process. Required: Yes Input range: Minimum 10 won, maximum 10,000 won or 50 % of your daily budget set for the ad group Unit: 1 won (KRW)
Automatic bidding	CPA cost targeting	Set the target bid amount. Bid with the target bid amount, but the amount may be above or below the target value due to the optimization process. Required: Yes Input range: Minimum 100 won, maximum 1,000,000 won or 50 % of your daily budget set for the ad group Unit: 1 won (KRW)
Automatic bidding	ROAS cost targeting	Set the target ROAS(Return on Advertising Spend). Bid with the target ROAS, but the amount may be above or below the target value due to the optimization process. Required: Yes Input range: Minimum 10%, maximum 100,000% Unit: 1%

Default, minimum, and maximum values by bidding method

Ad Type Manual bidding Automatic bidding

Display

Ad Type	Manual bidding	Automatic bidding
Display	Default `CPA`: 1,500 `CPC`: 200 `CPM`: 1,000 Minimum `CPA`: 100 `CPC`: 10 `CPM`: 100 Maximum Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.	Minimum CPC cost targeting: 10 CPA cost targeting: 100 ROAS targeting: 10 Maximum CPC cost targeting: Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group. CPA cost targeting: Smaller value between 1,000,000 won (KRW) and 50 % of your daily budget set for the ad group. ROAS targeting: 100,000 In the case of maximizing the number of clicks, maximizing the number of conversion and maximizing the value of conversions, set `bidAmount` to 0. Then `bidAmount` will be automatically set by the system in the daily budget to maximize the effectiveness of the selected advertisement.
Kakao Bizboard	Default `CPC`: 200 `CPM`: 3,000 Minimum `CPC`: 10 `CPM`: 1,000 Maximum Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.	Minimum CPC cost targeting: 10 CPA cost targeting: 100 ROAS targeting: 10 Maximum CPC cost targeting: Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group. CPA cost targeting: Smaller value between 1,000,000 won (KRW) and 50 % of your daily budget set for the ad group. ROAS targeting: 100,000 In the case of maximizing the number of clicks, maximizing the number of conversions and maximizing the value of conversions, set `bidAmount` to 0. Then `bidAmount` will be automatically set by the system in the daily budget to maximize the effectiveness of the selected advertisement.
Video	Default `CPV`: 20 Minimum `CPV`: 10 Maximum Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.	Not provided

Default

CPA: 1,500
CPC: 200
CPM: 1,000

Minimum

CPA: 100
CPC: 10
CPM: 100

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.

Minimum

CPC cost targeting: 10
CPA cost targeting: 100
ROAS targeting: 10

Maximum

CPC cost targeting: Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.
CPA cost targeting: Smaller value between 1,000,000 won (KRW) and 50 % of your daily budget set for the ad group.
ROAS targeting: 100,000

In the case of maximizing the number of clicks, maximizing the number of conversion and maximizing the value of conversions, set bidAmount to 0. Then bidAmount will be automatically set by the system in the daily budget to maximize the effectiveness of the selected advertisement.

Kakao Bizboard

Default

CPC: 200
CPM: 3,000

Minimum

CPC: 10
CPM: 1,000

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.

Minimum

CPC cost targeting: 10
CPA cost targeting: 100
ROAS targeting: 10

Maximum

CPC cost targeting: Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.
CPA cost targeting: Smaller value between 1,000,000 won (KRW) and 50 % of your daily budget set for the ad group.
ROAS targeting: 100,000

In the case of maximizing the number of clicks, maximizing the number of conversions and maximizing the value of conversions, set bidAmount to 0. Then bidAmount will be automatically set by the system in the daily budget to maximize the effectiveness of the selected advertisement.

Video

Default

CPV: 20

Minimum

CPV: 10

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.

Not provided

Delivery strategies

Daily budget for a group

In this step, you can set the daily budget for a group, which indicates the consolidated spending limit of an ad group for a day from 00:00 to 24:00.

Required values:
- Allowed to input a value from 10,000 to 500 million won or the set daily budget for the campaign.
- Allowed to input a value in multiples of 10 won (KRW).
- Default: 100,000 won (KRW).
Set the campaign's daily budget and the ad group's daily budget individually.
- If either budget runs out first, the ads stop running.

Delivery period

In this step, you can set the delivery period by selecting a start date and end date to run an ad.
For delievery period, you can only select the start date and end date, not day and time.

Start date	End date	Day	Time
You can select a date from today to up to 6 months later. Default: 오늘(Today)	You can select a date after the start date. You can select the "종료일 없음(No end date)" option. Default: 종료일 없음(No end date)	You cannot select a day. Default: All	You cannot set the start time and end time. Only for the Late night targeting, you can set the time from 22:00 to 06:59.

Rate limit

This API limits the number of calls you can make to every five seconds per user account and ad account.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name (Maximum: 50 characters). Automatically generated if omitted.	X
placements	`Enum: Placement[]`	Ad placements.	O
adServingCategories	`String[]`	Categories under Network for ad placements. Required if `placements` is set to `NETWORK`. If the campaign type is 'Kakao Bizboard', use all fields. Use `code` that is passed in the response of the View categories of Network for placements API.	X
sectionCategories	`String[]`	Section category. Allowed only if the campaign type is 'Kakao Bizboard', 'Display', 'Video', or 'Product catalog', and if `placements` is set to `KAKAO_TALK`. Use `code` that is passed in the response of the View list of section categories API.	X
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices (Default: `true`). Important: `true` can be passed only if the campaign type is Video X View or Display X Visit, or Display X Conversion whose objective is Purchase, Sign up, Potential customer, Apply for a service, or Add to a cart in Pixel & SDK. Important: If `true`, you must pass all of `ANDROID`, `IOS`, and `PC` in `deviceTypes`.	X
allAvailablePlacement	`Boolean`	Whether to display ads on all available places (Default: `true`). Important: `true` can be passed only if the campaign type is Display, Video, or Kakao Bizboard.	X
deviceTypes	`Enum: DeviceType[]`	Device type. Important: If the campaign type is not Display X Visit or Video X View, only `ANDROID` and `IOS` can be passed. Important: If `allAvailableDeviceType` is `true`, you must pass all of `ANDROID`, `IOS`, and `PC`.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting (Default: `false`). Important: If `true`, ads are exposed only to people aged 20 or older, and you must pass `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70` in `targeting.ages`.	X
dailyBudgetAmount	`Integer`	Daily budget.	O
bidStrategy	`Enum`	Bidding method. `MANUAL`: Manual bidding `AUTOBID`: Automatic bidding	O
pricingType	`Enum: PricingType`	Manual bidding method. `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View	O
bidAmount	`Integer`	Bid amount for manual payments. Set to 0 for automatic bidding.	O
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.	X
pacing	`Enum: Pacing`	Spending method. Important: If `bidStrategy` (Bidding method) is `MANUAL`, pass `NORMAL` or `QUICK`; if `AUTOBID`, pass `NONE`.	O
schedule	`Schedule`	Schedule information.	O

Campaign

Name	Type	Description
id	`Long`	Campaign's ID.

Targeting

Name	Type	Description	Required
id	`Long`	Audience's ID if using an audience.	X
type	`Enum`	Whether to use Audience. `NORMAL`: General targeting. `DISPLAY`: Use the set Display Audience. `MESSAGE`: Use the set Message Audience. Important: If you set it to `DISPLAY` or `MESSAGE`, pass empty values for the other targeting information. Important: If the ad type is `DISPLAY`, you must set the audience type to `DISPLAY`.	X
ageType	`Enum`	Selection type for age range. `ALL`: Select all age ranges `NOT_ALL`: Select some age ranges Important: If you set `adult` (Whether to use adult targeting) to `true`, only `NOT_ALL` is allowed.	O
ages	`String[]`	Age range `15`: 15 to 19 `20`: 20 to 24 `25`: 25 to 29 `30`: 30 to 34 `35`: 35 to 39 `40`: 40 to 44 `45`: 45 to 49 `50`: 50 to 54 `55`: 55 to 59 `60`: 60 to 64 `65`: 65 to 69 `70`: Over 70 Important: Required if `ageType` is `NOT_ALL`. Do not pass if `ageType` is `ALL`. Important: If you set `adult` (Whether to use adult targeting) to `true`, pass `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70` as an array.	X
genderType	`Enum`	Selection type for gender. `ALL`: Select all genders `NOT_ALL`: Select a specific gender	O
genders	`String[]`	Gender `M`: Male `F`: Female Important: Required if `genderType` is `NOT_ALL`. Do not pass if `genderType` is `ALL`.	X
ufoInterests	`UfoInterest[]`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [관심사(Interests)] Refer to View category data for custom audience targeting API.	X
ufoBusinessTypes	`UfoBusinessType[]`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [업종(Industries)] Refer to View category data for custom audience targeting API.	X
locationType	`Enum`	Selection type for areas. `ALL`: All domestic `AREA`: Select some areas Important: If `locationType` is not specified, all areas (domestic and overseas) are set.	X
locations	`Location[]`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/도(-si/do)] Refer to View city/province. Important: If `locationType` is set to `ALL` (All domestic), you must include all `locations` (-si/do) code values (`A`, `B`, ...) and `U` (Unknown) in your request. (`Z` (Overseas) is excluded.) Note: Can be passed together with `depth2Locations` (-si/gun/gu) and `depth3Locations` (-dong/eup/myeon).	X
depth2Locations	`Depth2Location[]`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/군/구(-si/gun/gu)] Refer to View city/county/district. Important: If `locationType` is `AREA`, you must pass at least one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon).	X
depth3Locations	`Depth3Location[]`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [동/읍/면(-dong/eup/myeon)] Refer to View dong/eup/myeon. Important: If `locationType` is `AREA`, you must pass at least one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon).	X
customerFileTargetings	`CustomerFileTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [고객파일(Customer file]) Use the information retrieved through the View list of targetable customer files API.	X
trackerTargetings	`TrackerTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [픽셀 & SDK(Pixel & SDK)] Use the information retrieved through the View targetable Pixel & SDK events API.	X
cohortTargetings	`CohortTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [광고반응타겟(Engagement target)] Use the information retrieved through the View targetable Engagement target API.	X
talkChannelTargetings	`TalkChannelTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오톡 채널 친구(Kakao Talk Channel friend)] Use the information retrieved through the View list of targetable Kakao Talk Channels API.	X
syncAppTargetings	`SyncAppTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오 로그인 이용자(Kakao Login user)] Use the information retrieved through the View list of targetable Kakao Talk Channels API.	X
talkChannelGroupTargetings	`TalkChannelGroupTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [친구그룹(Friend group)] Use the information retrieved through the View list of targetable Friend groups API. Only the campaigns with 'Kakao Talk Channel X Reach(도달)' type are allowed.	X

TalkChannelGroupTargeting

Name	Type	Description	Required
talkChannelGroupFileId	`Long`	Friend group file ID.	O
name	`String`	Friend group's name.	O
inclusionType	`Enum: InclusionType`	Whether to include or exclude the information extracted from a Friend group file for ad group targeting.	O
fileType	`Enum`	Friend group's type. `APP_USER_ID`: Service user ID `PHONE_NUMBER`: Phone number `MESSAGE_RETARGET`: Message recipients	O
groupKey	`String`	Friend group file's group key.	O

CustomerFileTargeting

Name	Type	Description	Required
customerFileId	`Long`	Registered customer file number.	O
inclusionType	`Enum: InclusionType`	Whether to include or exclude the information extracted from a customer file for ad group targeting.	O

TrackerTargeting

Name	Type	Description	Required
trackId	`String`	Tracking ID.	O
inclusionType	`Enum: InclusionType`	Whether to include or exclude the information extracted from a Pixel & SDK event for ad group targeting.	O
eventCode	`String`	Event code. Pass `*` for all events.	O
trackRuleId	`String`	Track Rule ID.	O
trackRuleName	`String`	Track Rule name.	O
term	`Integer`	Targeting period (Minimum: 1, Maximum: 180).	O

CohortTargeting

Name	Type	Description	Required
cohortId	`String`	Registered engagement targeting number.	O
inclusionType	`Enum: InclusionType`	Whether to include or exclude the information extracted through engagement targeting for ad group targeting.	O

TalkChannelTargeting

Name	Type	Description	Required
profileId	`String`	Kakao Talk Channel's profile ID.	O
inclusionType	`Enum: InclusionType`	Whether to include or exclude the information extracted from a Kakao Talk Channel for ad group targeting.	O

SyncAppTargeting

Name	Type	Description	Required
profileId	`String`	Kakao Talk Channel's profile ID.	O
inclusionType	`Enum: InclusionType`	Whether to include or exclude the information extracted from a Kakao Talk Channel for ad group targeting.	O

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`Enum: Config`	Ad group's status.
pacing	`Enum: Pacing`	Spending method.
pricingType	`Enum: PricingType`	Pricing type. `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View
bidAmount	`Integer`	Maximum bid.
bidStrategy	`Enum`	Bidding method. `MANUAL`: Manual bidding `AUTOBID`: Automatic bidding `OPTIMIZATION`: Optimized bidding for purpose
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.
statusDescription	`String`	Status of the ad group.
status	`Enum: Status[]`	Status.
optimizationStatus	`Enum: OptimizationStatus[]`	Status of optimization.
deviceTypes	`Enum: DeviceType[]`	Device type.
adServingCategories	`String[]`	Categories under Network for ad placements.
sectionCategories	`String[]`	Section category. Note: Provided only if the campaign type is 'Kakao Bizboard', 'Display', 'Video', or 'Product catalog'.
placements	`Enum: Placement[]`	Placements where ads are displayed.
targeting	`Targeting`	Targeting.
schedule	`Schedule`	Schedule.
campaign	`Campaign`	Campaign.
useWifiOnly	`Boolean`	Whether to display ads when WiFi is connected.
creativeCount	`Integer`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices.
allAvailablePlacement	`Boolean`	Whether to display ads on all available places.
adult	`Boolean`	Whether to use adult targeting.
totalBudget	`Integer`	Total budget.
dailyBudgetAmount	`Long`	Daily budget.
isDailyBudgetAmountOver	`Boolean`	Whether or not the daily budget is exceeded.
isValidPeriod	`Boolean`	Whether or not the delivery period is valid.
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/v4/adGroups" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "campaign": {
                "id": 5678
            },
            "placements": ["KAKAO_TALK"],
            "allAvailableDeviceType": false,
            "allAvailablePlacement": false,
            "deviceTypes": ["IOS", "ANDROID"],
            "targeting": {
                "ageType": "NOT_ALL",
                "ages": ["15", "20", "25", "30", "35", "40", "45", "50", "55", "60", "65"],
                "genderType": "NOT_ALL",
                "genders": ["M", "F"],
                "sectionCategories": ["KKO99-1"],
                "cohortTargetings": [
                    {"cohortId": 1, "inclusionType": "EXCLUDE"}
                ],
                "customerFileTargetings": [
                    {"customerFileId": 1, "inclusionType": "INCLUDE"}
                ],
                "talkChannelTargetings": [
                    {"profileId":1, "inclusionType":"EXCLUDE"}
                ],
                "syncAppTargetings": [
                    {"profileId":1, "inclusionType":"INCLUDE"}
                ],
                "trackerTargetings": [
                    {
                    "trackId": "123456789",
                    "inclusionType": "INCLUDE",
                    "term": 180,
                    "eventCode": "PageView",
                    "trackRuleId": "*",
                    "trackRuleName": "방문"
                    }
                ],
                "locationType": "AREA",
                "locations": [
                      {
                        "value": "E",
                        "description": "광주광역시",
                     "depth1Name": "광주광역시"
                     },
                     {
                      "value": "O",
                      "description": "충청남도",
                     "depth1Name": "충청남도"
                  }
              ],
                "depth2Locations": [
                    {
                        "value": "B7222",
                        "description": "경기도 여주시",
                        "depth1Name": "경기도",
                         "depth2Name": "여주시"
                    },
                    {
                        "value": "I1009",
                        "description": "서울특별시 도봉구",
                        "depth1Name": "광주광역시",
                        "depth2Name": "도봉구"
                    }
                ],
        "depth3Locations": [
                {
                "value": "A70052424",
                "description": "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
                },
                {
                "value": "E13010702",
                "description": "광주광역시 남구 백운2동",
                "depth1Name": "광주광역시",
                "depth2Name": "남구",
                "depth3Name": "백운2동"
                }
                ]
              },
            "adult": false,
            "dailyBudgetAmount": 100000,
            "bidStrategy": "AUTOBID",
            "bidStrategyTarget": {
                "type": "TARGET_CPC",
                "value": 250
            },
            "bidAmount": 0,
            "pricingType": "CPC",
            "pacing": "NONE",
            "name": "카카오톡_비즈보드_등록",
            "schedule": {
                "beginDate": "2020-01-01",
                "endDate": "2020-01-31",
                "lateNight": true,
                "detailTime": false,
                "mondayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "tuesdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "wednesdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "thursdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "fridayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "saturdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "sundayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","0"]
            },
            "type": "DISPLAY"
        }'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 54322,
  "name": "카카오 비즈보드_방문_202205201557",
  "config": "ON",
  "dynamicTarget": null,
  "creativeOptimization": false,
  "smartMessage": null,
  "pacing": "NONE",
  "pricingType": "CPC",
  "bidAmount": 0,
  "bidStrategy": "AUTOBID",
  "bidStrategyTarget": {
    "type": "TARGET_CPC",
    "value": 250
  },
  "statusDescription": "운영중",
  "status": ["LIVE"],
  "deviceTypes": ["ANDROID", "IOS"],
  "placements": ["DAUM", "NETWORK", "KAKAO_TALK", "KAKAO_SERVICE"],
  "targeting": {
    "type": "NORMAL",
    "adAccountId": null,
    "ageType": "ALL",
    "genderType": "ALL",
    "locationType": "AREA",
    "locations": [
      {
        "value": "E",
        "description": "광주광역시",
        "depth1Name": "광주광역시"
      },
      {
        "value": "O",
        "description": "충청남도",
        "depth1Name": "충청남도"
      }
    ],
    "depth2Locations": [
      {
        "value": "B7222",
        "description": "경기도 여주시",
        "depth1Name": "경기도",
        "depth2Name": "여주시"
      },
      {
        "value": "I1009",
        "description": "서울특별시 도봉구",
        "depth1Name": "광주광역시",
        "depth2Name": "도봉구"
      }
    ],
    "depth3Locations": [
      {
        "value": "A70052424",
        "description": "강원도 삼척시 원덕읍",
        "depth1Name": "강원도",
        "depth2Name": "삼척시",
        "depth3Name": "원덕읍"
      },
      {
        "value": "M55550301",
        "description": "전북특별자치도 전주시 덕진구 금암1동",
        "depth1Name": "전북특별자치도",
        "depth2Name": "전주시 덕진구",
        "depth3Name": "금암1동",
        "deprecated": true
      }
    ]
  },
  "schedule": {
    "detailTime": false,
    "beginDate": "2022-05-20",
    "beginTime": "00:00:00",
    "mondayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "tuesdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "wednesdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "thursdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "fridayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "saturdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "sundayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "lateNight": false
  },
  "campaign": {
    "id": 33626,
    "name": "픽셀&SDK수정_카카오 비즈보드_방문_202204211136",
    "campaignTypeGoal": {
      "campaignType": "TALK_BIZ_BOARD",
      "goal": "VISITING"
    },
    "objective": null,
    "dailyBudgetAmount": null,
    "config": "ON",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 27429,
    "status": ["LIVE"],
    "systemConfig": "ON",
    "isDailyBudgetAmountOver": false,
    "adminStop": false
  },
  "useWifiOnly": false,
  "creativeCount": 0,
  "systemConfig": "ON",
  "allAvailableDeviceType": false,
  "allAvailablePlacement": true,
  "adult": false,
  "dailyBudgetAmount": 100000,
  "isDailyBudgetAmountOver": false,
  "isValidPeriod": true,
  "createdDate": "2022-05-20T15:57:51",
  "lastModifiedDate": "2022-05-20T15:57:51",
  "adminStop": false
}

Edit Display ad group

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	Business token

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

Enables you to edit the detailed information of the Display ad group under a campaign.

Before using this API, retrieve the Display ad group's information by calling the View ad group API first. After that, pass the fields to be edited and not to be edited together when requesting to edit the Display ad group. You must also pass the existing values of the fields you do not want to edit to retain the existing information of the ad group.

Rate limit

This API limits the number of calls you can make to every five seconds per user account and ad account.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name (Maximum: 50 characters). If omitted, the previous name is kept.	X
placements	`Enum: Placement[]`	Ad placements.	O
adServingCategories	`String[]`	Categories under Network for ad placements. Required if `placements` is set to `NETWORK`. If the campaign type is 'Kakao Bizboard', use all fields. Use `code` that is passed in the response of the View categories of Network for placements API.	X
sectionCategories	`String[]`	Section category. Allowed only if the campaign type is 'Kakao Bizboard', 'Display', 'Video', or 'Product catalog', and if `placements` is set to `KAKAO_TALK`. Use `code` that is passed in the response of the View list of section categories API.	X
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices (Default: `true`). Important: `true` can be passed only if the campaign type is Video X View or Display X Visit, or Display X Conversion whose objective is Purchase, Sign up, Potential customer, Apply for a service, or Add to a cart in Pixel & SDK. Important: If `true`, you must pass all of `ANDROID`, `IOS`, and `PC` in `deviceTypes`.	X
allAvailablePlacement	`Boolean`	Whether to display ads on all available places (Default: `true`). Important: `true` can be passed only if the campaign type is Display, Video, or Kakao Bizboard.	X
deviceTypes	`Enum: DeviceType[]`	Device type. Important: If the campaign type is not Display X Visit or Video X View, only `ANDROID` and `IOS` can be passed. Important: If `allAvailableDeviceType` is `true`, you must pass all of `ANDROID`, `IOS`, and `PC`.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting (Default: `false`). Important: If `true`, ads are exposed only to people aged 20 or older, and you must pass `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70` in `targeting.ages`. Important: If adult targeting is set to `true` when creating the ad group, it cannot be changed to `false`.	X
dailyBudgetAmount	`Integer`	Daily budget.	O
bidStrategy	`Enum`	Bidding method. `MANUAL`: Manual bidding `AUTOBID`: Automatic bidding	O
pricingType	`Enum: PricingType`	Manual bidding method. `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View	O
bidAmount	`Integer`	Bid amount for manual payments. Set to 0 for automatic bidding.	O
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.	X
pacing	`Enum: Pacing`	Spending method. Important: Allowed only if `bidStrategy` (Bidding method) is `MANUAL`. Important: For an ad group under a Kakao Bizboard X Conversion campaign, pass `NONE`.	O
schedule	`Schedule`	Schedule information.	O

Campaign

Name	Type	Description
id	`Long`	Campaign's ID.

Targeting

Name	Type	Description	Required
id	`Long`	Audience's ID if using an audience.	X
type	`Enum`	Whether to use Audience. `NORMAL`: General targeting. `DISPLAY`: Use the set Display Audience. `MESSAGE`: Use the set Message Audience. Important: If you set it to `DISPLAY` or `MESSAGE`, pass empty values for the other targeting information. Important: If the ad type is `DISPLAY`, you must set the audience type to `DISPLAY`.	X
ageType	`Enum`	Selection type for age range. `ALL`: Select all age ranges `NOT_ALL`: Select some age ranges Important: If you set `adult` (Whether to use adult targeting) to `true`, only `NOT_ALL` is allowed.	O
ages	`String[]`	Age range `15`: 15 to 19 `20`: 20 to 24 `25`: 25 to 29 `30`: 30 to 34 `35`: 35 to 39 `40`: 40 to 44 `45`: 45 to 49 `50`: 50 to 54 `55`: 55 to 59 `60`: 60 to 64 `65`: 65 to 69 `70`: Over 70 Important: Required if `ageType` is `NOT_ALL`. Do not pass if `ageType` is `ALL`. Important: If you set `adult` (Whether to use adult targeting) to `true`, pass `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70` as an array.	X
genderType	`Enum`	Selection type for gender. `ALL`: Select all genders `NOT_ALL`: Select a specific gender	O
genders	`String[]`	Gender `M`: Male `F`: Female Important: Required if `genderType` is `NOT_ALL`. Do not pass if `genderType` is `ALL`.	X
ufoInterests	`UfoInterest[]`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [관심사(Interests)] Refer to View category data for custom audience targeting API.	X
ufoBusinessTypes	`UfoBusinessType[]`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [업종(Industries)] Refer to View category data for custom audience targeting API.	X
locationType	`Enum`	Selection type for areas. `ALL`: All domestic `AREA`: Select some areas Important: If `locationType` is not specified, all areas (domestic and overseas) are set.	X
locations	`Location[]`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/도(-si/do)] Refer to View city/province. Important: If `locationType` is set to `ALL` (All domestic), you must include all `locations` (-si/do) code values (`A`, `B`, ...) and `U` (Unknown) in your request. (`Z` (Overseas) is excluded.) Note: Can be passed together with `depth2Locations` (-si/gun/gu) and `depth3Locations` (-dong/eup/myeon).	X
depth2Locations	`Depth2Location[]`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/군/구(-si/gun/gu)] Refer to View city/county/district. Important: If `locationType` is `AREA`, you must pass at least one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon).	X
depth3Locations	`Depth3Location[]`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [동/읍/면(-dong/eup/myeon)] Refer to View dong/eup/myeon. Important: If `locationType` is `AREA`, you must pass at least one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon).	X
customerFileTargetings	`CustomerFileTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [고객파일(Customer file]) Use the information retrieved through the View list of targetable customer files API.	X
trackerTargetings	`TrackerTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [픽셀 & SDK(Pixel & SDK)] Use the information retrieved through the View targetable Pixel & SDK events API.	X
cohortTargetings	`CohortTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [광고반응타겟(Engagement target)] Use the information retrieved through the View targetable Engagement target API.	X
talkChannelTargetings	`TalkChannelTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user)] > [카카오톡 채널 친구(Kakao Talk Channel friend)] Use the information retrieved through the View list of targetable Kakao Talk Channels API.	X
syncAppTargetings	`SyncAppTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user)] > [카카오 로그인 이용자(Kakao Login user)] Use the information retrieved through the View list of targetable Kakao Talk Channels API.	X
talkChannelGroupTargetings	`TalkChannelGroupTargeting[]`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [친구그룹(Friend group)] Use the information retrieved through the View list of targetable Friend groups API. Only the campaigns with 'Kakao Talk Channel X Reach(도달)' type are allowed.	X

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`Enum: Config`	Ad group's status.
pacing	`Enum: Pacing`	Spending method.
pricingType	`Enum: PricingType`	Pricing type. `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View
bidAmount	`Integer`	Maximum bid.
bidStrategy	`Enum`	Bidding method. `MANUAL`: Manual bidding `AUTOBID`: Automatic bidding `OPTIMIZATION`: Optimized bidding for purpose
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.
statusDescription	`String`	Status of the ad group.
status	`Enum: Status[]`	Status.
optimizationStatus	`Enum: OptimizationStatus[]`	Status of optimization.
deviceTypes	`Enum: DeviceType[]`	Device type.
adServingCategories	`String[]`	Categories under Network for ad placements.
sectionCategories	`String[]`	Section category. Note: Provided only if the campaign type is 'Kakao Bizboard', 'Display', 'Video', or 'Product catalog'.
placements	`Enum: Placement[]`	Placements where ads are displayed.
targeting	`Targeting`	Targeting.
schedule	`Schedule`	Schedule.
campaign	`Campaign`	Campaign.
useWifiOnly	`Boolean`	Whether to display ads when WiFi is connected.
creativeCount	`Integer`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices.
allAvailablePlacement	`Boolean`	Whether to display ads on all available places.
adult	`Boolean`	Whether to use adult targeting.
totalBudget	`Integer`	Total budget.
dailyBudgetAmount	`Long`	Daily budget.
isDailyBudgetAmountOver	`Boolean`	Whether or not the daily budget is exceeded.
isValidPeriod	`Boolean`	Whether or not the delivery period is valid.
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "id": 1234,
            "campaign": {
                "id": 5678
            },
            "placements": ["KAKAO_TALK"],
            "allAvailableDeviceType": false,
            "allAvailablePlacement": false,
            "deviceTypes": ["IOS", "ANDROID"],
            "targeting": {
                "ageType": "NOT_ALL",
                "ages": ["15", "20", "25", "30", "35", "40", "45", "50", "55", "60", "65"],
                "genderType": "NOT_ALL",
                "genders": ["M", "F"],
                "sectionCategories": ["KKO99-1"],
                "cohortTargetings": [
                    {"cohortId": 1, "inclusionType": "EXCLUDE"}
                ],
                "customerFileTargetings": [
                    {"customerFileId": 1, "inclusionType": "INCLUDE"}
                ],
                "talkChannelTargetings": [
                    {"profileId":1, "inclusionType":"EXCLUDE"}
                ],
                "syncAppTargetings": [
                    {"profileId":1, "inclusionType":"INCLUDE"}
                ],
                "trackerTargetings": [
                    {
                    "trackId": "123456789",
                    "inclusionType": "INCLUDE",
                    "term": 180,
                    "eventCode": "PageView",
                    "trackRuleId": "*",
                    "trackRuleName": "방문"
                    }
                ],
                "locationType": "AREA",
                "locations": [
                         {
                        "value": "E",
                        "description": "광주광역시",
                        "depth1Name": "광주광역시"
                        },
                         {
                       "value": "O",
                        "description": "충청남도",
                      "depth1Name": "충청남도"
                       }
                         ],
                "depth2Locations": [
                        {
                        "value": "B7222",
                        "description": "경기도 여주시",
                       "depth1Name": "경기도",
                       "depth2Name": "여주시"
                        },
                        {
                        "value": "I1009",
                        "description": "서울특별시 도봉구",
                        "depth1Name": "광주광역시",
                        "depth2Name": "도봉구"
                        }
                    ],
                "depth3Locations": [
                        {
                        "value": "A70052424",
                        "description": "강원도 삼척시 원덕읍",
                      "depth1Name": "강원도",
                      "depth2Name": "삼척시",
                     "depth3Name": "원덕읍"
                        },
                        {
                        "value": "E13010702",
                        "description": "광주광역시 남구 백운2동",
                        "depth1Name": "광주광역시",
                        "depth2Name": "남구",
                     "depth3Name": "백운2동"
                        }
                   ]
            },
            "adult": false,
            "dailyBudgetAmount": 100000,
            "bidStrategy": "AUTOBID",
            "bidAmount": 0,
            "pricingType": "CPC",
            "pacing": "NONE",
            "name": "modify_kakao_talk_bizboard",
            "schedule": {
                "beginDate": "2020-01-01",
                "endDate": "2020-01-31",
                "lateNight": true,
                "detailTime": false,
                "mondayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "tuesdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "wednesdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "thursdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "fridayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "saturdayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1"],
                "sundayTime": ["1","1","1","0","0","1","0","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","1","0"]
            },
            "type": "DISPLAY"
        }'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 54322,
  "name": "kakao_bizboard_visit_202205201557",
  "config": "ON",
  "dynamicTarget": null,
  "creativeOptimization": false,
  "smartMessage": null,
  "pacing": "NONE",
  "pricingType": "CPC",
  "bidAmount": 0,
  "bidStrategy": "AUTOBID",
  "statusDescription": "운영중",
  "status": ["LIVE"],
  "deviceTypes": ["ANDROID", "IOS"],
  "placements": ["DAUM", "NETWORK", "KAKAO_TALK", "KAKAO_SERVICE"],
  "targeting": {
    "type": "NORMAL",
    "adAccountId": null,
    "ageType": "ALL",
    "genderType": "ALL",
    "locationType": "AREA",
    "locations": [
      {
        "value": "E",
        "description": "광주광역시",
        "depth1Name": "광주광역시"
      },
      {
        "value": "O",
        "description": "충청남도",
        "depth1Name": "충청남도"
      }
    ],
    "depth2Locations": [
      {
        "value": "B7222",
        "description": "경기도 여주시",
        "depth1Name": "경기도",
        "depth2Name": "여주시"
      },
      {
        "value": "I1009",
        "description": "서울특별시 도봉구",
        "depth1Name": "광주광역시",
        "depth2Name": "도봉구"
      }
    ],
    "depth3Locations": [
      {
        "value": "A70052424",
        "description": "강원도 삼척시 원덕읍",
        "depth1Name": "강원도",
        "depth2Name": "삼척시",
        "depth3Name": "원덕읍"
      },
      {
        "value": "E13010702",
        "description": "광주광역시 남구 백운2동",
        "depth1Name": "광주광역시",
        "depth2Name": "남구",
        "depth3Name": "백운2동"
      }
    ]
  },
  "schedule": {
    "detailTime": false,
    "beginDate": "2022-05-20",
    "beginTime": "00:00:00",
    "mondayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "tuesdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "wednesdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "thursdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "fridayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "saturdayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "sundayTime": ["1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"],
    "lateNight": false
  },
  "campaign": {
    "id": 33626,
    "name": "modified_pixel&SDK_kakao_bizboard_visit_202204211136",
    "campaignTypeGoal": {
      "campaignType": "TALK_BIZ_BOARD",
      "goal": "VISITING"
    },
    "objective": null,
    "dailyBudgetAmount": null,
    "config": "ON",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 27429,
    "status": ["LIVE"],
    "systemConfig": "ON",
    "isDailyBudgetAmountOver": false,
    "adminStop": false
  },
  "useWifiOnly": false,
  "creativeCount": 0,
  "systemConfig": "ON",
  "allAvailableDeviceType": false,
  "allAvailablePlacement": true,
  "adult": false,
  "dailyBudgetAmount": 100000,
  "isDailyBudgetAmountOver": false,
  "isValidPeriod": true,
  "createdDate": "2022-05-20T15:57:51",
  "lastModifiedDate": "2022-05-20T15:57:51",
  "adminStop": false
}

Edit daily budget for Display ad group

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups/dailyBudgetAmount`	Business token

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

Enables you to edit the daily budget for a Display ad group.

Daily budget conditions

Set the daily budget from 10,000 to 500 million won in multiples of 10 won.
If the campaign's daily budget is set, set the ad group's daily budget to no more than the campaign's daily budget.

Rate limit

This API limits the number of calls you can make every second per user account and ad account.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
dailyBudgetAmount	`Long`	Daily budget for an ad group. You can set the daily budget for an ad group in multiples of 10 won. Allowed range: 10,000 to 500 million won (South Korean won). If the campaign's daily budget has already been set, the daily budget for an ad group must be equal or less than the campaign's daily budget.	O

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/dailyBudgetAmount" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "id": 1234,
            "dailyBudgetAmount": 5000000
        }'

Response

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

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 32021,
    "detailMsg": "광고그룹 일예산은 최소 10,000보다 크거나 같아야 합니다."
  }
}

Edit maximum bid of Manual bidding for Display ad group

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups/bidAmount`	Business token

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

Edits the maximum bid amount of your Display ad group.

Bid amount conditions

Available only for ad groups under Display, Video, and Bizboard campaigns, except for the Reach goal.
The minimum bid amount varies by ad group type, advertising objective, and pricing type.
The bid amount cannot exceed 50% of the ad group's daily budget or 100,000 won.

Default and minimum values of the bid amount

Ad Type Maximum bid (Manual bidding)

Display

Ad Type	Maximum bid (Manual bidding)
Display	Default `CPA`: 1,500 `CPC`: 200 `CPM`: 1,000 Minimum `CPA`: 100 `CPC`: 10 `CPM`: 100 Maximum Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.
Kakao Bizboard	Default `CPC`: 200 `CPM`: 3,000 Minimum `CPC`: 10 `CPM`: 1,000 Maximum Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.
Video	Default `CPV`: 20 Minimum `CPV`: 10 Maximum Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.

Default

CPA: 1,500
CPC: 200
CPM: 1,000

Minimum

CPA: 100
CPC: 10
CPM: 100

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.

Kakao Bizboard

Default

CPC: 200
CPM: 3,000

Minimum

CPC: 10
CPM: 1,000

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.

Video

Default

CPV: 20

Minimum

CPV: 10

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.

Rate limit

This API limits the number of calls you can make every second per user account and ad account.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
bidAmount	`Integer`	Maximum bid Not allowed to exceed 50 % of your daily budget set for the ad group or the maximum value of 100,000 won (KRW). The minimum bid amount is applied differently depending on the group type, purpose, and pricing type.	O

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/bidAmount" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "id": 1234,
            "bidAmount": 5000
        }'

Response

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

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 32013,
    "detailMsg": "관련 작업을 지원하지 않는 광고그룹입니다."
  }
}

Edit delivery method for Display ad group

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups/pacing`	Business token

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

Changes the delivery method for a Display ad group.

Delivery method conditions

Available only for ad groups under Display, Video, and Bizboard campaigns, except for the Reach goal.
Available only when the bidding method is manual (MANUAL).

Rate limit

This API limits the number of calls you can make every second per user account and ad account.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
pacing	`Enum: Pacing`	Spending method. `NORMAL`: Normal spending `QUICK`: Quick spending Important: Allowed only if the bidding method is `MANUAL`.	O

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/pacing" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "id": 1234,
            "pacing": "QUICK"
        }'

Response

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

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 32016,
    "detailMsg": "게재방식을 선택할 수 없습니다."
  }
}

Create Message ad group

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	Business token

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

Creates a Message ad group under the 'Kakao Talk Channel X Reach(도달)' type of campaign.

Rate limit

This API limits the number of calls you can make to every five seconds per user account and ad account.

Delivery strategies settings: Pricing type and budget

You can pay only with the CPMS method that charges for sending each message. Depending on the set targeting information, the pricing per message is differently applied. The targeting message is charged 20 won per message, and the basic message is charged 15 won per message.

The budget of the ad group is automatically set according to the unit price and the number of messages sent. The budget including VAT is deducted from the ad account balance. When you pay for a Message ad group, you need to check whether there is sufficient balance.

Pricing type	Targeting	Price for a message	Setting value for targeting
CPMS	Not applied	15 won	`"targeting" : {"type": "NORMAL",` `"ageType": "ALL",` `"genders": [ ],` `"genderType": "NOT_ALL",` `"locationType": ""}`
CPMS	Applied	20 won	If settng additional targeting

Delivery strategies settings: Available number of sending messages

You can request the available number of sending messages by using populationScore obtained through the Retrieve estimated target population for Message ad group API.

Targeting type	Minimum	Maximum
Targeting not sepecified	Retrieved value	50,000,000
Targeting excluding Smart messages	11	Retrieved value
Targeting including Smart messages	30,000	Retrieved value

Delivery strategies settings: Acitive period

The Acitive period means the total period for which you can send messages. The period is automatically set for up to 30 days from the designated start date. If you select the '전체발송 후 새 친구에게도 보내기(Send to new friends after sending all messages)' option, you can also set the end date.

When the start date comes during the active period, the messages are sent. You can stop sending messages as far as sending messages is not completed. You can also resume sending messages within the delivery period. After the period, sending messages is terminated regardless of whether the messages have been sent or not.

Display method of Creative

If you use the Smart messages, the high-performing creatives are exposed more to improve the advertising efficiency for your ad groups. You can register up to 10 creatives. To optimize performance, you need at least 30,000 estimated target population for sending.

Other settings: 분산발송(Distributed sending)

If you are concerned about system load or others, you can control the message sending rate by setting the distributed sending rate. The set rate may be applied differently depending on the sending circumstances.

Other settings: 푸시알림 보내지 않기(Not send push notifications)

You can send a message without a Kakao Talk push notification.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name (Maximum: 50 characters). Automatically generated if omitted.	X
placements	`Enum: Placement[]`	Ad placements. Fixed to `KAKAO_TALK`.	O
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Important: `true` can be passed only if the campaign type is Display X Visit. Important: If `true`, you must pass all of `ANDROID`, `IOS`, and `PC` in `deviceTypes`.	O
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. Fixed to `false`.	O
deviceTypes	`Enum: DeviceType[]`	Device type. `ANDROID`: Android `IOS`: iOS Important: If the campaign type is not Display X Visit, only `ANDROID` and `IOS` can be passed. Important: If `allAvailableDeviceType` is `true`, you must pass all of `ANDROID`, `IOS`, and `PC`.	O
messageSendingInfo	`MessageSendingInfo`	Message information.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting. Fixed to `false` (adult targeting not allowed).	O
bidStrategy	`String`	Bidding method. Fixed to `MANUAL`.	O
pricingType	`Enum: PricingType`	Manual bidding method. Fixed to `CPMS`.	O
bidAmount	`Integer`	Bid amount for manual payments (Pricing for sending a message). Important: Pass the same value as `price` in `messageSendingInfo` (Message information).	O
pacing	`Enum: Pacing`	Spending method. Fixed to `NONE`.	O
schedule	`Schedule`	Schedule information.	O
smartMessage	`Boolean`	Whether to use Smart message. `true`: Use `false`: Not use Note: Smart message finds friends similar to those who clicked the creative based on the data collected in real time while sending messages and sends messages to them, and improves the efficiency of the ad group by exposing high-performing creatives more through creative optimization. Important: Available only for channels with 100,000 or more friends, and messages are sent to a portion of the friends to optimize performance (Maximum: 50% of friends). Important: If `true`, targeting information of a custom audience cannot be set, creatives can be registered (Maximum: 10 creatives), and at least 30,000 estimated target population is required to optimize performance.	O

MessageSendingInfo

Name	Type	Description	Required
contractCount	`Integer`	Available number of sending messages. Important: Cannot be less than the estimated target population for sending messages.	O
longTerm	`Boolean`	Whether to use the '전체발송 후 새 친구에게도 보내기(Send to new friends after sending all messages)' option. `true`: Send `false`: Not send Important: If a real-time target is selected, pass `false`. Important: If `true`, you must pass `beginDate` (Start date), `beginTime` (Start time), `endDate` (End date), and `endTime` (End time) in `schedule` (Schedule information), and set `allAvailableDeviceType` (Whether to display ads on all available devices) to `true`.	O
price	`Long`	Pricing for sending a message (Unit: won). `15`: Targeting not applied `20`: Targeting applied Note: If the targeting information changes, the pricing per message also changes.	O
pushAlarm	`Boolean`	Whether to use the '푸시알림 보내지 않기(Not send push notifications)' option. `true`: Not send push notifications `false`: Send push notifications	O
sendRate	`Integer`	Whether to use the '분산발송 하기(Distributed sending)' option. `100`, `500`, `1000`, `1500`, `2000`: Use distributed sending `0`: Not use distributed sending	O
status	`String`	Status of sending a message. Fixed to `SAVE`.	O
syncStatus	`String`	Sync status with the sending system. Fixed to `READY`.	O
ageVerification	`Boolean`	Whether to use age verification messages. `true`: Age verification message used. `false`: General message used.	O

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group' name.
config	`Enum: Config`	Ad group's status.
smartMessage	`Boolean`	Whether to use a Smart message.
pricingType	`Enum: PricingType`	Pricing type. `CPMS`: Cost per Message Send
bidAmount	`Integer`	Bid amount.
bidStrategy	`String`	Bidding method. Fixed to `MANUAL`.
totalBudget	`Long`	Total budget.
totalBudgetWithVAT	`Long`	Budget including a Value-Added Tax (VAT).
status	`Enum: Status[]`	Status.
placements	`Enum: Placement[]`	Placements where ads are displayed.
targeting	`Targeting`	Targeting.
schedule	`Schedule`	Schedule.
messageSendingInfo	`MessageSendingInfo`	Message information.
profileId	`String`	Kakao Talk Channel's profile ID.
campaign	`Campaign`	Campaign.
useWifiOnly	`Boolean`	Whether to display ads when WiFi is connected.
creativeCount	`Long`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices.
allAvailablePlacement	`Boolean`	Whether to display ads on all available places.
adult	`Boolean`	Whether to use adult targeting. Fixed to `false` (adult targeting not allowed).
isDailyBudgetAmountOver	`Boolean`	Whether or not the daily budget is exceeded.
isValidPeriod	`Boolean`	Whether or not the delivery period is valid.
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/v4/adGroups" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "campaign": {
                "id": 1
            },
            "name": "메시지_광고그룹",
            "placements": ["KAKAO_TALK"],
            "allAvailableDeviceType": true,
            "allAvailablePlacement": false,
            "deviceTypes": ["IOS", "ANDROID"],
            "messageSendingInfo": {
                "contractCount": 100,
                "longTerm": false,
                "price": 15,
                "pushAlarm": true,
                "sendRate": 0,
                "status": "SAVE",
                "syncStatus": "READY",
                "ageVerification": false
            },
            "targeting": {
                "ageType": "ALL",
                "genderType": "ALL",
                "locationType": "ALL"
            },
            "adult": false,
            "bidStrategy": "MANUAL",
            "pricingType": "CPMS",
            "bidAmount": 15,
            "pacing": "NONE",
            "schedule": {
                "beginDate": "2023-11-15",
                "beginTime": "13:00:00",
                "lateNight": false,
                "detailTime": false
            },
            "smartMessage": false
        }'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 541620,
  "name": "메시지_광고그룹",
  "config": "ON",
  "dynamicTarget": false,
  "creativeOptimization": false,
  "smartMessage": false,
  "pricingType": "CPMS",
  "bidAmount": 15,
  "bidStrategy": "MANUAL",
  "totalBudget": 1500,
  "totalBudgetWithVAT": 1650,
  "status": ["NO_AVAILABLE_CREATIVE"],
  "deviceTypes": ["IOS", "ANDROID"],
  "placements": ["KAKAO_TALK"],
  "targeting": {
    "type": "NORMAL",
    "adAccountId": null,
    "ageType": "ALL",
    "genderType": "ALL",
    "locationType": "ALL"
  },
  "schedule": {
    "detailTime": false,
    "beginDate": "2023-11-15",
    "beginTime": "13:00:00",
    "endDate": "2023-12-15",
    "endTime": "23:59:59.999999999",
    "lateNight": false
  },
  "messageSendingInfo": {
    "price": 15,
    "contractCount": 100,
    "sendRate": 0,
    "pushAlarm": true,
    "startedAt": null,
    "finishedAt": null,
    "status": "SAVE",
    "syncStatus": "READY",
    "ageVerification": false,
    "longTerm": false
  },
  "profileId": "_ZQxd",
  "campaign": {
    "id": 34097,
    "name": "카카오톡 채널_도달_202311031251",
    "campaignTypeGoal": {
      "campaignType": "TALK_CHANNEL",
      "goal": "REACH"
    },
    "objective": {
      "type": "TALK_CHANNEL",
      "detailType": "SEND_MESSAGE",
      "value": "_ZQxd"
    },
    "dailyBudgetAmount": null,
    "config": "ON",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 27429,
    "status": ["LIVE"],
    "systemConfig": "ON",
    "isDailyBudgetAmountOver": false
  },
  "useWifiOnly": false,
  "creativeCount": 0,
  "systemConfig": "ON",
  "bidStrategyTarget": null,
  "allAvailableDeviceType": true,
  "allAvailablePlacement": false,
  "adult": false,
  "isDailyBudgetAmountOver": false,
  "isValidPeriod": false,
  "createdDate": "2023-11-14T15:36:40.469166",
  "lastModifiedDate": "2023-11-14T15:36:40.522281"
}

Edit Message ad group

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	Business token

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

Enables you to edit the detailed information of the ad group under the 'Kakao Talk Channel X Reach(도달)' campaign.

Before using this API, retrieve the ad group's information by calling the View ad group API first. After that, pass the fields to be edited and not to be edited together when requesting to edit the Message ad group. You must also pass the existing values of the fields you do not want to edit to retain the existing information of the ad group.

Rate limit

This API limits the number of calls you can make to every five seconds per user account and ad account.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name (Maximum: 50 characters). If omitted, the previous name is kept.	X
placements	`Enum: Placement[]`	Placements where ads are displayed. Fixed to `KAKAO_TALK`.	O
adServingCategories	`String[]`	Categories under Network for ad placements. Required if `placements` is set to `NETWORK`. Not allowed if the campaign type is 'Kakao Bizboard'. Use `code` that is passed in the response of the View categories of Network for placements API.	X
sectionCategories	`String[]`	Section category. Allowed only if the campaign type is 'Kakao Bizboard', 'Display', 'Video', or 'Product catalog', and if `placements` is set to `KAKAO_TALK`. Use `code` that is passed in the response of the View list of section categories API.	X
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Important: `true` can be passed only if the campaign type is Display X Visit. Important: If `true`, you must pass all of `ANDROID`, `IOS`, and `PC` in `deviceTypes`.	O
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. Fixed to `false`.	O
deviceTypes	`Enum: DeviceType[]`	Device type. `ANDROID`: Android `IOS`: iOS Important: If the campaign type is not Display X Visit, only `ANDROID` and `IOS` can be passed. Important: If `allAvailableDeviceType` is `true`, you must pass all of `ANDROID`, `IOS`, and `PC`.	O
messageSendingInfo	`MessageSendingInfo`	Message information.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting. Fixed to `false` (adult targeting not allowed).	O
dailyBudgetAmount	`Integer`	Daily budget.	O
bidStrategy	`String`	Bidding method. Fixed to `MANUAL`.	O
pricingType	`Enum: PricingType`	Manual bidding method. Fixed to `CPMS`.	O
smartMessage	`Boolean`	Whether to use Smart message. `true`: Use `false`: Not use Note: Smart message finds friends similar to those who clicked the creative based on the data collected in real time while sending messages and sends messages to them, and improves the efficiency of the ad group by exposing high-performing creatives more through creative optimization. Important: Available only for channels with 100,000 or more friends, and messages are sent to a portion of the friends to optimize performance (Maximum: 50% of friends). Important: If `true`, targeting information of a custom audience cannot be set, creatives can be registered (Maximum: 10 creatives), and at least 30,000 estimated target population is required to optimize performance.	O
bidAmount	`Integer`	Bid amount for manual payments (Pricing for sending a message). Important: Pass the same value as `price` in `messageSendingInfo` (Message information).	O
pacing	`Enum: Pacing`	Spending method. Fixed to `NONE`.	O
schedule	`Schedule`	Schedule information.	O

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group' name.
config	`Enum: Config`	Ad group's status.
smartMessage	`Boolean`	Whether to use a Smart message.
pricingType	`Enum: PricingType`	Pricing type. `CPMS`: Cost per Message Send
bidAmount	`Integer`	Bid amount.
bidStrategy	`String`	Bidding method. Fixed to `MANUAL`.
totalBudget	`Long`	Total budget.
totalBudgetWithVAT	`Long`	Budget including a Value-Added Tax (VAT).
status	`Enum: Status[]`	Status.
placements	`Enum: Placement[]`	Placements where ads are displayed.
targeting	`Targeting`	Targeting.
schedule	`Schedule`	Schedule.
messageSendingInfo	`MessageSendingInfo`	Message information.
profileId	`String`	Kakao Talk Channel's profile ID.
campaign	`Campaign`	Campaign.
useWifiOnly	`Boolean`	Whether to display ads when WiFi is connected.
creativeCount	`Long`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices.
allAvailablePlacement	`Boolean`	Whether to display ads on all available places.
adult	`Boolean`	Whether to use adult targeting. Fixed to `false` (adult targeting not allowed).
isDailyBudgetAmountOver	`Boolean`	Whether or not the daily budget is exceeded.
isValidPeriod	`Boolean`	Whether or not the delivery period is valid.
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "id": 1,
        "campaign": {
            "id": 1
        },
        "messageSendingInfo": {
            "contractCount": 33,
            "longTerm": false,
            "price": 30,
            "pushAlarm": false,
            "sendRate": 1500,
            "status": "SAVE",
            "syncStatus": "READY"
        },
        "profileId": "_Xxo",
        "placements": ["KAKAO_TALK"],
        "allAvailableDeviceType": true,
        "allAvailablePlacement": false,
        "deviceTypes": ["IOS", "ANDROID"],
        "targeting": {
            "genderType": "NOT_ALL",
            "genders": ["M"],
            "locationType": "ALL",
            "locations": []
        },
        "adult": false,
        "dailyBudgetAmount": 100000,
        "bidStrategy": "MANUAL",
        "bidAmount": 30,
        "pricingType": "CPMS",
        "pacing": "NONE",
        "smartMessage": false,
        "name": "message_ad_group",
        "schedule": {
            "beginDate": "2021-06-01",
            "beginTime": "13:00:00",
            "lateNight": false,
            "detailTime": false,
            "mondayTime": [],
            "tuesdayTime": [],
            "wednesdayTime": [],
            "thursdayTime": [],
            "fridayTime": [],
            "saturdayTime": [],
            "sundayTime": []
        }
    }'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 541620,
  "name": "ad_group_for_sending_msg",
  "config": "ON",
  "dynamicTarget": false,
  "creativeOptimization": false,
  "smartMessage": false,
  "pricingType": "CPMS",
  "bidAmount": 15,
  "bidStrategy": "MANUAL",
  "totalBudget": 270,
  "totalBudgetWithVAT": 297,
  "status": ["FINISHED"],
  "placements": ["KAKAO_TALK"],
  "targeting": {
    "type": "NORMAL",
    "adAccountId": null,
    "ageType": "ALL",
    "genderType": "ALL",
    "locationType": "ALL"
  },
  "schedule": {
    "detailTime": false,
    "beginDate": "2022-05-17",
    "beginTime": "13:40:00",
    "endDate": "2022-06-16",
    "endTime": "23:59:59.999999999",
    "lateNight": false
  },
  "messageSendingInfo": {
    "price": 15,
    "contractCount": 18,
    "sendRate": 0,
    "pushAlarm": true,
    "startedAt": "2022-05-18T16:18:14",
    "finishedAt": "2022-05-18T16:18:26",
    "status": "FINISHED",
    "syncStatus": "SUCCESS",
    "ageVerification": false,
    "longTerm": false
  },
  "profileId": "_ZQxd",
  "campaign": {
    "id": 34097,
    "name": "kakao_talk_channel_reach_202205161039",
    "campaignTypeGoal": {
      "campaignType": "TALK_CHANNEL",
      "goal": "REACH"
    },
    "objective": {
      "type": "TALK_CHANNEL",
      "detailType": "SEND_MESSAGE",
      "value": "_ZQxd"
    },
    "dailyBudgetAmount": null,
    "config": "ON",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 27429,
    "status": ["LIVE"],
    "systemConfig": "ON",
    "isDailyBudgetAmountOver": false,
    "adminStop": false
  },
  "useWifiOnly": false,
  "creativeCount": 1,
  "systemConfig": "ON",
  "allAvailableDeviceType": true,
  "allAvailablePlacement": false,
  "adult": false,
  "isDailyBudgetAmountOver": false,
  "isValidPeriod": false,
  "createdDate": "2022-05-17T11:39:10",
  "lastModifiedDate": "2022-05-17T11:39:10"
}

Retrieve estimated target population for Message ad group

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/v4/targetings/populationScore`	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 estimated target population used to enter the number of messages to purchase when creating or editing an ad group under a Kakao Talk Channel X Reach campaign.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
campaignTypeGoal	`CampaignTypeGoal`	Campaign Type X Goal.	O
objective	`Objective`	Objective of the advertising goal. Required if the campaign's Type X Goal is set to 'Channel X Reach(도달)'.	X
placements	`Enum: Placement[]`	Placements where ads are displayed. Fixed to `KAKAO_TALK`.	O
adServingCategories	`String[]`	Categories under Network for ad placements. Required if `placements` is set to `NETWORK`. Not allowed if the campaign type is 'Kakao Bizboard'. Use `code` that is passed in the response of the View categories of Network for placements API.	X
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Important: `true` can be passed only if the campaign type is Display X Visit. Important: If `true`, you must pass all of `ANDROID`, `IOS`, and `PC` in `deviceTypes`.	O
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. Fixed to `false`.	O
deviceTypes	`Enum: DeviceType[]`	Device type. `ANDROID`: Android `IOS`: iOS Important: If the campaign type is not Display X Visit, only `ANDROID` and `IOS` can be passed. Important: If `allAvailableDeviceType` is `true`, you must pass all of `ANDROID`, `IOS`, and `PC`.	O
targeting	`Targeting`	Targeting information.	O
smartMessage	`Boolean`	Whether to use Smart message. `true`: Use `false`: Not use Note: Smart message finds friends similar to those who clicked the creative based on the data collected in real time while sending messages and sends messages to them, and improves the efficiency of the ad group by exposing high-performing creatives more through creative optimization. Important: Available only for channels with 100,000 or more friends, and messages are sent to a portion of the friends to optimize performance (Maximum: 50% of friends). Important: If `true`, targeting information of a custom audience cannot be set, creatives can be registered (Maximum: 10 creatives), and at least 30,000 estimated target population is required to optimize performance.	O

Response

Body

Name	Type	Description
populationScore	`Long`	Target population.

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/v4/targetings/populationScore" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -d '{
        "sectionCategories": [],
        "deviceTypes": [],
        "adServingCategories": [],
        "placements": ["KAKAO_TALK"],
        "campaignTypeGoal": {
            "id": 2,
            "campaignType": "TALK_CHANNEL",
            "goal": "REACH"
        },
        "targeting": {
            "ages": ["30"],
            "syncAppTargetings": [],
            "talkChannelGroupTargetings": [],
            "ufoInterests": [],
            "depth2Locations": [],
            "retargetingApps": [],
            "genders": [],
            "cohortTargetings": [],
            "plusFriendTargetings": [],
            "contents": [],
            "trackerTargetings": [],
            "id": -1,
            "ufoBusinessTypes": [],
            "customerFileTargetings": [],
            "audienceType": "NORMAL",
            "locations": []
        },
        "allAvailableDeviceType": true,
        "smartMessage": false,
        "allAvailablePlacement": false
        }'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "populationScore": 134
}

Cancel contract for Message ad group

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups/cancel/${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

Terminates the contract for an ad group under a Kakao Talk Channel X Reach campaign.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Path variable

Name	Type	Description	Required
ID	`Long`	Message ad group's ID.	O

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/cancel/${ID}" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json"

Response

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

Create Personalized message ad group

Basic information

Method	URL	Authorization
`POST`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	Business token

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

Creates an ad group for the Personalized message X Reach(도달) campaign.

Rate limit

This API limits the number of calls you can make to every five seconds per user account and ad account.

Execution strategy

Automatically set to CPMS.
Cost per sending is flexible and depends on the platform policy.

Execution target

Specify Service user ID or phone number when sending Personalized message API requests.

Obligations regarding personal information processing

When entrusting users' personal information to Kakao for the use of Kakao Advertising Integrated Services, advertisers must inform users of this fact. In addition, advertisers must use personal information only for the purpose agreed to by users in accordance with relevant laws.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name (Maximum: 50 characters). Automatically generated if omitted.	X

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`Enum: Config`	Ad group's status.
pricingType	`Enum: PricingType`	Pricing type. `CPMS`: Cost per Message Send
status	`Enum: Status[]`	Status.
placements	`Enum: Placement[]`	Placements where ads are displayed.
profileId	`String`	Kakao Talk Channel profile ID.
campaign	`Campaign`	Campaign.
creativeCount	`Long`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/v4/adGroups" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {
        "id": 1
    },
    "name": "Test Personalized message ad group"
}'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 1,
  "name": "Test Personalized message ad group",
  "config": "ON",
  "pricingType": "CPMS",
  "status": ["NO_AVAILABLE_CREATIVE"],
  "deviceTypes": ["ANDROID", "IOS"],
  "placements": ["KAKAO_TALK"],
  "profileId": "_Xxju",
  "campaign": {
    "id": 1,
    "name": "개인화 메시지_도달_202306150913",
    "campaignTypeGoal": {
      "campaignType": "PERSONAL_MESSAGE",
      "goal": "REACH"
    },
    "objective": {
      "type": "TALK_CHANNEL",
      "detailType": "SEND_MESSAGE",
      "value": "_Xxju"
    },
    "dailyBudgetAmount": null,
    "config": "ON",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 39543,
    "status": ["LIVE"],
    "systemConfig": "ON",
    "isDailyBudgetAmountOver": false
  },
  "creativeCount": 0,
  "systemConfig": "ON",
  "adult": false,
  "createdDate": "2023-06-16T14:14:15.124859",
  "lastModifiedDate": "2023-06-16T14:14:15.94692"
}

Edit Personalized message ad group

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	Business token

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

Edits the Personalized message ad group in detail.

You can edit the name, but other information is not editable.

Rate limit

This API limits the number of calls you can make to every five seconds per user account and ad account.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
id	`Long`	Ad group's ID.	O
name	`String`	Ad group's name (Maximum: 50 characters). If omitted, the previous name is kept.	X

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`Enum: Config`	Ad group's status.
pricingType	`Enum: PricingType`	Pricing type. `CPMS`: Cost per Message Send
status	`Enum: Status[]`	Status.
placements	`Enum: Placement[]`	Placements where ads are displayed.
profileId	`String`	Kakao Talk Channel profile ID.
campaign	`Campaign`	Campaign.
creativeCount	`Long`	Number of registered creatives.
systemConfig	`Enum: SystemConfig`	Ad group's system status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
createdDate	`String`	Date and time of ad group creation in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time of ad group modification in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "id": 11111,
        "campaign": {
            "id": 11111
        },
        "name": "Edit Personalized message ad group"
    }'

Response

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 1,
  "name": "Edit Personalized message ad group",
  "config": "ON",
  "pricingType": "CPMS",
  "status": ["NO_AVAILABLE_CREATIVE"],
  "deviceTypes": ["ANDROID", "IOS"],
  "placements": ["KAKAO_TALK"],
  "profileId": "_Xxju",
  "campaign": {
    "id": 1,
    "name": "개인화 메시지_도달_202306150913",
    "campaignTypeGoal": {
      "campaignType": "PERSONAL_MESSAGE",
      "goal": "REACH"
    },
    "objective": {
      "type": "TALK_CHANNEL",
      "detailType": "SEND_MESSAGE",
      "value": "_Xxju"
    },
    "dailyBudgetAmount": null,
    "config": "ON",
    "statusDescription": "운영중",
    "trackId": null,
    "adAccountId": 39543,
    "status": ["LIVE"],
    "systemConfig": "ON",
    "isDailyBudgetAmountOver": false
  },
  "creativeCount": 0,
  "systemConfig": "ON",
  "adult": false,
  "createdDate": "2023-06-16T14:14:15.124859",
  "lastModifiedDate": "2023-06-16T14:14:15.94692"
}

Change ad group status

Basic information

Method	URL	Authorization
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups/onOff`	Business token

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

Enables you to change the status of an ad group to ON or OFF.

Conditions for use

The ad group status can be changed only when it is ON or OFF.
Available only for ad groups under Display, Video, and Bizboard campaigns, except for the Reach goal, and Kakao Talk Channel campaigns.
Changing an ad group under a Kakao Talk Channel campaign to OFF stops messages being delivered and cancels scheduled messages.

Rate limit

This API limits the number of calls you can make to every second per user account, ad account, and ad group.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
config	`Enum: Config`	Ad group's status. `ON`: Activated `OFF`: Inactivated	O

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/onOff" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "id": 1234,
            "config": "ON"
        }'

Response

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

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 32001,
    "detailMsg": "광고그룹이 존재하지 않습니다."
  }
}

Delete ad group

Basic information

Method	URL	Authorization
`DELETE`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${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 an ad group.

Caution when deleting

Deleting does not mean removing the data, but rather relinquishing management of the sub-ad group.
You cannot delete ad groups under 'Kakao Bizboard X Reach', 'Daum Shopping' campaign types.
You can only delete an ad group if all of its creatives are deletable.
When an ad group is deleted, the following restrictions apply:
- All functions related to the ad group, such as editing or suspending, become unavailable.
- All ads under the ad group stop running and displaying.
- All creatives under the ad group are deleted.
- However, statistics from the operational period before deletion can still be viewed.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Path variable

Name	Type	Description	Required
ID	`Long`	Ad group's ID.	O

Sample

Request

curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json"

Response

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

Response: Fail

// HTTP/1.1 400 Bad request
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 75007,
    "detailMsg": "카카오톡 채널_도달 그룹은 삭제할 수 없습니다.",
    "path": "/v2/moment/adGroups",
    "timestamp": "2018-10-01T10:16:14.294+0000"
  }
}

View reason for system stop

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/latestSystemConfigHistory`	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 reason why the specified ad group's system is stopped.

Only when the value of systemConfig (Ad group's system status) is ADMIN_STOP or EXTERNAL_SERVICE_STOP, the response is returned. If there are multiple reasons for the system stop, the most recent reason is returned.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Path variable

Name	Type	Description	Required
ID	`Long`	Ad group's ID.	O

Response

Body

Name	Type	Description
id	`Long`	System stop ID.
systemConfig	`Enum: SystemConfig`	System status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
reason	`String`	Reason for the system stop.
detailReason	`String`	Detailed reason for the system stop. Only returned if a system reason exists.
createdDate	`String`	Date and time when the system stop reason is created in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time when the system stop reason is lastly updated in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/latestSystemConfigHistory" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Response

{
  "id": 1234,
  "systemConfig": "ADMIN_STOP",
  "reason": "해당 광고그룹은 관리자정지 조치 취해졌습니다.",
  "createdDate": "2021-01-01T00:00:00",
  "lastModifiedDate": "2021-01-01T00:00:00"
}

{
  "id": 1234,
  "systemConfig": "EXTERNAL_SERVICE_STOP",
  "reason": "채널 파트너센터에서 제재됨",
  "detailReason": "메시지 집행 가이드, 운영정책 위반으로 2022년 7월 15일까지 메시지 발송이 불가",
  "createdDate": "2021-01-01T00:00:00",
  "lastModifiedDate": "2021-01-01T00:00:00"
}

Response: Fail

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 32001,
    "detailMsg": "광고그룹이 존재하지 않습니다."
  }
}

View list of reasons for system stop

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/systemConfigHistories`	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 list of reasons why the specified ad group's system was stopped during the last two years.

Only when the value of systemConfig (Ad group's system status) is ADMIN_STOP or EXTERNAL_SERVICE_STOP, the response is returned.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Path variable

Name	Type	Description	Required
ID	`Long`	Ad group's ID.	O

Response

Body

Name	Type	Description
-	`SystemStopReason[]`	List of system stop reasons.

SystemStopReason

Name	Type	Description
id	`Long`	System stop ID.
systemConfig	`Enum: SystemConfig`	System status. `ON`: Activated `ADMIN_STOP`: Administrator suspended `EXTERNAL_SERVICE_STOP`: Linked service restricted
reason	`String`	Reason for the system stop.
detailReason	`String`	Detailed reason for the system stop. Only returned if a system reason exists.
createdDate	`String`	Date and time when the system stop reason is created in `yyyy-MM-dd'T'HH:mm:ss` format.
lastModifiedDate	`String`	Date and time when the system stop reason is lastly updated in `yyyy-MM-dd'T'HH:mm:ss` format.

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/systemConfigHistories" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Response

[
  {
    "id": 1235,
    "systemConfig": "ADMIN_STOP",
    "reason": "해당 광고그룹은 관리자정지 조치 취해졌습니다.",
    "createdDate": "2021-01-01T00:00:00",
    "lastModifiedDate": "2021-01-01T00:00:00"
  },
  {
    "id": 1234,
    "systemConfig": "EXTERNAL_SERVICE_STOP",
    "reason": "채널 파트너센터에서 제재됨",
    "detailReason": "메시지 집행 가이드, 운영정책 위반으로 2022년 7월 15일까지 메시지 발송이 불가",
    "createdDate": "2021-01-01T00:00:00",
    "lastModifiedDate": "2021-01-01T00:00:00"
  }
]

Response: Fail

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 32001,
    "detailMsg": "광고그룹이 존재하지 않습니다."
  }
}

See more

Kakao Moment API Reference

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

Ad creation: Ad group

View list of ad groups

Basic information

Request

Header

Query parameter

Response

Body

AdGroup

Sample

Request

Response

View ad group

Basic information

Request

Header

Path variable

Response

Body: Display ad group

Body: Message ad group

Sample

Request

Response

Response: Fail

Create Display ad group

Basic information

Delivery strategies settings

Bidding method

Default, minimum, and maximum values by bidding method

Delivery strategies

Daily budget for a group

Delivery period

Rate limit

Request

Header

Body

Campaign

Targeting

TalkChannelGroupTargeting

CustomerFileTargeting

TrackerTargeting

CohortTargeting

TalkChannelTargeting

SyncAppTargeting

Response

Body

Sample

Request

Response

Edit Display ad group

Basic information

Rate limit

Request

Header

Body

Campaign

Targeting

Response

Body

Sample

Request

Response

Edit daily budget for Display ad group

Basic information

Daily budget conditions

Rate limit

Request

Header

Body