광고그룹

이 문서는 광고 만들기: 광고그룹 API 사용 방법을 안내합니다.

광고그룹 목록 보기

기본 정보

광고그룹 목록을 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하고, 성공 시 응답 본문에 JSON 객체로 광고그룹 정보 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

쿼리 파라미터

응답

본문

AdGroup

* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경

예제

요청

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

응답

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

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
            "id": 1111,
            "name": "메시지 광고그룹 1",
            "config": "ON",
            "userConfig": "ON",
            "systemConfig": "ON"
        }, {
            "id": 1112,
            "name": "메시지 광고그룹 2",
            "config": "OFF",
            "userConfig": "ON",
            "systemConfig": "EXTERNAL_SERVICE_STOP"
        }
    ]
}

광고그룹 보기

기본 정보

각 광고그룹 상세 정보를 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 본문 JSON 객체에 종류별 광고그룹 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

경로 변수

응답

본문: 디스플레이 광고그룹

* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경

본문: 다이렉트 메시지 광고그룹

* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경

예제

요청

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

응답: 성공

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",
    "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
}

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": 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": "카카오톡 채널_도달_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",
}

응답: 실패

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": "광고그룹이 존재하지 않습니다."
    }
}

디스플레이 광고그룹 생성하기

기본 정보

다음 쇼핑, 카카오 비즈보드 X 도달 유형 캠페인을 제외한 캠페인의 하위에 디스플레이 광고그룹을 생성할 수 있습니다. 다음의 타게팅 설정, 집행전략 설정 등의 정보를 참고하여 요청 시 파라미터 값을 지정합니다.

집행전략 설정

입찰 방식

입찰 방식별 기본/최소/최대 값

집행전략

그룹 일 예산

일 소진 가능한 금액을 설정하는 단계로, 00시 ~ 24시 기준의 광고그룹 통합 지출 한도를 의미합니다.

• 필수 값
  • 입력 범위: 최소 1만 원 ~ 최대 5억 원 또는 캠페인에서 정의된 일 예산
  • 입력 단위: 10원
  • 기본 값: 100,000원
• 캠페인 기간예산과 광고그룹 일예산은 독립적으로 설정합니다.
  • 둘 중 하나라도 먼저 소진되면 광고 운영 중단

집행 기간

• 광고가 집행될 시작일과 종료일을 설정하는 단계
• 집행 기간은 시작일 및 종료일만 선택 가능
• 기본 시작일 / 종료일 선택은 "일단위"로 제공

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 성공 시 응답 본문의 JSON 객체는 생성된 광고그룹의 상세 정보를 포함하며, 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

* 특정 조건 만족 시 필수 파라미터, 이 외의 경우 필수 파라미터 아님

Campaign

Targeting

CustomerFileTargeting

TrackerTargeting

CohortTargeting

TalkChannelTargeting

SyncAppTargeting

TalkChannelGroupTargeting

응답

본문

* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경

예제

요청

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"
        }'

응답

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
}

디스플레이 광고그룹 수정하기

기본 정보

다음 쇼핑, 카카오 비즈보드 X 도달 유형 캠페인을 제외한 캠페인 하위의 디스플레이 광고그룹 상세 정보를 수정합니다. 광고그룹 수정 시에는 광고그룹 보기를 통해 기존 광고그룹의 정보를 조회한 다음에 수정하고자 하는 필드와 수정을 원치 않는 필드를 조합하여 요청해야 합니다. 수정을 원치 않는 필드도 기존 값으로 요청되어야 광고그룹의 정보를 유지할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 파라미터와 함께 PUT으로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

* 특정 조건 만족 시 필수 파라미터, 이 외의 경우 필수 파라미터 아님

Campaign

Targeting

응답

본문

* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경

예제

요청

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": "카카오톡_비즈보드_등록",
            "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"
        }'

응답

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",
    "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
}

디스플레이 광고그룹 일 예산 수정하기

기본 정보

디스플레이 광고그룹 일 예산을 변경합니다. 카카오톡 채널 메시지, 다음 쇼핑, 카카오 비즈보드 X 도달 유형 캠페인 하위의 광고그룹의 일예산은 수정이 불가능합니다. 일 예산은 최소 1만 원에서 최대 5억 원까지 설정 가능하며 10원 단위로 가능합니다. 캠페인 일예산이 설정되어 있는 경우, 광고그룹 일예산은 캠페인 일예산보다 작거나 같아야 합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

예제

요청

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
        }'

응답: 성공

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

응답: 실패

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

디스플레이 광고그룹 수동 입찰 최대 입찰금액 수정하기

기본 정보

디스플레이 광고그룹 최대 입찰금액을 수정합니다. 디스플레이, 동영상, 비즈보드유형 캠페인 (도달 목표 제외) 하위 광고그룹만 가능합니다.

입찰금액 최소 값은 광고그룹 타입, 광고 목적, 과금방식에 따라 다릅니다. 또한 입찰금액은 광고그룹에서 설정한 일예산의 50% 또는 최대 값인 10만 원을 넘을 수 없습니다.

입찰금액 기본, 최소, 최대 값

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

예제

요청

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
        }'

Reponse: 성공

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

응답: 실패

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

디스플레이 광고그룹 게재 방식 수정하기

기본 정보

디스플레이 광고그룹 게재 방식을 변경하는 API로 디스플레이, 동영상, 비즈보드 유형 (도달 목표 제외) 캠페인 하위 광고그룹만 가능합니다. 입찰 방식이 수동(MANUAL)일 경우에만 설정 가능하고, 그 외의 입찰 방식은 게재 방식을 설정할 수 없습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

예제

요청

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"
        }'

응답: 성공

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

응답: 실패

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

메시지 광고그룹 생성하기

기본 정보

카카오톡 채널 X 도달 캠페인 하위의 광고 그룹을 생성합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 성공 시 응답 본문의 JSON 객체는 생성된 광고그룹의 상세 정보를 포함하며, 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.

집행전략 설정

구매 방식 및 기간 예산

발송당 과금방식인 CPMS로만 구매가 가능합니다. 타겟 정보가 변경되는 경우 건당 금액이 변경됩니다. 타게팅이 적용되지 않은 경우 15원, 타게팅이 적용된 경우 20원입니다.

단가와 발송수에 의해 광고그룹의 기간예산이 자동으로 설정 되며 예산은 VAT를 포함하여 광고계정 잔액에서 차감됩니다. 메시지 광고그룹 구매시 잔액이 충분히 충전되어있는지 확인이 필요합니다.

구매 발송수

메시지 광고그룹 예상 모수 조회하기 API를 이용하여 조회된 값을 사용하여 구매발송수로 요청할 수 있습니다.

구매 기간

메시지 발송이 가능한 총 기간을 의미합니다. 총 기간은 시작일로부터 최대 30일로 자동 설정됩니다. 새 친구에게도 보내기를 선택한 경우, 종료일을 설정할 수 있습니다.

발송 가능한 상태인 경우에만 시작일시가 도래하면 메시지를 발송합니다. 메시지 발송이 완료되기 전에 중지가 가능하며, 집행 기간 내에 다시 재개 할 수 있습니다. 기간이 지나면 발송 완료 여부와 관계없이 종료처리 됩니다.

소재 노출방식

소재최적화 기능을 사용하면 성과가 좋은 소재들의 노출 기회를 높여 광고그룹의 효율을 향상시킵니다. 최대 10개의 소재를 등록할 수 있으며, 성능 최적화를 위해 최소 3만의 예상 발송 모수가 필요합니다.

기타 설정

분산 발송하기

시스템 부하 등이 우려되는 경우 분산 발송 속도를 설정하여 메시지 발송 속도를 조절할 수 있습니다. 발송 상황에 따라 설정한 속도와 차이가 발생할 수 있습니다.

푸시 알림 보내지 않기

카카오톡 푸시 알림 없이 발송합니다.

요청

헤더

본문

MessageSendingInfo

응답

본문

* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경

예제

요청

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           
        }'

응답

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

메시지 광고그룹 수정하기

기본 정보

카카오톡 채널 X 도달 캠페인 하위의 광고 그룹의 상세 정보를 수정합니다. 광고 그룹 수정 시에는 광고 그룹 보기 API를 통해 기존 광고 그룹의 정보를 조회한 다음에 수정하고자 하는 필드와 수정을 원치 않는 필드를 조합하여 요청해야 합니다. 수정을 원치 않는 필드도 기존 값으로 요청되어야 광고 그룹의 정보를 유지할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 파라미터와 함께 PUT으로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

응답

본문

* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경

예제

요청

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": "메시지_광고그룹",
        "schedule": {
            "beginDate": "2021-06-01",
            "beginTime": "13:00:00",
            "lateNight": false,
            "detailTime": false,
            "mondayTime": [],
            "tuesdayTime": [],
            "wednesdayTime": [],
            "thursdayTime": [],
            "fridayTime": [],
            "saturdayTime": [],
            "sundayTime": []
        },
        "type": "DIRECT_MESSAGE"
    }'

응답

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": 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": "카카오톡 채널_도달_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",
}

메시지 광고그룹 예상 모수 조회하기

기본 정보

카카오톡 채널 X 도달 캠페인 하위의 광고그룹 생성 및 수정 시 필요한 구매 발송수 입력을 위한 예상 모수를 조회하는 API입니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

본문

응답

본문

예제

요청

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": [],
                "talkChannelGroupTargeting": [],
                "ufoInterests": [],
                "depth2Locations": [],
                "retargetingApps": [],
                "genders": [],
                "cohortTargetings": [],
                "talkChannelTargetings": [],
                "contents": [],
                "trackerTargetings": [],
                "id": -1,
                "ufoBusinessTypes": [],
                "customerFileTargetings": [],
                "audienceType": "NORMAL",
                "locations": []
            },
            "allAvailableDeviceType": true,
            "smartMessage": false,
            "allAvailablePlacement": false
        }'

응답

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

메시지 광고그룹 계약해지하기

기본 정보

카카오톡 채널 X 도달 캠페인 하위의 광고그룹에 대해 계약해지를 할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

경로 변수

예제

요청

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"

응답

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

개인화 메시지 광고그룹 생성하기

기본 정보

개인화 메시지 X 도달 캠페인 하위의 광고그룹을 생성합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 성공 시 응답 본문의 JSON 객체는 생성된 광고그룹의 상세 정보를 포함하며, 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.

집행 전략

• 발송당 과금방식인 CPMS로 자동 설정
• 발송당 금액은 플랫폼 정책에 따르게 되며 변동 가능

집행 대상

• 개인화 메시지 발송 요청하기 API를 통해 발송 대상 식별자(회원번호, 전화전호) 전달

요청

헤더

본문

응답

본문

예제

요청

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": "테스트 개인화 메시지 광고그룹명"
    }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "name": "테스트 개인화 메시지 광고그룹명",
    "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"
}

개인화 메시지 광고그룹 수정하기

기본 정보

개인화 메시지 X 도달 캠페인 하위의 광고 그룹의 상세 정보를 수정합니다. 수정 가능한 항목은 광고그룹의 이름이며 기타 광고그룹 정보는 수정이 불가합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 파라미터와 함께 PUT으로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

응답

본문

예제

요청

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": "개인화 메시지_광고그룹 수정"
    }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "name": "테스트 개인화 메시지 광고그룹명",
    "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"
}

광고그룹 상태 변경하기

기본 정보

광고그룹 상태를 ON, OFF 중에서 변경합니다. 광고그룹 상태가 ON 또는 OFF일 경우, 디스플레이, 동영상, 비즈보드 유형 (도달 목표 제외), 카카오톡 채널 캠페인 하위 광고그룹만 가능합니다. 카카오톡 채널 캠페인 하위 광고그룹을 OFF하는 경우 발송 중이던 메시지는 중단되고, 발송예정 메시지는 발송 취소 됩니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정, 광고그룹마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

본문

예제

요청

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"
        }'

응답: 성공

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

응답: 실패

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

광고그룹 삭제하기

기본 정보

광고그룹을 삭제합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청합니다. 삭제하려는 광고그룹의 ID를 파라미터로 지정해야 합니다. 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

경로 변수

예제

요청

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"

응답: 성공

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

응답: 실패

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

광고그룹 시스템 정지 사유 보기

기본 정보

지정한 한 광고그룹의 시스템 정지 사유를 조회합니다. 광고그룹의 systemConfig가 ADMIN_STOP 또는 EXTERNAL_SERVICE_STOP인 경우에만 응답이 있습니다. 시스템 정지 사유가 여러 건 있는 경우 가장 최근의 시스템 정지 사유를 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 시스템 정지 사유 상세정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

경로 변수

응답

본문

* adminStopReason: Deprecated, 관리자 정지 사유(String), reason으로 변경

예제

요청

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

응답: 성공

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1234,
    "systemConfig": "EXTERNAL_SERVICE_STOP",
    "reason": "채널 관리자센터에서 규제됨",
    "detailReason" : "메시지 집행 가이드, 운영정책을 위반한 내용이 포함되어 있어 발송 불가",
    "createdDate":"2021-01-01T00:00:00",
    "lastModifiedDate": "2021-01-01T00:00:00"
}

응답: 실패

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

광고그룹 시스템 정지 사유 목록 보기

기본 정보

지정한 한 광고그룹의 최근 2년 동안의 시스템 정지 사유를 조회합니다. 광고그룹의 systemConfig가 ADMIN_STOP 또는 EXTERNAL_SERVICE_STOP인 경우에만 응답이 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 시스템 정지 사유 상세정보 리스트를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

경로 변수

응답

본문

SystemStopReason

* adminStopReason: Deprecated, 관리자 정지 사유(String), reason으로 변경

예제

요청

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

응답: 성공

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "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" : "메시지 집행 가이드, 운영정책을 위반한 내용이 포함되어 있어 발송 불가",
        "createdDate":"2021-01-01T00:00:00",
        "lastModifiedDate": "2021-01-01T00:00:00"
    }
]

응답: 실패

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

더 보기

카카오모먼트 API 레퍼런스