Ad creation: Ad group

This document describes how to use the Ad group APIs.

View list of ad groups

Basic information

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

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

Request

Header

Query parameter

Response

Body

AdGroup

Sample

Request

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

Response

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

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

View ad group

Basic information

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

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

Request

Header

Path variable

Response

Body: Display ad group

Body: Message ad group

Sample

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 54322,
    "name": "kakao_bizboard_visit_202205201557",
    "config": "ON",
    "dynamicTarget": null,
    "creativeOptimization": false,
    "smartMessage": null,
    "pacing": "NONE",
    "pricingType": "CPC",
    "bidAmount": 0,
    "bidStrategy": "AUTOBID",
    "statusDescription": "운영중",
    "status": [
        "LIVE"
    ],
    "deviceTypes": [
        "ANDROID",
        "IOS"
    ],
    "placements": [
        "DAUM",
        "NETWORK",
        "KAKAO_TALK",
        "KAKAO_SERVICE"
    ],
    "targeting": {
        "type": "NORMAL",
        "adAccountId": null,
        "ageType": "ALL",
        "genderType": "ALL",
        "locationType": "AREA",
          "locations": [
            {
                "value": "E",
                "description": "광주광역시",
                "depth1Name": "광주광역시"
            },
            {
                "value": "O",
                "description": "충청남도",
                "depth1Name": "충청남도"
            }
        ],
        "depth2locations" : [
            {
                "value" : "B7222",
                "desrciption" : "경기도 여주시",
                "depth1Name": "경기도",
                "depth2Name": "여주시"
            },
            {
                "value" : "I1009",
                "desrciption" : "서울특별시 도봉구",
                "depth1Name": "광주광역시",
                "depth2Name": "도봉구"
            }
        ],
        "depth3Locations" : [
            {
                "value" : "A70052424",
                "desrciption" : "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
            },
            {
                "value" : "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

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

Basic information

This API enables you to create a Display ad group under a campaign, except for the '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

Default, minimum, and maximum values by bidding method

Delivery strategies

Daily budget for a group

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

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

Delivery period

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

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

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

Request

Header

Body

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

Campaign

Targeting

TalkChannelGroupTargeting

CustomerFileTargeting

TrackerTargeting

CohortTargeting

TalkChannelTargeting

SyncAppTargeting

Response

Body

Sample

Request

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

Response

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

Edit Display ad group

Basic information

This API enables you to edit the detailed information of the Display ad group under a campaign except for the 'Daum Shopping' 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 Business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the changed information of the ad group in JSON format. If failed, refer to Error code to figure out its failure cause.

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

Request

Header

Body

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

Campaign

Targeting

Response

Body

Sample

Request

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

Response

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

Edit daily budget for Display ad group

Basic information

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 'Daum Shopping' 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 Business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

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

Request

Header

Body

Sample

Request

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

Response

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

Response: Fail

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

Edit maximum bid of Manual bidding for Display ad group

Basic information

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, Video, or Bizboard type except for the 'Reach(도달)' goal.

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

Default and minimum values of the bid amount

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

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

Request

Header

Body

Sample

Request

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

Response

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

Response: Fail

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

Edit spending method for Display ad group

Basic information

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, Video, 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 Business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

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

Request

Header

Body

Sample

Request

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

Response

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

Response: Fail

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

Create Message ad group

Basic information

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 Business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the detailed information of the created ad group. If failed, refer to Error code to figure out its failure cause.

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

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.

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.

Delivery strategies settings: Acitive period

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

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

Display method of Creative

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

Other settings: 분산발송(Distributed sending)

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

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

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

Request

Header

Body

MessageSendingInfo

Response

Body

Sample

Request

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

Response

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

Edit Message ad group

Basic information

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 Business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the changed information of the ad group in JSON format. If failed, refer to Error code to figure out its failure cause.

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

Request

Header

Body

Response

Body

Sample

Request

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

Response

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

Retrieve estimated target population for Message ad group

Basic information

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 Business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header

Body

Response

Body

Sample

Request

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

Response

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

Cancel contract for Message ad group

Basic information

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 Business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header

Path variable

Sample

Request

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

Response

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

Create Personalized message ad group

Basic information

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

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

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

Execution strategy

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

Execution target

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

Request

Header

Body

Response

Body

Sample

Request

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

Response

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

Edit Personalized message ad group

Basic information

Edit the Personalized message ad group in detail. You can edit the name, but other information is not editable.

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

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

Request

Header

Body

Response

Body

Sample

Request

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

Response

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

Change ad group status

Basic information

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', 'Video', 'Bizboard' (except for the 'Reach(도달)' goal), or 'Kakao Talk Channel' type.

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

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

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

Request

Header

Body

Sample

Request

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

Response

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

Response: Fail

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

Delete ad group

Basic information

This API enables you to delete an ad group.

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

Request

Header

Path variable

Sample

Request

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

Response

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

Response: Fail

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

View reason for system stop

Basic information

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 Business token in the request header. If the request is successful, this API returns the system stop reason and details in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header

Path variable

Response

Body

Sample

Request

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

Response

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

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

Response: Fail

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

View list of reasons for system stop

Basic information

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 Business token in the request header. If the request is successful, this API returns the list of the system stop reasons and details in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header

Path variable

Response

Body

SystemStopReason

Sample

Request

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

Response

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

Response: Fail

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

See more

• Kakao Moment API Reference