페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 광고 만들기: 광고그룹

카카오모먼트

광고그룹

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

광고그룹 목록 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adGroups 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
쿼리 파라미터
이름 타입 설명 필수
campaignId Long 캠페인 번호 O
config String[] 광고그룹 상태
다음 중 복수 선택 가능
ON
OFF
DEL
(기본값 : [ON, OFF])		 X

응답

본문
이름 타입 설명
content AdGroup[] 광고그룹 정보 목록
AdGroup
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹명
config String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
userConfig String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
참고: config와 동일한 값으로, config로 개선하기 이전에 사용하던 필드입니다. 현재 해당 필드는 사용이 불가하며, 히스토리 관리를 위한 조회용으로만 참고 가능합니다.
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나

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

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups?campaignId=1234&config=ON" \
    -H "Authorization: Bearer ${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"
        }
    ]
}

광고그룹 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adGroups/${ID} 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 광고그룹 번호 O

응답

본문: 디스플레이 광고그룹
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹명
config String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
pacing Pacing 게재 방식
NONE, QUICK, NORMAL 중 하나
pricingType PricingType 과금 방식
CPM, CPC, CPA 중 하나
bidAmount Integer 최대 입찰금액
bidStrategy String 입찰 방식
MANUAL(수동), AUTOBID(자동입찰), OPTIMIZATION(목적 최적화) 중 하나
bidStrategyTarget BidStrategyTarget 자동입찰 옵션
statusDescription String 광고그룹의 게재와 관련된 현재 상태
status String[] 상태, Status 참고
optimizationStatus String[] 최적화 상태, OptimizationStatus 참고
최적화 상태값이 없는 경우 응답에서 제외
deviceTypes EnumSet of DeviceType[] 디바이스 타입
adServingCategories String[] 게재 지면의 네트워크 하위 카테고리
sectionCategories String[] 섹션 카테고리
(현재 카카오 비즈보드 캠페인 유형 '채팅탭에만 노출' 옵션으로만 지원)
placements EnumSet of Placement[] 게재 지면
targeting Targeting 타게팅
schedule Schedule 스케줄
campaign Campaign 캠페인
useWifiOnly Boolean WIFI에서만 노출 여부
creativeCount Integer 등록된 소재의 수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
allAvailablePlacement Boolean 가능한 모든 지면 노출
adult Boolean 성인 타게팅 여부
true : 성인 타게팅 허용
false : 성인 타게팅 비허용
totalBudget Long 총 예산
dailyBudgetAmount Long 일 예산
isDailyBudgetAmountOver Boolean 일 예산 초과 여부
isValidPeriod Boolean 집행기간 유효 여부
createdDate String 광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

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

본문: 다이렉트 메시지 광고그룹
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹명
config String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
smartMessage boolean 스마트 메시지 여부
pricingType PricingType 과금 방식
CPMS
bidAmount Integer 입찰금액
bidStrategy String 입찰 방식
MANUAL(수동) 고정값
totalBudget Long 구매 금액
totalBudgetWithVAT Long VAT 포함 기간 예산
status String[] 상태, Status 참고
placements Placement 게재 지면
targeting Targeting 타게팅
schedule Schedule 스케줄
messageSendingInfo MessageSendingInfo 메시지
profileId String 카카오톡 채널 프로필 아이디
campaign Campaign 캠페인
useWifiOnly Boolean WIFI에서만 노출 여부
creativeCount Long 등록된 소재수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
allAvailablePlacement Boolean 가능한 모든 지면 노출
adult Boolean 성인 타게팅 여부
false : 성인 타게팅 비허용
isDailyBudgetAmountOver Boolean 일 예산 초과 여부
isValidPeriod Boolean 집행기간 유효 여부
createdDate String 광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

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

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}" \
    -H "Authorization: Bearer ${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": "광고그룹이 존재하지 않습니다."
    }
}

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

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/adGroups 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

집행전략 설정

입찰 방식
입찰 방식 종류 입찰금액 설정
수동입찰 CPA
CPC
CPM		 최대금액 입찰 설정
입력한 값으로 비딩하고, 입력한 값보다 적은 금액으로 과금
* 필수값
* 입력범위 : 최소 (캠페인 프리셋별 정의된 기준) ~ 최대 (10만 혹은 광고그룹 일예산의 50% 이하)
* 입력단위 : 1원
* 기본값 : 캠페인 프리셋 별 정의된 기준
자동입찰 클릭수 최대화
전환수 최대화		 입찰금액 설정 대상에 해당하지 않음
시스템에서 자동으로 최적 입찰가로 비딩함
CPC 비용 목표 목표로 삼을 입찰금액 설정
입력한 값을 평균으로 유지하도록 동작하나, 최적화 과정에서 목표 금액을 상회하거나 미달할 수 있음
* 필수값
* 입력범위: 10원 ~ 최대 (10만 또는 광고그룹 일예산의 50% 이하)
* 입력단위: 1원
CPA 비용 목표 목표로 삼을 입찰금액 설정
입력한 값을 평균으로 유지하도록 동작하나, 최적화 과정에서 목표 금액을 상회하거나 미달할 수 있음
* 필수값
* 입력범위: 100원 ~ 최대 (100만 또는 광고그룹 일예산의 50% 이하)
* 입력단위: 1원
입찰 방식별 기본/최소/최대 값
광고 유형 수동 입찰 자동 입찰
디스플레이 기본
CPA: 1,500
CPC: 200
CPM: 1,000

최소
CPA: 100
CPC: 10
CPM: 100

최대
10만 또는 광고그룹 일예산 50% 이하 중 작은 값		 최소
CPC 비용 목표: 10
CPA 비용 목표: 100

최대
CPC 비용 목표: 10만 또는 광고그룹 일예산 50% 이하 중 작은 값
CPA 비용 목표: 100만 또는 광고그룹 일예상 50% 이하 중 작은 값

클릭수 최대화, 전환수 최대화의 경우 bidAmount는 별도 설정 없이 0으로 입력하시면 광고그룹 일 예산 내에서 선택한 광고 효율을 최대한 높이도록 시스템에서 입찰금액을 자동으로 설정합니다.
카카오 비즈보드 기본
CPC: 200
CPM: 3,000

최소
CPC: 10
CPM: 1,000

최대
10만 또는 광고그룹 일예산 50% 이하 중 작은 값		 최소
CPC 비용 목표: 10
CPA 비용 목표: 100

최대
CPC 비용 목표: 10만 또는 광고그룹 일예산 50% 이하 중 작은 값
CPA 비용 목표: 100만 또는 광고그룹 일예상 50% 이하 중 작은 값

클릭수 최대화, 전환수 최대화의 경우 bidAmount는 별도 설정 없이 0으로 입력하시면 광고그룹 일 예산 내에서 선택한 광고 효율을 최대한 높이도록 시스템에서 입찰금액을 자동으로 설정합니다.

집행전략

그룹 일 예산

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

  • 필수 값
    • 입력 범위: 최소 1만 원 ~ 최대 5억 원 또는 캠페인에서 정의된 일 예산
    • 입력 단위: 10원
    • 기본 값: 100,000원
  • 캠페인 기간예산과 광고그룹 일예산은 독립적으로 설정합니다.
    • 둘 중 하나라도 먼저 소진되면 광고 운영 중단
집행 기간
  • 광고가 집행될 시작일과 종료일을 설정하는 단계
  • 집행 기간은 시작일 및 종료일만 선택 가능
  • 기본 시작일 / 종료일 선택은 "일단위"로 제공
시작일 종료일 요일 시작시간/종료시간
오늘부터 최대 6개월 이후 날짜까지 선택 가능
기본 값 : 오늘 날짜		 시작일부터 이후 날짜 선택 가능
"종료일 없음" 상태 선택 가능
기본 값 : 종료일 없음		 선택불가
기본값 : 전체		 선택불가
단, 심야타게팅 (22:00 ~ 06:59)은 설정 가능

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
campaign Campaign 캠페인 O
name String 광고그룹 이름
최대 50자
요청 시 포함되지 않으면 자동 생성		 X
placements String[] 게재 지면
KAKAO_STORY (카카오 스토리)
KAKAO_SERVICE (카카오 서비스)
KAKAO_TALK (카카오톡)
DAUM (다음)
NETWORK (네트워크)		 O
adServingCategories String[] 게재 지면 네트워크 하위
placements에 NETWORK가 요청되었을 경우에 해당 필드는 필수로 요청
캠페인 유형이 카카오 비즈보드인 경우에는 해당 필드 전체 값으로 요청
네트워크 게재지면 하위 목록 보기를 사용하여 응답 Json 중에 code를 사용하여 요청		 O*
sectionCategories String[] 섹션 카테고리
캠페인 유형이 카카오 비즈보드이고, placements에 KAKAO_TALK 요청되었을 경우 선택 가능
그 외의 경우 요청 불가
섹션 카테고리 목록 보기 API의 응답 JSON 중 code를 사용하여 요청		 X
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
캠페인 유형이 디스플레이 X 방문이거나 디스플레이 X 전환 중 광고 목표 대상이 픽셀 & SDK의 구매, 회원가입, 잠재고객, 서비스 신청, 장바구니인 경우에 true 설정 가능
true로 설정할 경우 하단의 deviceTypes에 ANDROID, IOS, PC 가 Array of String으로 요청되어야 함		 O
allAvailablePlacement Boolean 가능한 모든 지면 노출
캠페인 유형이 디스플레이, 카카오 비즈보드인 경우에만 true 설정 가능		 O
deviceTypes String[] 디바이스
ANDROID (안드로이드)
IOS (IOS)
PC (PC)
캠페인 유형이 디스플레이 X 방문이 아닌 경우 ANDROID, IOS만 요청 가능
allAvailableDeviceType (가능한 모든 디바이스 노출)을 true로 설정한 경우 ANDROID, IOS, PC 모두 요청해야 함		 O
targeting Targeting 타게팅 O
adult Boolean 성인 타게팅 여부
true로 설정 시 20세 이상에게만 광고 노출이 가능
targeting.ages에 "20","25","30","35","40","45","50","55","60","65","70"을 배열에 담아 요청해야 함		 O
dailyBudgetAmount Integer 일 예산 O
bidStrategy String 입찰 방식
MANUAL(수동), AUTOBID(자동입찰) 중 하나		 O
pricingType String 수동 입찰 방식
CPA, CPM, CPC 중 하나		 O
bidAmount Integer 수동 입찰금액
자동입찰일 경우 0 입력		 O
bidStrategyTarget BidStrategyTarget 자동입찰 옵션 X
pacing String 게재 방식
입찰 방식에 따라 설정 가능 값 다름, 아래 참고

입찰 방식 MANUAL(수동): NORMAL(일반게재), QUICK(빠른게재) 중 하나
입찰 방식 AUTOBID(자동): NONE		 O
schedule Schedule 스케줄 정보 O

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

Campaign
이름 타입 설명
id Long 캠페인 번호
Targeting
이름 타입 설명 필수
id Long 오디언스를 사용하는 경우 해당 오디언스의 ID X
type String 오디언스 사용여부
NORMAL(일반 타겟팅 설정), DISPLAY(디스플레이 오디언스 관리기능 설정), MESSAGE(메시지 오디언스 관리기능 설정) 중 하나
DISPLAY 또는 MESSAGE를 사용하는 경우 나머지 타겟 정보는 빈 값으로 요청
* 광고타입이 DISPLAY인 경우, 오디언스도 DISPLAY로 요청해야 함		 X
ageType String 연령대 전체 선택 종류
ALL (전체 선택), NOT_ALL (부분 선택) 중 하나
adult(성인 타게팅 여부)가 true인 경우 해당 필드는 NOT_ALL로만 요청 가능		 O
ages String[] 연령대
15 (15 ~ 19)
20 (20 ~ 24)
25 (25 ~ 29)
30 (30 ~ 34)
35 (35 ~ 39)
40 (40 ~ 44)
45 (45 ~ 49)
50 (50 ~ 54)
55 (55 ~ 59)
60 (60 ~ 64)
65 (65 ~ 69)
70(70 이상)
ageType(연령대 전체 선택 종류)이 ALL 인 경우 ages는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함
성인 타게팅 여부(true) 허용으로 설정할 경우 "20","25","30","35","40","45","50","55","60","65","70" 을 배열에 담아 요청해야 함.		 O*
genderType String 성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나		 O
genders String[] 성별
M : 남자
F : 여자
genderType(성별 전체 선택 종류)이 ALL 인 경우 genders는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함		 O*
ufoInterests Set of UfoInterest 맞춤타겟 > 카카오 데이터 > 카테고리 > 관심사
맞춤타겟 카테고리 타입 보기 참고		 X
ufoBusinessTypes Set of UfoBusinessType 맞춤타겟 > 카카오 데이터 > 카테고리 > 업종
맞춤타겟 카테고리 타입 보기 참고		 X
locationType String 지역선택 타입
ALL (전체선택), AREA (지역선택) 중 하나		 O
locations Set of Location 데모그래픽 > 행정구역 > 시/도
시/도 보기 참고
locationType(ALL)으로 요청된 경우 해당 필드는 요청할 수 없음
캠페인 유형이 카카오 비즈보드인 경우 해외(Z)는 요청할 수 없음
locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 함께 요청 가능		 X
depth2Locations Set of Depth2Location 데모그래픽 > 행정구역 > 시/군/구
시/군/구 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야함. 행정구역 타게팅 세 가지 함께 요청 가능		 X
depth3Locations Set of Depth3Location 데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능		 X
customerFileTargetings Set of CustomerFileTargeting 맞춤타겟 > 내 데이터 > 고객파일
타게팅 가능한 고객파일 목록 보기 API 를 통해 조회되는 정보를 활용		 X
trackerTargetings Set of TrackerTargeting 맞춤타겟 > 내 데이터 > 픽셀 & SDK
타게팅 가능한 픽셀 & SDK 이벤트 목록 보기 API 를 통해 조회되는 정보를 활용		 X
cohortTargetings Set of CohortTargeting 맞춤타겟 > 내 데이터 > 광고반응타겟
타게팅 가능한 광고반응 타겟 목록 보기 API 를 통해 조회되는 정보를 활용		 X
talkChannelTargetings Set of TalkChannelTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구
타게팅 가능한 카카오 채널 정보 보기 API 를 통해 조회되는 정보를 활용		 X
syncAppTargetings Set of SyncAppTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자
타게팅 가능한 카카오 채널 정보 보기 API 를 통해 조회되는 정보를 활용		 X
talkChannelGroupTargetings Set of TalkChannelGroupTargeting 맞춤타겟 > 내 데이터 > 친구그룹
타게팅 가능한 친구그룹 목록 보기를 통해 조회되는 정보를 활용
비고: 카카오톡 채널 X 도달 캠페인에서만 사용 가능		 X
CustomerFileTargeting
이름 타입 설명 필수
customerFileId Long 등록된 고객파일 번호 O
inclusionType String 포함 여부
INCLUDE (포함), EXCLUDE (제외) 중 하나		 O
TrackerTargeting
이름 타입 설명 필수
trackId String 트래킹 아이디 O
inclusionType String 포함여부
INCLUDE (포함),
EXCLUDE (제외) 중 하나		 O
eventCode String 이벤트 코드
'모든 이벤트'의 경우 * 값으로 요청		 O
trackRuleId String 트랙 룰 아이디 O
trackRuleName String 트랙 룰 이름 O
term Integer 타겟 기간(최소: 1, 최대: 180) O
CohortTargeting
이름 타입 설명 필수
cohortId String 등록된 광고반응 타겟 번호 O
inclusionType String 포함여부
INCLUDE(포함),
EXCLUDE(제외) 중 하나		 O
TalkChannelTargeting
이름 타입 설명 필수
profileId String 카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법		 O
inclusionType String 포함여부
INCLUDE(포함),
EXCLUDE(제외) 중 하나		 O
SyncAppTargeting
이름 타입 설명 필수
profileId String 카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법		 O
inclusionType String 포함여부
INCLUDE(포함),
EXCLUDE(제외) 중 하나		 O
TalkChannelGroupTargeting
이름 타입 설명 필수
talkChannelGroupFileId Long 친구그룹 파일 ID O
name String 친구그룹 이름 O
inclusionType String 포함 여부
INCLUDE(포함), EXCLUDE(제외) 중 하나		 O
fileType String 친구그룹 유형
다음 중 하나
APP_USER_ID(앱유저아이디)
PHONE_NUMBER(전화번호)
MESSAGE_RETARGET(메시지 발송 대상자)		 O
groupKey String 친구그룹 파일의 그룹 키 O

응답

본문
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹 이름
config String 광고그룹 상태
pacing String 게재 종류
pricingType String 과금 종류
bidAmount Integer 광고그룹 입찰가
bidStrategy String 입찰 방식
bidStrategyTarget BidStrategyTarget 자동입찰 옵션
statusDescription String 광고그룹 상태 설명
status String[] 광고그룹 상태, Status 참고
optimizationStatus String[] 최적화 상태, OptimizationStatus 참고
최적화 상태값이 없는 경우 응답에서 제외
deviceTypes DeviceType[] 디바이스
adServingCategories String[] 게재 지면 네트워크의 하위
sectionCategories String[] 섹션 카테고리
(현재 카카오 비즈보드 유형 '채팅탭에만 노출' 옵션으로만 지원)
placements Placement[] 게재 지면
targeting Targeting 타게팅
Schedule Schedule 스케줄
campaign Campaign 캠페인
useWifiOnly Boolean WIFI에서만 노출 여부
creativeCount Long 하위에 등록된 소재 개수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceType Boolean 가능한 모든 디바이스 지원 여부
allAvailablePlacement Boolean 가능한 모든 게재 지면 지원 여부
adult Boolean 성인 타게팅
totalBudget Integer 총 예산
dailyBudgetAmount Long 일 예산
isDailyBudgetAmountOver Boolean 광고그룹 일 예산 초과 여부
isValidPeriod Boolean 집행 기간 유효 여부
createdDate String 등록일시
lastModifiedDate String 마지막 수정일시

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

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/adGroups" \
    -H "Authorization: Bearer ${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
}

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

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 광고그룹 번호 O
campaign Campaign 캠페인 O
name String 광고그룹 이름
최대 50자
요청 시 포함되지 않으면 생성 시 설정된 이름으로 대체		 X
placements String[] 게재 지면
KAKAO_STORY (카카오 스토리)
KAKAO_SERVICE (카카오 서비스)
KAKAO_TALK (카카오톡)
DAUM (다음)
NETWORK (네트워크)		 O
adServingCategories String[] 게재 지면 네트워크 하위
placements에 NETWORK가 요청되었을 경우에 해당 필드는 필수로 요청
캠페인 유형이 카카오 비즈보드인 경우에는 해당 필드 전체 값으로 요청
타게팅의 네트워크 하위 보기 API를 사용하여 응답 JSON 중에 code를 사용하여 요청		 O*
sectionCategories String[] 섹션 카테고리
캠페인 유형이 카카오 비즈보드이고, placements에 KAKAO_TALK 요청되었을 경우 선택 가능
그 외의 경우 요청 불가
섹션 카테고리 목록 보기 API의 응답 JSON 중에 code를 사용하여 요청		 X
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
캠페인 유형이 디스플레이 X 방문이거나 디스플레이 X 전환 중 광고 목표 대상이 픽셀 & SDK의 구매, 회원가입, 잠재고객, 서비스 신청, 장바구니인 경우에 true 설정 가능
true로 설정할 경우 하단의 deviceTypes에 ANDROID, IOS, PC 가 Array of String으로 요청되어야 함		 O
allAvailablePlacement Boolean 가능한 모든 지면 노출
캠페인 유형이 디스플레이, 카카오 비즈보드인 경우에만 true 설정 가능		 O
deviceTypes String[] 디바이스
ANDROID (안드로이드)
IOS (IOS)
PC (PC)
캠페인 유형이 디스플레이 X 방문이 아닌 경우 ANDROID, IOS만 요청 가능
allAvailableDeviceType(가능한 모든 디바이스 노출)을 true로 설정한 경우 ANDROID, IOS, PC 모두 요청해야 함		 O
targeting Targeting 타게팅 O
adult Boolean 성인 타게팅 여부
true로 설정 시 20세 이상에게만 광고 노출이 가능
targeting.ages에 "20","25","30","35","40","45","50","55","60","65","70"을 배열에 담아 요청해야 함
광고그룹 생성시 성인 타게팅 여부 허용으로 했을 경우 허용 안함으로 변경은 불가능		 O
dailyBudgetAmount Integer 일 예산 O
bidStrategy String 입찰 방식
MANUAL(수동), AUTOBID(자동입찰) 중 하나		 O
pricingType String 수동 입찰 방식
CPA, CPM, CPC 중 하나		 O
bidAmount Integer 수동 입찰금액
자동입찰일 경우 0 입력		 O
bidStrategyTarget BidStrategyTarget 자동입찰 옵션 X
pacing String 게재 방식
NORMAL (일반게재)
QUICK (빠른게재)
NONE (설정해제) 중 하나
단, 입찰방식이 MANUAL(수동)일 경우에만 설정 가능
카카오 비즈보드 X 전환 유형 하위에 광고그룹을 생성할 경우 NONE으로만 요청		 O
schedule Schedule 스케줄 정보 O

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

Campaign
이름 타입 설명
id Long 캠페인 번호
Targeting
이름 타입 설명 필수
id Long 오디언스를 사용하는 경우 해당 오디언스의 ID X
type String 오디언스 사용여부
NORMAL(일반 타겟팅 설정), DISPLAY(디스플레이 오디언스 관리기능 설정), MESSAGE(메시지 오디언스 관리기능 설정) 중 하나
DISPLAY 또는 MESSAGE를 사용하는 경우 나머지 타겟 정보는 빈 값으로 요청		 X
ageType String 연령대 전체 선택 종류
ALL (전체 선택), NOT_ALL (부분 선택) 중 하나
adult(성인 타게팅 여부)가 true인 경우 해당 필드는 NOT_ALL로만 요청 가능		 O
ages String[] 연령대
15 (15 ~ 19)
20 (20 ~ 24)
25 (25 ~ 29)
30 (30 ~ 34)
35 (35 ~ 39)
40 (40 ~ 44)
45 (45 ~ 49)
50 (50 ~ 54)
55 (55 ~ 59)
60 (60 ~ 64)
65 (65 ~ 69)
70(70 이상)
ageType(연령대 전체 선택 종류)이 ALL 인 경우 ages는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함
성인 타게팅 여부(true) 허용으로 설정할 경우 "20","25","30","35","40","45","50","55","60","65","70" 을 배열에 담아 요청해야 함.		 O*
genderType String 성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나		 O
genders String[] 성별
M : 남자
F : 여자
genderType(성별 전체 선택 종류)이 ALL 인 경우 genders는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함		 O*
ufoInterests Set of UfoInterest 맞춤타겟 > 카카오 데이터 > 카테고리 > 관심사
맞춤 타겟 카테고리 타입 보기 참고		 X
ufoBusinessTypes Set of UfoBusinessType 맞춤타겟 > 카카오 데이터 > 카테고리 > 업종
맞춤타겟 카테고리 타입 보기 참고		 X
locationType String 지역선택 타입
ALL (전체선택), AREA (지역선택) 중 하나		 O
locations Set of Location 데모그래픽 > 행정구역 > 시/도
시/도 보기 참고
locationType(ALL)으로 요청된 경우 해당 필드는 요청할 수 없음
캠페인 유형이 카카오 비즈보드인 경우 해외(Z)는 요청할 수 없음
locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 함께 요청 가능		 X
depth2Locations Set of Depth2Location 데모그래픽 > 행정구역 > 시/군/구
시/군/구 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야함. 행정구역 타게팅 세 가지 함께 요청 가능		 X
depth3Locations Set of Depth3Location 데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 보기 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능		 X
customerFileTargetings Set of CustomerFileTargeting 맞춤타겟 > 내 데이터 > 고객파일
타게팅 가능한 고객파일 목록 보기 API 를 통해 조회되는 정보를 활용		 X
trackerTargetings Set of TrackerTargeting 맞춤타겟 > 내 데이터 > 픽셀 & SDK
타게팅 가능한 픽셀 & SDK 이벤트 목록 보기 API 를 통해 조회되는 정보를 활용		 X
cohortTargetings Set of CohortTargeting 맞춤타겟 > 내 데이터 > 광고반응타겟
타게팅 가능한 광고반응 타겟 목록 보기 API 를 통해 조회되는 정보를 활용		 X
talkChannelTargetings Set of TalkChannelTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구
타게팅 가능한 카카오 채널 정보 보기 API 를 통해 조회되는 정보를 활용		 X
syncAppTargetings Set of SyncAppTargeting 맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자
타게팅 가능한 카카오 채널 정보 보기 API 를 통해 조회되는 정보를 활용		 X

응답

본문
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹 이름
config String 광고그룹 상태
pacing String 게재 종류
pricingType String 과금 종류
bidAmount Integer 광고그룹 입찰가
bidStrategy String 입찰 방식
bidStrategyTarget BidStrategyTarget 자동입찰 옵션
statusDescription String 광고그룹 상태 설명
status String[] 광고그룹 상태, Status 참고
optimizationStatus String[] 최적화 상태, OptimizationStatus 참고
최적화 상태값이 없는 경우 응답에서 제외
deviceTypes String[] 디바이스
adServingCategories String[] 게재 지면 네트워크의 하위
sectionCategories String[] 섹션 카테고리
(현재 카카오 비즈보드 유형 '채팅탭에만 노출' 옵션으로만 지원)
placements Placement[] 게재 지면
targeting Targeting 타게팅
Schedule Schedule 스케줄
campaign Campaign 캠페인
useWifiOnly Boolean WIFI에서만 노출 여부
creativeCount Long 하위에 등록된 소재 개수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceType Boolean 가능한 모든 디바이스 지원 여부
allAvailablePlacement Boolean 가능한 모든 게재 지면 지원 여부
adult Boolean 성인 타게팅
totalBudget Integer 총 예산
dailyBudgetAmount Long 일 예산
isDailyBudgetAmountOver Boolean 광고그룹 일 예산 초과 여부
isValidPeriod Boolean 집행 기간 유효 여부
createdDate String 등록일시
lastModifiedDate String 마지막 수정일시

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

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups" \
    -H "Authorization: Bearer ${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
}

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

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups/dailyBudgetAmount 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 광고그룹 번호 O
dailyBudgetAmount Long 광고그룹 일예산
광고그룹 일예산은 최소 1만 원에서 최대 5억 원까지 설정 가능하며 10원 단위로 가능
캠페인 일예산이 설정되어 있는 경우, 광고그룹 일예산은 캠페인 일예산보다 작거나 같아야함		 O

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/dailyBudgetAmount" \
    -H "Authorization: Bearer ${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만원보다 크거나 같아야 합니다."
    }
}

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

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups/bidAmount 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

입찰금액 기본, 최소, 최대 값
Type 최대 입찰금액(수동입찰)
디스플레이 기본
CPA : 1,500
CPC : 200
CPM : 1,000

최소
CPA : 100
CPC : 10
CPM : 100

최대
10만 또는 광고 그룹 일예산 50% 이하 중 작은 값
카카오 비즈보드 기본
CPC : 200
CPM : 3,000

최소
CPC : 10
CPM : 1,000

최대
10만 또는 광고 그룹 일예산 50% 이하 중 작은 값

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 광고그룹 번호 O
bidAmount Integer 최대 입찰금액
광고그룹 입찰금액은 광고그룹에서 설정한 일예산의 50% 또는 최대값인 10만 원을 넘을 수 없습니다.
입찰금액 최솟값은 광고그룹 타입, 광고 목적, 과금방식에 따라 다릅니다.		 O

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/bidAmount" \
    -H "Authorization: Bearer ${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": "관련 작업을 지원하지 않는 광고그룹입니다."
    }
}

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

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups/pacing 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 광고그룹 번호 O
pacing String 게재방식
NORMAL(일반게재), QUICK(빠른게재) 중 하나
단, 과금전략이 MANUAL(수동)일 경우에만 설정 가능합니다. 그외의 과금전략은 게재방식을 설정할 수 없습니다.

NORMAL(일반게재)
'일반 게재'는 광고그룹에 설정된 일예산을 바탕으로 시간대별로 고려된 예산을 초과 사용하지 않도록 예산을 분할하여 광고 노출을 제어합니다.

QUICK(빠른게재)
'빠른 게재'는 가능한 빨리 광고 결과를 얻을 수 있도록 예산을 최대한 사용하여 광고 노출을 유도합니다.		 O

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/pacing" \
    -H "Authorization: Bearer ${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": "게재방식을 선택할 수 없습니다."
    }
}

메시지 광고그룹 생성하기

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/adGroups 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

집행전략 설정

구매 방식 및 기간 예산

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

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

구매 방식 타겟팅 적용여부 발송 단가 타겟팅 세팅 값
CPMS 미적용 15 "targeting" : {"type": "NORMAL",
"ageType": "ALL",
"genders": [ ],
"genderType": "NOT_ALL",
"locationType": ""}
적용 20 그외 추가 타겟팅 설정시
구매 발송수

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

타겟팅 종류 최소 최대
설정하지 않음 조회된 값 50,000,000
스마트메시지 제외한 타겟팅 11 조회된 값
스마트메시지 포함한 타겟팅 30,000 조회된 값
구매 기간

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

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

소재 노출방식

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

기타 설정

분산 발송하기

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

푸시 알림 보내지 않기

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
campaign Campaign 캠페인 O
name String 광고그룹 이름
최대 50자
요청 시 포함되지 않으면 자동 생성		 X
placements String[] 게재 지면
고정값(KAKAO_TALK)		 O
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
캠페인 유형이 디스플레이 X 방문인 경우에만 true 설정 가능
true로 설정할 경우 하단의 deviceTypes에 ANDROID, IOS, PC 가 Array of String으로 요청되어야 함		 O
allAvailablePlacement Boolean 가능한 모든 지면 노출
false만 전달 가능		 O
deviceTypes String[] 디바이스
ANDROID (안드로이드),
IOS (IOS)
캠페인 유형이 디스플레이 X 방문이 아닌 경우 ANDROID, IOS만 요청 가능
allAvailableDeviceType (가능한 모든 디바이스 노출)을 true로 설정한 경우 ANDROID, IOS, PC 모두 요청해야 함		 O
messageSendingInfo MessageSendingInfo 메시지 정보 O
targeting Targeting 타게팅 O
adult Boolean 성인 타게팅 여부
사용하지 않음 (false)로 요청		 O
bidStrategy String 입찰 방식
고정값 MANUAL(수동)		 O
pricingType String 수동 입찰 방식
고정값(CPMS)		 O
bidAmount Integer 수동 입찰금액(발송단가)
메시지 정보 (MessageSendingInfo)의 price와 같은 값으로 요청		 O
pacing String 게재 방식
고정값 NONE 으로 요청		 O
schedule Schedule 스케줄 정보 O
smartMessage Boolean 스마트 메시지 사용여부
사용 (true), 사용하지 않음 (false) 중 하나
메시지 발송 중 실시간으로 수집한 데이터를 바탕으로 소재를 클릭한 친구와 유사한 친구를 찾아 메시지를 발송하며
성능 최적화를 위해 친구의 최대 50%를 대상으로 발송이 가능하며, 10만 이상의 친구를 가진 채널에만 제공 또한 맞춤타겟의 타겟 정보는 설정이 불가능
소재최적화 기능을 사용하면 성과가 좋은 소재들의 노출 기회를 높여 광고그룹의 효율을 향상시킴
최대 10개의 소재를 등록할 수 있으며, 성능 최적화를 위해 최소 3만의 예상 발송 모수가 필요		 O
MessageSendingInfo
이름 타입 설명 필수
contractCount Integer 구매발송수
예상 발송 모수보다 작게 설정할 수 없음		 O
longTerm boolean 전체발송 후 새 친구에게도 보내기
보내기 (true),
보내지 않기 (false) 중 하나
실시간 타겟 선택시 해당 필드는 false로 요청되어야 함
또한 보내기로 설정한 경우 schedule 항목의
beginDate(시작일), beginTime(시작시간),
endDate(종료일), endTime(종료시간)을 필수로 전달
또한 allAvailableDeviceType 가 true 여야함		 O
price Long 발송단가타겟 정보가 변경되는 경우 건당 금액 변경됨 타게팅이 적용되지 않은 경우 15원, 타게팅이 적용된 경우 20원 O
pushAlarm boolean 푸시알림 보내지 않기
보내지 않기 (true),
보내기 (false) 중 하나		 O
sendRate Integer 분산발송 하기
분산발송 하기 (100, 500, 1000, 1500, 2000),
분산발송 하지 않기 (0) 중 하나		 O
status String 메시지 발송 상태
SAVE (고정값)		 O
syncStatus String 발송시스템과의 연동 상태
READY (고정값)		 O
ageVerification Boolean 연령인증 메시지 여부
true: 연령인증 메시지
false: 일반 메시지		 O

응답

본문
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹명
config String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
smartMessage Boolean 스마트 메시지 여부
pricingType PricingType 과금 방식
CPMS
bidAmount Integer 입찰금액
bidStrategy String 입찰 방식
MANUAL(수동) 고정값
totalBudget Long 구매 금액
totalBudgetWithVAT Long VAT 포함 기간 예산
status String[] 상태, Status 참고
placements Placement 게재 지면
targeting Targeting 타게팅
schedule Schedule 스케줄
messageSendingInfo MessageSendingInfo 메시지
profileId String 카카오톡 채널 프로필 아이디
campaign Campaign 캠페인
useWifiOnly Boolean WIFI에서만 노출 여부
creativeCount Long 등록된 소재수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
allAvailablePlacement Boolean 가능한 모든 지면 노출
adult Boolean 성인 타게팅 여부
false : 성인 타게팅 비허용
isDailyBudgetAmountOver Boolean 일 예산 초과 여부
isValidPeriod Boolean 집행기간 유효 여부
createdDate String 광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

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

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/adGroups" \
    -H "Authorization: Bearer ${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"
}

메시지 광고그룹 수정하기

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
campaign Campaign 캠페인 O
name String 광고그룹 이름
최대 50자
요청 시 포함되지 않으면 자동 생성		 X
placements String[] 게재 지면
고정값(KAKAO_TALK)		 O
adServingCategories String[] 게재 지면 네트워크 하위
placements에 NETWORK가 요청되었을 경우에 해당 필드는 필수로 요청
캠페인 유형이 카카오 비즈보드인 경우에는 요청 불가능
네트워크 게재지면 하위 목록 보기를 사용하여 응답 JSON 중에 code를 사용하여 요청		 O*
sectionCategories String[] 섹션 카테고리
캠페인 유형이 카카오 비즈보드이고, placements에 KAKAO_TALK 요청되었을 경우 선택 가능
그 외의 경우 요청 불가
섹션 카테고리 목록 보기 API의 응답 JSON 중 code를 사용하여 요청		 X
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
캠페인 유형이 디스플레이 X 방문인 경우에만 true 설정 가능
true로 설정할 경우 하단의 deviceTypes에 ANDROID, IOS, PC 가 String[]으로 요청되어야 함		 O
allAvailablePlacement Boolean 가능한 모든 지면 노출
false만 전달 가능		 O
deviceTypes String[] 디바이스
ANDROID(안드로이드),
IOS(IOS)
캠페인 유형이 디스플레이 X 방문이 아닌 경우 ANDROID, IOS만 요청 가능
allAvailableDeviceType(가능한 모든 디바이스 노출)을 true로 설정한 경우 ANDROID, IOS, PC 모두 요청해야 함		 O
messageSendingInfo MessageSendingInfo 메시지 정보 O
targeting Targeting 타게팅 O
adult Boolean 성인 타게팅 여부
사용하지 않음 (false)로 요청		 O
dailyBudgetAmount Integer 일 예산 O
bidStrategy String 입찰 방식
고정값 MANUAL(수동)		 O
pricingType String 수동 입찰 방식
고정값(CPMS)		 O
smartMessage Boolean 스마트 메시지 사용여부
사용 (true), 사용하지 않음 (false) 중 하나
메시지 발송 중 실시간으로 수집한 데이터를 바탕으로 소재를 클릭한 친구와 유사한 친구를 찾아 메시지를 발송하며
성능 최적화를 위해 친구의 최대 50%를 대상으로 발송이 가능하며, 10만 이상의 친구를 가진 채널에만 제공 또한 맞춤타겟의 타겟 정보는 설정이 불가능
소재최적화 기능을 사용하면 성과가 좋은 소재들의 노출 기회를 높여 광고그룹의 효율을 향상시킴
최대 10개의 소재를 등록할 수 있으며, 성능 최적화를 위해 최소 3만의 예상 발송 모수가 필요		 O
bidAmount Integer 수동 입찰금액 (발송단가)
메시지 정보(MessageSendingInfo)의 price와 같은 값으로 요청		 O
pacing String 게재 방식
고정값 NONE 으로 요청		 O
schedule Schedule 스케줄 정보 O

응답

본문
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹명
config String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
smartMessage Boolean 스마트 메시지 여부
pricingType PricingType 과금 방식
CPMS
bidAmount Integer 입찰금액
bidStrategy String 입찰 방식
MANUAL(수동) 고정값
totalBudget Long 구매 금액
totalBudgetWithVAT Long VAT 포함 기간 예산
status Status 상태
placements Placement 게재 지면
targeting Targeting 타게팅
schedule Schedule 스케줄
messageSendingInfo MessageSendingInfo 메시지 정보
profileId String 카카오톡 채널 프로필 아이디
campaign Campaign 캠페인
useWifiOnly Boolean WIFI에서만 노출 여부
creativeCount Long 등록된 소재수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
allAvailablePlacement Boolean 가능한 모든 지면 노출
adult Boolean 성인 타게팅 여부
false : 성인 타게팅 비허용
isDailyBudgetAmountOver Boolean 일 예산 초과 여부
isValidPeriod Boolean 집행기간 유효 여부
createdDate String 광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

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

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups" \
    -H "Authorization: Bearer ${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",
}

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

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/targetings/populationScore 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
campaignTypeGoal CampaignTypeGoal 캠페인 유형 X 목표 O
objective Objective 광고 목표 대상
캠페인 유형 X 목표가 채널 X 도달인 경우 채널 필수		 O*
placements String[] 게재 지면
고정값(KAKAO_TALK)		 O
adServingCategories String[] 게재 지면 네트워크 하위
placements에 NETWORK가 요청되었을 경우에 해당 필드는 필수로 요청
캠페인 유형이 카카오 비즈보드인 경우에는 요청 불가능
네트워크 게재지면 하위 목록 보기를 사용하여 응답 JSON 중에 code를 사용하여 요청		 O*
allAvailableDeviceType Boolean 가능한 모든 디바이스 노출
캠페인 유형이 디스플레이 X 방문인 경우에만 true 설정 가능
true로 설정할 경우 하단의 deviceTypes에 ANDROID, IOS, PC가 String[]으로 요청되어야 함		 O
allAvailablePlacement Boolean 가능한 모든 지면 노출
false만 전달 가능		 O
deviceTypes String[] 디바이스
ANDROID(안드로이드),
IOS(IOS)
캠페인 유형이 디스플레이 X 방문이 아닌 경우 ANDROID, IOS만 요청 가능
allAvailableDeviceType(가능한 모든 디바이스 노출)을 true로 설정한 경우 ANDROID, IOS, PC 모두 요청해야 함		 O
targeting Targeting 타게팅 O
smartMessage Boolean 스마트 메시지 사용여부
사용 (true), 사용하지 않음 (false) 중 하나
메시지 발송 중 실시간으로 수집한 데이터를 바탕으로 소재를 클릭한 친구와 유사한 친구를 찾아 메시지를 발송하며
성능 최적화를 위해 친구의 최대 50%를 대상으로 발송이 가능하며, 10만 이상의 친구를 가진 채널에만 제공 또한 맞춤타겟의 타겟 정보는 설정이 불가능
소재최적화 기능을 사용하면 성과가 좋은 소재들의 노출 기회를 높여 광고그룹의 효율을 향상시킴
최대 10개의 소재를 등록할 수 있으며, 성능 최적화를 위해 최소 3만의 예상 발송 모수가 필요		 O

응답

본문
이름 타입 설명
populationScore Long 해당 타겟팅의 모수

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/targetings/populationScore" \
    -H "Authorization: Bearer ${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
}

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

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups/cancel/${ID} 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 메시지 광고그룹 ID O

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/cancel/${ID}" \
    -H "Authorization: Bearer ${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

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

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/adGroups 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

집행 전략

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

집행 대상

주의: 개인정보 처리에 따른 의무사항

카카오 광고 통합서비스 이용을 위해 이용자의 개인정보를 카카오에 위탁하는 경우 광고주는 이 사실을 이용자에게 안내해야 합니다. 또한, 광고주는 관련된 법률에 따라 이용자에게 동의받은 목적으로만 개인정보를 이용해야 합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
campaign Campaign 캠페인 O
name String 광고그룹 이름
요청 시 포함되지 않으면 자동 생성
(최대: 50자)		 X

응답

본문
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹명
config String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
pricingType PricingType 과금 방식
CPMS
status Status 상태
placements Placement 게재 지면
profileId String 카카오톡 채널 프로필 아이디
campaign Campaign 캠페인
creativeCount Long 등록된 소재 수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
createdDate String 광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/adGroups" \
    -H "Authorization: Bearer ${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"
}

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

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
campaign Campaign 캠페인 O
id Long 광고그룹 번호 O
name String 광고그룹 이름
요청 시 포함되지 않으면 자동 생성
(최대: 50자)		 X

응답

본문
이름 타입 설명
id Long 광고그룹 번호
name String 광고그룹명
config String 광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
pricingType PricingType 과금 방식
CPMS
status Status 상태
placements Placement 게재 지면
profileId String 카카오톡 채널 프로필 아이디
campaign Campaign 캠페인
creativeCount Long 등록된 소재 수
systemConfig String 광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
createdDate String 광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/adGroups" \
    -H "Authorization: Bearer ${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"
}

광고그룹 상태 변경하기

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adGroups/onOff 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 광고그룹 번호 O
config String ON, OFF 중 하나 O

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adGroups/onOff" \
    -H "Authorization: Bearer ${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": "광고그룹이 존재하지 않습니다."
    }
}

광고그룹 삭제하기

기본 정보
메서드 URL 인증 방식
DELETE https://apis.moment.kakao.com/openapi/v4/adGroups/${ID} 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

광고그룹을 삭제합니다.

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

광고그룹 삭제는 데이터 삭제를 의미하는 것이 아닌, 광고그룹 하위에 대한 운영을 포기한다는 의미입니다. 카카오 비즈보드 X 도달, 다음쇼핑, 카카오TV 유형 캠페인 하위 광고그룹은 삭제가 불가능합니다. 하위 소재중 삭제 불가한 소재가 포함되어 있지 않을 때만 삭제가 가능합니다. 광고그룹 삭제 시 다음의 제약사항이 있습니다. - 수정, 실시 중지 등의 광고그룹 관련 모든 기능 사용 불가 - 광고그룹에 속한 모든 광고가 운영 & 노출 중지 - 하위 모든 소재 삭제 - 단, 과거 운영 시점의 통계 내용 조회 가능

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 광고그룹 번호 O

예제

요청
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}" \
    -H "Authorization: Bearer ${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"
    }
}

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

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/latestSystemConfigHistory 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 광고그룹 번호 O

응답

본문
이름 타입 설명
id Long 시스템 정지 번호
systemConfig String 시스템 상태
reason String 시스템 정지 사유
detailReason String 시스템 정지 사유 상세, 있는 경우에만 응답에 포함
createdDate String 시스템 정지 사유 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 시스템 정지 사유 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

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

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/latestSystemConfigHistory" \
    -H "Authorization: Bearer ${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": "광고그룹이 존재하지 않습니다."
  }
}

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

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/systemConfigHistories 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱		 필요 -

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 광고그룹 번호 O

응답

본문
이름 타입 설명
- SystemStopReason[] 시스템 정지 사유 목록
SystemStopReason
이름 타입 설명
id Long 시스템 정지 번호
systemConfig String 시스템 상태
reason String 시스템 정지 사유
detailReason String 시스템 정지 사유 상세, 있는 경우에만 응답에 포함
createdDate String 시스템 정지 사유 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 시스템 정지 사유 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

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

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/systemConfigHistories" \
    -H "Authorization: Bearer ${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": "광고그룹이 존재하지 않습니다."
  }
}

더 보기

카카오모먼트> 광고 만들기: 광고그룹