페이지 이동경로
  • Docs>
  • Kakao Moment>
  • Ad creation: Ad group

Kakao Moment

Ad creation: Ad group

This document describes how to use the Ad group APIs.

View list of ad groups

This API enables you to retrieve a list of ad groups.

Send a GET request with the issued access 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

URL
GET /openapi/v4/adGroups HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Query
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

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).
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
Display ad group
Message ad group
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "content": [
    {
      "id": 1111,
      "name": "ad_group_1",
      "config": "ON", 
      "systemConfig": "ON"
    },
    {
      "id": 1112,
      "name": "ad_group_2",
      "config": "OFF",
      "systemConfig": "ADMIN_STOP"
    }
  ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "content": [
    {
      "id": 1111,
      "name": "message_ad_group_1",
      "config": "ON",
      "systemConfig": "ON"
    },
    {
      "id": 1112,
      "name": "message_ad_group_2",
      "config": "OFF",
      "systemConfig": "EXTERNAL_SERVICE_STOP"
    }
  ]
}

View ad group

This API enables you to retrieve the detailed information of the specified ad group.

Send a GET request with the issued access 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

URL
GET /openapi/v4/adGroups/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Ad group's ID. O

Response

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).
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.
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 as 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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response: Success
Display ad group
Message ad group
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
}
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",
}
Response: Fail
Display ad group
Message ad group
HTTP/1.1 400 Bad request
Content-Type: application/json;charset=UTF-8
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 32001,
        "detailMsg": "광고그룹이 존재하지 않습니다."
    }
}
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

This API enables you to create a Display ad group under a campaign, except for the 'Sponsored board', 'Daum Shopping', 'Video', and 'Kakao Bizboard X Reach(도달)' type of 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
Set the maximum bid amount.
1. You can bid with the input bid amount but are charged less than the input value.
2. You can set the actual bid amount by creative, but cannot exceed the maximum bid amount set for the ad group.
* 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)
* Allowed to input a value in multiples of 10 won (KRW).
* Default: Depending on the values defined by each campaign preset.
Automatic bidding Maximizing the number of clicks

Maximizing the number of conversions
Set the maximum bid limit.
Bid with the amount less than the input value.
* Not required.
* Input range: 10 won (KRW) to the maximum value (100,000 won or 50 % of your daily budget set for the ad group.)
* Allowed to input a value in multiples of 10 won (KRW).
* Default: Not specified.
Default, minimum, and maximum values by bidding method
Ad Type Maximum bid (Manual bidding) Daily average bid limit (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.
Default
Maximizing the number of clicks: 200

Minimum
Maximizing the number of clicks: 10

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.
Kakao Bizboard Default
CPC : 200
CPM : 3,000

Minimum
CPC : 10
CPM : 1,000

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

Minimum
Maximizing the number of clicks: 10

Maximum
Smaller value between 100,000 won (KRW) and 50 % of your daily budget set for the ad group.
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 strategies: 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 access 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

URL
POST /openapi/v4/adGroups HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
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_STROY
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 false only if the campaign type is 'Kakao Talk Channel X Reach'.

If you set it to true, you must set deviceTypes to ["ANDROID", "IOS", "PC"] as an array of strings.
O
allAvailablePlacement Boolean Whether to display ads on all available places.
Allowed to set it to true only if the campaign type is 'Display' or 'Kakao Bizboard'.
O
deviceTypes String[] Device type.
Use one or more of the followings:
ANDROID
IOS
PC
If the campaign type is not 'Display X Visit', you can pass ANDROID and IOS only.
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.
Adult targeting functions to run ads only for those who are 20 years or older.
If you set it to true, you cannot request targeting.ages.
O
dailyBudgetAmount Integer Daily budget. O
bidStrategy String Bidding method.
Either MANUAL or AUTOBID.
O
pricingType String Manual payments.
One of CPA, CPM, or CPC.
O
bidAmount Integer Bid amount for manual payments. O
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
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" 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. O
trackRuleId String Track Rule ID. O
trackRuleName String Track Rule name. O
trackerTargetingTerms String[] Tracking period.
Pass the followings as array of strings up to four:
ONE_MONTH: 30 days.
TWO_MONTHS: 60 days.
THREE_MONTHS: 90 days.
FOUR_MONTHS: 120 days.
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

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).
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -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",
                    "trackerTargetingTerms": ["ONE_MONTH"],
                    "eventCode": "PageView",
                    "trackRuleId": "*",
                    "trackRuleName": "방문"
                    }
                ],
                "locationType": "AREA",
                "locations": [
            {
                "value": "E",
                "description": "광주광역시",
                "depth1Name": "광주광역시"
            },
            {
                "value": "O",
                "description": "충청남도",
                "depth1Name": "충청남도"
            }
             ],
        "depth2locations" : [
            {
                "value" : "",
                "desrciption" : "",
                "depth1Name": "광주광역시",
                "depth2Name": "광주광역시"
            },
            {
                "value" : "",
                "desrciption" : "",
                "depth1Name": "광주광역시",
                "depth2Name": "광주광역시"
            }
        ],
        "depth3Locations" : [
            {
                "value" : "####",
                "desrciption" : "#####",
                "depth1Name": "광주광역시",
                "depth2Name": "광주광역시",
                "depth3Name": "광주광역시"
            },
            {
                "value" : "######",
                "desrciption" : "#####",
                "depth1Name": "광주광역시",
                "depth2Name": "광주광역시",
                "depth3Name": "광주광역시"
            },
        ],
            },
            "adult": false,
            "dailyBudgetAmount": 100000,
            "bidStrategy": "AUTOBID",
            "bidAmount": 0,
            "pricingType": "CPC",
            "pacing": "NONE",
            "name": "register_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
}

Create Message ad group

This API enables you to create a Message ad group under the 'Kakao Talk Channel X Reach(도달)' type of campaign.

Send a POST request with the issued access 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.

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

URL
POST /openapi/v4/adGroups HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format.
adAccountId Long Ad account's ID.
Parameter: Path
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 as KAKAO_TALK.
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.
Fixed as 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
dailyBudgetAmount Integer Daily budget. O
bidStrategy String Bidding method.
Fixed as MANUAL.
O
pricingType String Manual payments.
Fixed as 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 as 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 as SAVE.
O
syncStatus String Sync status with the sending system.
Fixed as READY.
O
ageVerification Boolean Whether to use age verification messages.
true: Age verification message used.
false: General message used.
O

Response

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 as 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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
        "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",
}

Edit Display ad group

This API enables you to edit the detailed information of the Display ad group under a campaign except for the 'Sponsored board', 'Daum Shopping', 'Video', and 'Kakao Bizboard X Reach(도달)' type of 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 access 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

URL
PUT /openapi/v4/adGroups HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
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_STROY
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 only if the campaign type is 'Display X Visit'.
If you set it to true, you must set deviceTypes to ["ANDROID", "IOS", "PC"] as an array of strings.
O
allAvailablePlacement Boolean Whether to display ads on all available places.
Allowed to set it to true only if the campaign type is 'Display' or 'Kakao Bizboard'.
O
deviceTypes String[] Device type.
Use one or more of the followings:
ANDROID
IOS
PC
If the campaign type is not 'Display X Visit', you can pass ANDROID and IOS only.
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.
Adult targeting functions to run ads only for those who are 20 years or older.
If you set it to true, you cannot request targeting.ages.
After you choose to use adult targeting when creating an ad group, you cannot set it to 'Not use'.
O
dailyBudgetAmount Integer Daily budget. O
bidStrategy String Bidding method.
Either MANUAL or AUTOBID.
O
pricingType String Manual payments.
One of CPA, CPM, or CPC.
O
bidAmount Integer Bid amount for manual payments. O
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
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" 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

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).
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -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",
                    "trackerTargetingTerms": ["ONE_MONTH"],
                    "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 Message ad group

This API 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.

Send a PUT request with the issued access 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

URL
PUT /openapi/v4/adGroups HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format.
adAccountId Long Ad account's ID.
Parameter
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 as 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 as 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 as MANUAL.
O
pricingType String Manual bidding method.
Fixed as 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 as NONE.
O
schedule Schedule Schedule information. O

Response

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 as 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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -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",
}

Edit daily budget for Display ad group

This API enables you to edit the daily budget for a Display ad group. You cannot change the daily budget of the ad group under a campaign with the 'Sponsored board', 'Daum Shopping', 'Video', or 'Kakao Bizboard X Reach(도달)' type. 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 access 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 to every second per user account and ad account.

Request

URL
PUT /openapi/v4/adGroups/dailyBudgetAmount HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "id": 1234,
            "dailyBudgetAmount": 5000000
        }'
Response: Success
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 for Display ad group

You can edit 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 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) Daily average bid limit (Automatic 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.
Default
Maximizing the number of clicks: 200

Minimum
Maximizing the number of clicks: 10

Maximum
Lower value bewteen 100,000 won and 50 % of the ad group's daily budget.
Kakao Bizboard Default
CPC : 200
CPM : 5,000

Minimum
CPC : 10
CPM : 4,000

Maximum
Lower value bewteen 100,000 won and 50 % of the ad group's daily budget.
Default
Maximizing the number of clicks: 200

Minimum
Maximizing the number of clicks: 10

Maximum
Lower value bewteen 100,000 won and 50 % of the ad group's daily budget.

Send a PUT request with the issued access 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 to every second per user account and ad account.

Request

URL
PUT /openapi/v4/adGroups/bidAmount HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "id": 1234,
            "bidAmount": 5000
        }'
Response: Success
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

This API 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 or Bizboard type except for 'Reach(도달)' goal. Also, you can edit the spending method only if the bidding method is set to MANUAL.

Send a PUT request with the issued access 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 to every five seconds per user account and ad account.

Request

URL
PUT /openapi/v4/adGroups/pacing HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "id": 1234,
            "pacing": "QUICK"
        }'
Response: Success
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": "게재방식을 선택할 수 없습니다."
    }
}

Retrieve estimated target population for Message ad group

This API enables you to retrieve 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 access 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

URL
POST /openapi/v4/targetings/populationScore HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format.
adAccountId Long Ad account's ID.
Parameter: Query
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 as 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 as 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

Name Type Description
populationScore Long Target population.

Sample

Request
curl -X POST "https://apis.moment.kakao.com/openapi/v4/targetings/populationScore" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "adAccountId: {adAccountId}" \
    -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
}

Change ad group status

This API 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', '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.

Send a PUT request with the issued access 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 to every second per user account, ad account, and ad group.

Request

URL
PUT /openapi/v4/adGroups/onOff HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
    -H "Content-Type: application/json" \
    -d '{
            "id": 1234,
            "config": "ON"
        }'
Response: Success
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": "광고그룹이 존재하지 않습니다."
    }
}

Cancel contract for Message ad group

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

Send a PUT request with the issued access 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

URL
PUT /openapi/v4/adGroups/cancel/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format.
adAccountId Long Ad account's ID.
Parameter: Path
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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json"
Response
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

Delete ad group

This API enables you to delete an ad group.

Send a DELETE request with the issued access 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.

IMPORTANT

Deleting an ad group means giving up the operation of a sub-ad group, not deleting its data. You can delete the ad groups when the creatives that can be deleted are included only. You cannot delete the ad groups under the 'Sponsored board', 'Kakao Bizboard X Reach(도달)', 'Daum Shopping', or 'Kakao TV' type of campaigns.

After deleting an ad group: - You cannot use all functions related to the ad group, such as editing and suspending ad groups. - All ads in the ad group are stopped running and displaying. - All creatives under the ad group are deleted. - However, you can still view the statistics in the past operation time.

Request

URL
DELETE /openapi/v4/adGroups/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Ad group's ID. O

Sample

Request
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/adGroups/{id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -H "Content-Type: application/json"
Response: Success
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

This API enables you to retrieve 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 access 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

URL
GET /openapi/v4/adGroups/{id}/adminStopHistory HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Ad group's ID. O

Response

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}/adminStopHistory" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response: Success

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

This API enables you to retrieve 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 access 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

URL
GET /openapi/v4/adGroups/{id}/adminStopHistories HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter: Path
Name Type Description Required
id Long Ad group's ID. O

Response

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}/adminStopHistory" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response: Success
[
{
    "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