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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves a list of ad groups.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns a list of each ad group's detailed information in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header

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

Query parameter

Name	Type	Description	Required
campaignId	`Long`	Campaign's ID.	O
config	`String[]`	Ad group's status. Use one or more of the followings: `ON` `OFF` `DEL` (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	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
userConfig	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted). Note: `userConfig` has the same value as `config`. This field is deprecated and provided for reference.
systemConfig	`String`	Ad group's system status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves the detailed information of the specified ad group.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the detailed information of the ad group by type in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
pacing	`Pacing`	Spending method. One of `NONE`, `QUICK`, or `NORMAL`.
pricingType	`PricingType`	Pricing type. One of `CPM`, `CPC`, or `CPA`.
bidAmount	`Integer`	Maximum bid.
bidStrategy	`String`	Bidding method. One of `MANUAL` (Manual bidding), `AUTOBID` (Automatic bidding), or `OPTIMIZATION` (Optimized bidding for purpose).
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.
statusDescription	`String`	Status of the ad group.
status	`String[]`	Status. Refer to `Status`.
optimizationStatus	`String[]`	Status of optimization. Refer to `OptimizationStatus`.
deviceTypes	`EnumSet of DeviceType[]`	Device type.
adServingCategories	`String[]`	Categories under Network for ad placements.
sectionCategories	`String[]`	Section category. Provided only for the 'Kakao Bizboard' type of campaign through the '채팅탭에만 노출(Only displayed in Chat tab) option as of now.
placements	`EnumSet of 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	`String`	Ad group's system status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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.
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	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
smartMessage	`Boolean`	Whether to use a Smart message.
pricingType	`PricingType`	Pricing type. CPMS
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	`String[]`	Status. Refer to `Status`.
placements	`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	`String`	Ad group's system status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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.
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",
                "desrciption" : "경기도 여주시",
                "depth1Name": "경기도",
                "depth2Name": "여주시"
            },
            {
                "value" : "I1009",
                "desrciption" : "서울특별시 도봉구",
                "depth1Name": "광주광역시",
                "depth2Name": "도봉구"
            }
        ],
        "depth3Locations" : [
            {
                "value" : "A70052424",
                "desrciption" : "강원도 삼척시 원덕읍",
                "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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Creates a Display ad group under a campaign.

When requesting this API, you need to specify parameters by referring to the following information about the targeting settings and delivery strategies.

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. * Input range: minimum value (defined by each campaign preset) to maximum value (100,000 won or 50 % of your daily budget set for the ad group) * Unit of input amount: 1 won (KRW) * Default: Depending on the values 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.
	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. * The target bid amount is required. * Input range: from 10 won to the maximum value (10,000 won or 50 % of your daily budget set for the ad group) * Unit of input amount: 1 won (KRW)
	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. * The target bid amount is required. * Input range: from 100 won to the maximum value (1,000,000 won or 50 % of your daily budget set for the ad group) * Unit of input amount: 1 won (KRW)
	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. * The target ROAS is required. * Input range: from 10% to 100,000% * Unit of input amount: 1%

Default, minimum, and maximum values by bidding method

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

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 between 10,000 and 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.

Send a POST request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the detailed information of the created ad group. If failed, refer to Error code to figure out its failure cause.

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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name. Character limits: 50 characters If you do not specify, the name specified when creating the ad group is used.	X
placements	`String[]`	Ad placements. Use one or more of the followings: `KAKAO_SERVICE` `KAKAO_TALK` `DAUM` `NETWORK`	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 Viewing categories of Network for placements API.	O*
sectionCategories	`String[]`	Section category. Allowed only if the campaign type is 'Kakao Bizboard', and if `placements` is set to `KAKAO_TALK`. Use `code` that is passed in the response of the Viewing categories of Network for placements API.	X
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Allowed to set it to `true` if the campaign type is either 'Kakao Talk Channel X Reach' visit, 'Video X View' or 'Display X Conversion' of which ObjectiveDetailType is PURCHASE, COMPLETE_REGISTRATION, SIGN_UP, CART or PARTICIPATION. If not included in request, `true` is passed. If you set it to `true`, you must set `deviceTypes` to `["ANDROID", "IOS", "PC"]` as an array of strings.	X
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. If not included in request, `true` is passed. Allowed to set it to `true` only if the campaign type is 'Display', 'Video', or 'Kakao Bizboard'.	X
deviceTypes	`String[]`	Device type. Use one or more of the followings: `ANDROID` `IOS` `PC` If the campaign type is not ‘Display X Visit’ or ‘Video X View,’ only `ANDROID` and `IOS` can be passed. If you set `allAvailableDeviceType` to `true`, you must pass all of `ANDROID`, `IOS`, and `PC`.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting. If you set it to `true`, advertisements can only be exposed to people aged 20 or older. Pass "20","25","30","35","40","45","50","55","60","65","70" in `targeting.ages`. If not included in request, `false` is passed.	X
dailyBudgetAmount	`Integer`	Daily budget.	O
bidStrategy	`String`	Bidding method. Either `MANUAL` or `AUTOBID`.	O
pricingType	`String`	Manual payments. One of `CPA`, `CPM`, `CPC`, or `CPV`	O
bidAmount	`Integer`	Bid amount for manual payments. Set to 0 for automatic bidding.	O
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.	X
pacing	`String`	Spending method. Possible values vary depending on the bidding method, see below. Bidding method `MANUAL`: Either `NORMAL` or `QUICK` Bidding method `AUTOBID`: `NONE`	O
schedule	`Schedule`	Schedule information.	O

* Required parameter only when certain conditions are met. In other other cases, optional.

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	`String`	Whether to use Audience. One of `NORMAL`, `DISPLAY`, or `MESSAGE`. `NORMAL`: General targeting. `DISPLAY`: Use the set Display Audience. `MESSAGE`: Use the set Message Audience. If you set it to `DISPLAY` or `MESSAGE`, pass the empty value for the rest target information. If the ad type is `DISPLAY`, you must set the audience type to `DISPLAY`.	X
ageType	`String`	Selection type for age range. Either `All` or `NOT_ALL`. `ALL`: Select all age ranges. `NOT_ALL`: Select some age ranges. If you set `adult` (Whether to use adult targeting) to `true`, use `NOT_ALL`.	O
ages	`String[]`	Age range. Use one or more of the followings: `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 Only allowed if `ageType` is set to `NOT_ALL`. If you set `ageType` to `ALL`, do not pass `ages`. 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.	O*
genderType	`String`	Selection type for gender. Either `All` or `NOT_ALL`. `ALL`: Select all genders. `NOT_ALL`: Select a specific gender.	O
genders	`String[]`	Gender. Use one or more of the followings: `M`: Male. `F`: Female. Required if `genderType` is set to `NOT_ALL`. If you set `genderType` to `ALL`, do not pass `genders`.	O*
ufoInterests	`Set of UfoInterest`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [관심사(Interests)] Refer to View category data for custom audience targeting.	X
ufoBusinessTypes	`Set of UfoBusinessType`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [업종(Industries)] Refer to View category data for custom audience targeting.	X
locationType	`String`	Selection type for areas. Either `All` or `AREA`. `ALL`: Select all areas. `AREA`: Select some areas.	O
locations	`Set of Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/도(-si/do)] Refer to View city/province. Not allowed if `locationType` is set to `ALL`. Allowed to pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). If the campaign type is 'Kakao Bizboard', Overseas(Z) is not allowed.	X
depth2Locations	`Set of Depth2Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/군/구(-si/gun/gu)] Refer to View city/county/district. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
depth3Locations	`Set of Depth3Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [동/읍/면(-dong/eup/myeon)] Refer to View dong/eup/myeon. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
`customerFileTargetings`	`Set of CustomerFileTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [고객파일(Customer file]) Use the information retrieved through the Viewing list of targetable customer files API.	X
trackerTargetings	`Set of TrackerTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [픽셀 & SDK(Pixel & SDK)] Use the information retrieved through the Viewing targetable Pixel & SDK events API.	X
cohortTargetings	`Set of CohortTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [광고반응타겟(Engagement target)] Use the information retrieved through the Viewing targetable Engagement target API.	X
talkChannelTargetings	`Set of TalkChannelTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오톡 채널 친구(Kakao Talk Channel friend)] Use the information retrieved through the Viewing list of targetable Kakao Talk Channels API.	X
syncAppTargetings	`Set of SyncAppTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user) > [카카오 로그인 이용자(Kakao Login user)] Use the information retrieved through the Viewing list of targetable Kakao Talk Channels API.	X
`talkChannelGroupTargetings`	`Set of TalkChannelGroupTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [친구그룹(Friend group)] Use the information retrieved through the Viewing 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	`String`	Whether to include or exclude the information extracted from a Friend group file for ad group targeting. Either `INCLUDE` or `EXCLUDE`.	O
fileType	`String`	Friend group's type. One of the followings: `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	`String`	Whether to include or exclude the information extracted from a customer file for ad group targeting. Either `INCLUDE` or `EXCLUDE`.	O

TrackerTargeting

Name	Type	Description	Required
trackId	`String`	Tracking ID.	O
inclusionType	`String`	Whether to include or exclude the information extracted from a Pixel & SDK event for ad group targeting. Either `INCLUDE` or `EXCLUDE`.	O
eventCode	`String`	Event code. Pass `*` to request '모든 이벤트(All events)'.	O
trackRuleId	`String`	Track Rule ID.	O
trackRuleName	`String`	Track Rule name.	O
term	`Integer`	Targeting period. (Min: 1, Max: 180)	O

CohortTargeting

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

TalkChannelTargeting

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

SyncAppTargeting

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

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
pacing	`Pacing`	Spending method. One of `NONE`, `QUICK`, or `NORMAL`.
pricingType	`PricingType`	Pricing type. One of `CPM`, `CPC`, `CPA`, or `CPV`.
bidAmount	`Integer`	Maximum bid.
bidStrategy	`String`	Bidding method. One of `MANUAL` (Manual bidding), `AUTOBID` (Automatic bidding), or `OPTIMIZATION` (Optimized bidding for purpose).
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.
statusDescription	`String`	Status of the ad group.
status	`String[]`	Status. Refer to `Status`.
optimizationStatus	`String[]`	Status of optimization. Refer to `OptimizationStatus`.
deviceTypes	`EnumSet of DeviceType[]`	Device type.
adServingCategories	`String[]`	Categories under Network for ad placements.
sectionCategories	`String[]`	Section category. Provided only for the 'Kakao Bizboard' type of campaign through the '채팅탭에만 노출(Only displayed in Chat tab) option as of now.
placements	`EnumSet of 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	`String`	Ad group's system status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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.
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",
                        "desrciption" : "경기도 여주시",
                        "depth1Name": "경기도",
                         "depth2Name": "여주시"
                    },
                    {
                        "value" : "I1009",
                        "desrciption" : "서울특별시 도봉구",
                        "depth1Name": "광주광역시",
                        "depth2Name": "도봉구"
                    }
                ],
        "depth3Locations" : [
                {
                "value" : "A70052424",
                "desrciption" : "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
                },
                {
                "value" : "E13010702",
                "desrciption" : "광주광역시 남구 백운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",
                "desrciption" : "경기도 여주시",
                "depth1Name": "경기도",
                "depth2Name": "여주시"
            },
            {
                "value" : "I1009",
                "desrciption" : "서울특별시 도봉구",
                "depth1Name": "광주광역시",
                "depth2Name": "도봉구"
            }
        ],
        "depth3Locations" : [
            {
                "value" : "A70052424",
                "desrciption" : "강원도 삼척시 원덕읍",
                "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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

Send a PUT request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the changed information of the ad group in JSON format. If failed, refer to Error code to figure out its failure cause.

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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name. Character limits: 50 characters If you do not specify, the name specified when creating the ad group is used.	X
placements	`String[]`	Ad placements. Use one or more of the followings: `KAKAO_SERVICE` `KAKAO_TALK` `DAUM` `NETWORK`	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 Viewing categories of Network for placements API.	O*
sectionCategories	`String[]`	Section category. Allowed only if the campaign type is 'Kakao Bizboard', and if `placements` is set to `KAKAO_TALK`. Use `code` that is passed in the response of the Viewing list of section categories API.	X
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Allowed to set it to `true` if the campaign type is 'Kakao Talk Channel X Reach' visit, or 'Display X Conversion' of which ObjectiveDetailType is PURCHASE, COMPLETE_REGISTRATION, SIGN_UP, CART or PARTICIPATION. If not included in request, `true` is passed. If you set it to `true`, you must set `deviceTypes` to `["ANDROID", "IOS", "PC"]` as an array of strings.	X
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. Allowed to set it to `true` only if the campaign type is 'Display', 'Video', or 'Kakao Bizboard'. If not included in request, `true` is passed.	X
deviceTypes	`String[]`	Device type. Use one or more of the followings: `ANDROID` `IOS` `PC` If the campaign type is not ‘Display X Visit’ or ‘Video X View,’ only `ANDROID` and `IOS` can be passed. If you set `allAvailableDeviceType` to `true`, you must pass all of `ANDROID`, `IOS`, and `PC`.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting. If you set it to `true`, advertisements can only be exposed to people aged 20 or older. Pass "20","25","30","35","40","45","50","55","60","65","70" in `targeting.ages`. After you choose to use adult targeting when creating an ad group, you cannot set it to 'Not use'. If not included in request, `false` is passed.	X
dailyBudgetAmount	`Integer`	Daily budget.	O
bidStrategy	`String`	Bidding method. Either `MANUAL` or `AUTOBID`.	O
pricingType	`String`	Manual payments. One of `CPA`, `CPM`, `CPC`, or `CPV`.	O
bidAmount	`Integer`	Bid amount for manual payments. Set to 0 for automatic bidding.	O
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.	X
pacing	`String`	Spending method. Allowed only if the bidding method is set to `MANUAL`. Use one of the followings: `NORMAL`: Normal spending. `QUICK`: Quick spending. `NONE`: Disable this option. If you create an ad group under the 'Kakao Bizboard X Conversion(전환)' type of campaign, set it to `NONE`.	O
schedule	`Schedule`	Schedule information.	O

* Required parameter only when certain conditions are met. In other other cases, optional.

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	`String`	Whether to use Audience. One of `NORMAL`, `DISPLAY`, or `MESSAGE`. `NORMAL`: General targeting. `DISPLAY`: Use the set Display Audience. `MESSAGE`: Use the set Message Audience. If you set it to `DISPLAY` or `MESSAGE`, pass the empty value for the rest target information. If the ad type is `DISPLAY`, you must set the audience type to `DISPLAY`.	X
ageType	`String`	Selection type for age range. Either `All` or `NOT_ALL`. `ALL`: Select all age ranges. `NOT_ALL`: Select some age ranges. If you set `adult` (Whether to use adult targeting) to `true`, use `NOT_ALL`.	O
ages	`String[]`	Age range. Use one or more of the followings: `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 Only allowed if `ageType` is set to `NOT_ALL`. If you set `ageType` to `ALL`, do not pass `ages`. 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.	O*
genderType	`String`	Selection type for gender. Either `All` or `NOT_ALL`. `ALL`: Select all genders. `NOT_ALL`: Select a specific gender.	O
genders	`String[]`	Gender. Use one or more of the followings: `M`: Male. `F`: Female. Required if `genderType` is set to `NOT_ALL`. If you set `genderType` to `ALL`, do not pass `genders`.	O*
ufoInterests	`Set of UfoInterest`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [관심사(Interests)] Refer to View category data for custom audience targeting.	X
ufoBusinessTypes	`Set of UfoBusinessType`	[맞춤타겟(Custom audience target)] > [추가 설정(Additional settings)] > [카테고리(Categories)] > [업종(Industries)] Refer to View category data for custom audience targeting.	X
locationType	`String`	Selection type for areas. Either `All` or `AREA`. `ALL`: Select all areas. `AREA`: Select some areas.	O
locations	`Set of Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/도(-si/do)] Refer to View city/province. Not allowed if `locationType` is set to `ALL`. Allowed to pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). If the campaign type is 'Kakao Bizboard', Overseas(Z) is not allowed.	X
depth2Locations	`Set of Depth2Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [시/군/구(-si/gun/gu)] Refer to View city/county/district. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
depth3Locations	`Set of Depth3Location`	[데모그래픽(Demographic)] > [행정구역(Administrative area)] > [동/읍/면(-dong/eup/myeon)] Refer to View dong/eup/myeon. If `locationType` is set to `AREA`, you must pass one of `locations` (-si/do), `depth2Locations` (-si/gun/gu), or `depth3Locations` (-dong/eup/myeon). You can also pass all of three parameters.	X
customerFileTargetings	`Set of CustomerFileTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [고객파일(Customer file]) Use the information retrieved through the Viewing list of targetable customer files API.	X
trackerTargetings	`Set of TrackerTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [픽셀 & SDK(Pixel & SDK)] Use the information retrieved through the Viewing targetable Pixel & SDK events API.	X
cohortTargetings	`Set of CohortTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [광고반응타겟(Engagement target)] Use the information retrieved through the Viewing targetable Engagement target API.	X
talkChannelTargetings	`Set of TalkChannelTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user)] > [카카오톡 채널 친구(Kakao Talk Channel friend)] Use the information retrieved through the Viewing list of targetable Kakao Talk Channels API.	X
syncAppTargetings	`Set of SyncAppTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [카카오 사용자(Kakao user)] > [카카오 로그인 이용자(Kakao Login user)] Use the information retrieved through the Viewing list of targetable Kakao Talk Channels API.	X
talkChannelGroupTargetings	`Set of TalkChannelGroupTargeting`	[맞춤타겟(Custom audience target)] > [내 데이터 설정(My data settings)] > [친구그룹(Friend group)] Use the information retrieved through the Viewing 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	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
pacing	`Pacing`	Spending method. One of `NONE`, `QUICK`, or `NORMAL`.
pricingType	`PricingType`	Pricing type. One of `CPM`, `CPC`, `CPA`, or `CPV`.
bidAmount	`Integer`	Maximum bid.
bidStrategy	`String`	Bidding method. One of `MANUAL` (Manual bidding), `AUTOBID` (Automatic bidding), or `OPTIMIZATION` (Optimized bidding for purpose).
bidStrategyTarget	`BidStrategyTarget`	Automatic bidding option.
statusDescription	`String`	Status of the ad group.
status	`String[]`	Status. Refer to `Status`.
optimizationStatus	`String[]`	Status of optimization. Refer to `OptimizationStatus`.
deviceTypes	`EnumSet of DeviceType[]`	Device type.
adServingCategories	`String[]`	Categories under Network for ad placements.
sectionCategories	`String[]`	Section category. Provided only for the 'Kakao Bizboard' type of campaign through the '채팅탭에만 노출(Only displayed in Chat tab) option as of now.
placements	`EnumSet of 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	`String`	Ad group's system status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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.
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",
                        "desrciption" : "경기도 여주시",
                       "depth1Name": "경기도",
                       "depth2Name": "여주시"
                        },
                        {
                        "value" : "I1009",
                        "desrciption" : "서울특별시 도봉구",
                        "depth1Name": "광주광역시",
                        "depth2Name": "도봉구"
                        }
                    ],
                "depth3Locations" : [
                        {
                        "value" : "A70052424",
                        "desrciption" : "강원도 삼척시 원덕읍",
                      "depth1Name": "강원도",
                      "depth2Name": "삼척시",
                     "depth3Name": "원덕읍"
                        },
                        {
                        "value" : "E13010702",
                        "desrciption" : "광주광역시 남구 백운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",
                "desrciption" : "경기도 여주시",
                "depth1Name": "경기도",
                "depth2Name": "여주시"
            },
            {
                "value" : "I1009",
                "desrciption" : "서울특별시 도봉구",
                "depth1Name": "광주광역시",
                "depth2Name": "도봉구"
            }
        ],
        "depth3Locations" : [
            {
                "value" : "A70052424",
                "desrciption" : "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
            },
            {
                "value" : "E13010702",
                "desrciption" : "광주광역시 남구 백운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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

You can set a daily budget for an ad group from 10,000 to 500 million won (South Korean won) in multiples of 10 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.

Send a PUT request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

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

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Edits the maximum bid amount of your Display ad group.

You can edit only the ad group's maximum bid amount under the campaign with the Display, Video, or Bizboard type except for the 'Reach(도달)' goal.

The minimum bid amount is applied differently depending on the ad group type, ad purpose, and pricing type. Also, the bid amount cannot exceed 50 % of your daily budget set for the ad group or the maximum value of 100,000 won (KRW). API

Default and minimum values of the bid amount

Ad Type	Maximum bid (Manual bidding)
Display	Default CPA : 1,500 CPC : 200 CPM : 1,000 Minimum CPA : 100 CPC : 10 CPM : 100 Maximum Lower value bewteen 100,000 won and 50 % of the ad group's daily budget.
Kakao Bizboard	Default CPC : 200 CPM : 3,000 Minimum CPC : 10 CPM : 1,000 Maximum Lower value bewteen 100,000 won and 50 % of the ad group's daily budget.
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.

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

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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 spending method for Display ad group

Basic information

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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Enables you to edit the spending method for your Display ad group.

You can edit only the ad group's spending method under the campaign with the Display, Video, or Bizboard type except for 'Reach(도달)' goal. Also, you can edit the spending method only if the bidding method is set to MANUAL.

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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
pacing	`String`	Spending method. Allowed only if the bidding method is set to `MANUAL`. Use either `NORMAL` or `QUICK`. `NORMAL`: Controls ad impression by spending the time-specific budget not to exceed the daily budget set for the ad group. `QUICK`: Spends your budget as quickly as possible to increase ad impression and reach your goal.	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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

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 Retrieving 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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name. Character limits: 50 characters If you do not specify, the name specified when creating the ad group is used.	X
placements	`String[]`	Ad placements. Fixed to `KAKAO_TALK`.	O
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Fixed to `false`.	O
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. Only `false` is allowed.	O
deviceTypes	`String[]`	Device type. Use either `ANDROID` or `IOS`.	O
messageSendingInfo	`MessageSendingInfo`	Message information.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting. Pass `false` (Not use adult targeting).	O
bidStrategy	`String`	Bidding method. Fixed to `MANUAL`.	O
pricingType	`String`	Manual payments. Fixed to `CPMS`.	O
bidAmount	`Integer`	Bid amount for manual payments (Pricing for sending a message). Pass the same value as `price` of `MessageSendingInfo` (Message information).	O
pacing	`String`	Spending method. Fixed to `NONE`.	O
schedule	`Schedule`	Schedule information.	O
smartMessage	`Boolean`	Whether to use a Smart message. Smart messages function to find the audiences who are similar to the friends who clicked the creative based on the data collected in real-time while sending messages, and then send messages to the lookalike audiences. To optimize performance, you can only send messages to the friends of the channels that have 100,000 friends or more, and send messages to up to 50 % of the friends. You cannot set targeting information for custom audience targeting. If you use the Smart message, the high-performing creatives are exposed more to improve the efficiency of ad group. To optimize performance, you can register up to 10 creatives and need at least 30,000 estimated target population for sending messages.	O

MessageSendingInfo

Name	Type	Description	Required
contractCount	`Integer`	Available number of sending messages. Cannot set the value less than the estimated target population for sending message.	O
longTerm	`Boolean`	Whether to use the '전체발송 후 새 친구에게도 보내기(Send to new friends after sending all messages)' option. If using this option, you must pass `beginDate` (Start date), `beginTime` (Start time), `endDate` (End date), and `endTime` (End time) for the `schedule` field, and set `allAvailableDeviceType` to `true`.	O
price	`Long`	Depending on the set targeting information, the pricing per message is differently applied. The targeting message is charged 20 won per message. The basic message is charged 15 won per message.	O
pushAlarm	`Boolean`	Whether to use the '푸시알림 보내지 않기(Not send push notifications)' option. `true`: Not send push notifications. `false`: Send push notifications.	O
sendRate	`Integer`	Set the message sending rate required for the 분산발송(Distributed sending) option. Use one of the numbers: `100`, `500`, `1000`, `1500`, `2000`: Set the number of messages that are sent at once. `0`: Not use the Distributed sending option.	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	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
smartMessage	`Boolean`	Whether to use a Smart message.
pricingType	`PricingType`	Pricing type. CPMS
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	`String[]`	Status. Refer to `Status`.
placements	`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	`String`	Ad group's system status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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.
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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group's name. Character limits: 50 characters If you do not specify, the name specified when creating the ad group is used.	X
placements	`String[]`	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 Viewing categories of Network for placements API.	O*
sectionCategories	`String[]`	Section category. Allowed only if the campaign type is 'Kakao Bizboard', and if `placements` is set to `KAKAO_TALK`. Use `code` that is passed in the response of the Viewing categories of Network for placements API.	X
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Fixed to `false`.	O
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. Allowed to set to `false` only.	O
deviceTypes	`String[]`	Device type. Use either `ANDROID` or `IOS`.	O
messageSendingInfo	`MessageSendingInfo`	Message information.	O
targeting	`Targeting`	Targeting.	O
adult	`Boolean`	Whether to use adult targeting. Pass `false` (Not use adult targeting).	O
dailyBudgetAmount	`Integer`	Daily budget.	O
bidStrategy	`String`	Bidding method. Fixed to `MANUAL`.	O
pricingType	`String`	Manual bidding method. Fixed to `CPMS`.	O
smartMessage	`Boolean`	Whether to use a Smart message. Smart messages function to find the audiences who are similar to the friends who clicked the creative based on the data collected in real-time while sending messages, and then send messages to the lookalike audiences. To optimize performance, you can only send messages to the friends of the channels that have 100,000 friends or more, and send messages to up to 50 % of the friends. You cannot set targeting information for custom audience targeting. If you use the Smart message, the high-performing creatives are exposed more to improve the efficiency of ad group. To optimize performance, you can register up to 10 creatives and need at least 30,000 estimated target population for sending messages.	O
bidAmount	`Integer`	Bid amount for manual payments. (Pricing for sending a message) Pass the same value as `price` of `MessageSendingInfo` (Message information).	O
pacing	`String`	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	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
smartMessage	`Boolean`	Whether to use a Smart message.
pricingType	`PricingType`	Pricing type. CPMS
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	`String[]`	Status. Refer to `Status`.
placements	`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	`String`	Ad group's system status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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.
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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves the estimated target population that is used to enter the number of sending messages, which is required for creating or editing ad groups under the campaign with 'Kakao Talk Channel X Reach(도달)' type.

Send a POST request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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(도달)'.	O*
placements	`String[]`	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 Viewing categories of Network for placements API.	O*
allAvailableDeviceType	`Boolean`	Whether to display ads on all available devices. Fixed to `false`.	O
allAvailablePlacement	`Boolean`	Whether to display ads on all available places. Only `false` is allowed.	O
deviceTypes	`String[]`	Device type. Use either `ANDROID` or `IOS`.	O
targeting	`Targeting`	Targeting information.	O
smartMessage	`Boolean`	Whether to use a Smart message. Smart messages function to find the audiences who are similar to the friends who clicked the creative based on the data collected in real-time while sending messages, and then send messages to the lookalike audiences. To optimize performance, you can only send messages to the friends of the channels that have 100,000 friends or more, and send messages to up to 50 % of the friends. You cannot set targeting information for custom audience targeting. If you use the Smart message, the high-performing creatives are exposed more to improve the efficiency of the ad group. To optimize performance, you can register up to 10 creatives and need at least 30,000 estimated target population for sending messages.	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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Enables you to cancel the contract about an ad group under the 'Kakao Talk Channel X Reach(도달)' campaign.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

Send a POST request with the business token and the ad account ID in the header. If the request is successful, the response includes the information of the ad group in JSON object. If failed, refer to Error code to figure out its failure cause.

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

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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
name	`String`	Ad group' name. If you do not specify, the name specified when creating the ad group is used. (Maximum: 50 characters)	X

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
pricingType	`PricingType`	Pricing type. CPMS
status	`Status`	Status.
placements	`Placement`	Placements where ads are displayed.
profileId	`String`	Kakao Talk Channel profile ID.
campaign	`Campaign`	Campaign.
creativeCount	`Long`	Number of registered creatives.
systemConfig	`String`	Ad group's system status. One of the followings: ON: Available to run ads. ADMIN_STOP: Unavailable to run ads because the administrator is suspended. EXTERNAL_SERVICE_STOP: Unavailable to run ads because the linked service is 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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Edits the Personalized message ad group in detail.

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

Send a PUT request with an Business token and the ad account ID in the header. If the request is successful, the response includes the modified ad group information. If failed, refer to Error code to figure out its failure cause.

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

Request

Header

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

Body

Name	Type	Description	Required
campaign	`Campaign`	Campaign.	O
id	`Long`	Ad group's ID.	O
name	`String`	Ad group' name. If you do not specify, the name specified when creating the ad group is used. (Maximum: 50 characters)	X

Response

Body

Name	Type	Description
id	`Long`	Ad group's ID.
name	`String`	Ad group's name.
config	`String`	Ad group's status. One of `ON`, `OFF`, or `DEL` (Deleted).
pricingType	`PricingType`	Pricing type. CPMS
status	`Status`	Status.
placements	`Placement`	Placements where ads are displayed.
profileId	`String`	Kakao Talk Channel profile ID.
campaign	`Campaign`	Campaign.
creativeCount	`Long`	Number of registered creatives.
systemConfig	`String`	Ad group's system status. One of the followings: ON: Available to run ads. ADMIN_STOP: Unavailable to run ads because the administrator is suspended. EXTERNAL_SERVICE_STOP: Unavailable to run ads because the linked service is 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 '{
        "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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

Only if the ad group's status is ON or OFF, you can change the status of the ad groups under the campaign with the 'Display', 'Video', 'Bizboard' (except for the 'Reach(도달)' goal), or 'Kakao Talk Channel' type.

If you change the status of the ad group under the 'Kakao Talk Channel' type of campaign to OFF, the messages being sent are stopped and the messages scheduled to be sent are canceled.

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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Body

Name	Type	Description	Required
id	`Long`	Ad group's ID.	O
config	`String`	Ad group's status. Either `ON` or `OFF`.	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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Deletes an ad group.

Send a DELETE request with the issued business token and an ad account ID (adAccountId) in the request header. You must pass the ad group's ID as a parameter when you request. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

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', or 'Kakao TV' 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	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

Send a GET request with the issued business token in the request header. If the request is successful, this API returns the system stop reason and details in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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	`String`	System status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves the list of reasons why the specified ad group's system is stopped, which occurred for 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.

Send a GET request with the issued business token in the request header. If the request is successful, this API returns the list of the system stop reasons and details in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's 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	`String`	System status. One of the followings: `ON`: Available to run ads. `ADMIN_STOP`: Unavailable to run ads because the administrator is suspended. `EXTERNAL_SERVICE_STOP`: Unavailable to run ads because the linked service is 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

Kakao 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

Request

Header

Body

Campaign

Targeting

TalkChannelGroupTargeting

CustomerFileTargeting

TrackerTargeting

CohortTargeting

TalkChannelTargeting

SyncAppTargeting

Response

Body

Sample

Request

Response

Edit Display ad group

Basic information

Request

Header

Body

Campaign

Targeting

Response

Body

Sample

Request

Response

Edit daily budget for Display ad group

Basic information

Request

Header

Body

Sample

Request

Response

Response: Fail