본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

관련사이트
  • 문서
  • 카카오모먼트
  • 광고 생성: 광고그룹

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

카카오모먼트

광고그룹

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

광고그룹 목록 조회

기본 정보
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
쿼리 파라미터
이름타입설명필수
campaignIdLong캠페인 번호O
configString[]광고그룹 상태
아래 중 복수 선택 가능
ON
OFF
DEL
(기본값 : [ON, OFF])		X

응답

본문
이름타입설명
contentAdGroup[]광고그룹 정보 목록
AdGroup
이름타입설명
idLong광고그룹 번호
nameString광고그룹명
configString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
userConfigString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
참고: config와 동일한 값으로, config로 개선하기 이전에 사용하던 필드입니다. 현재 해당 필드는 사용이 불가하며, 히스토리 관리를 위한 조회용으로만 참고 가능합니다.
systemConfigString광고그룹 시스템 상태
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 ${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"

        }

    ]

}

광고그룹 조회

기본 정보
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/${ID}비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
경로 변수
이름타입설명필수
IDLong광고그룹 번호O

응답

본문: 디스플레이 광고그룹
이름타입설명
idLong광고그룹 번호
nameString광고그룹명
configString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
pacingPacing게재 방식
NONE, QUICK, NORMAL 중 하나
pricingTypePricingType과금 방식
CPM, CPC, CPA 중 하나
bidAmountInteger최대 입찰금액
bidStrategyString입찰 방식
MANUAL(수동), AUTOBID(자동입찰), OPTIMIZATION(목적 최적화) 중 하나
bidStrategyTargetBidStrategyTarget자동입찰 옵션
statusDescriptionString광고그룹의 게재와 관련된 현재 상태
statusString[]상태, Status 참고
optimizationStatusString[]최적화 상태, OptimizationStatus 참고
최적화 상태값이 없는 경우 응답에서 제외
deviceTypesEnumSet of DeviceType[]디바이스 타입
adServingCategoriesString[]게재 지면의 네트워크 하위 카테고리
sectionCategoriesString[]섹션 카테고리
(현재 카카오 비즈보드 캠페인 유형 '채팅탭에만 노출' 옵션으로만 지원)
placementsEnumSet of Placement[]게재 지면
targetingTargeting타게팅
scheduleSchedule스케줄
campaignCampaign캠페인
useWifiOnlyBooleanWIFI에서만 노출 여부
creativeCountInteger등록된 소재의 수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceTypeBoolean가능한 모든 디바이스 노출
allAvailablePlacementBoolean가능한 모든 지면 노출
adultBoolean성인 타게팅 여부
true : 성인 타게팅 허용
false : 성인 타게팅 비허용
totalBudgetLong총 예산
dailyBudgetAmountLong일 예산
isDailyBudgetAmountOverBoolean일 예산 초과 여부
isValidPeriodBoolean집행기간 유효 여부
createdDateString광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식
* adminStop: Deprecated, 관리자 정지 여부(Boolean), systemConfig로 변경
본문: 다이렉트 메시지 광고그룹
이름타입설명
idLong광고그룹 번호
nameString광고그룹명
configString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
smartMessageboolean스마트 메시지 여부
pricingTypePricingType과금 방식
CPMS
bidAmountInteger입찰금액
bidStrategyString입찰 방식
MANUAL(수동) 고정값
totalBudgetLong구매 금액
totalBudgetWithVATLongVAT 포함 기간 예산
statusString[]상태, Status 참고
placementsPlacement게재 지면
targetingTargeting타게팅
scheduleSchedule스케줄
messageSendingInfoMessageSendingInfo메시지
profileIdString카카오톡 채널 프로필 아이디
campaignCampaign캠페인
useWifiOnlyBooleanWIFI에서만 노출 여부
creativeCountLong등록된 소재수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceTypeBoolean가능한 모든 디바이스 노출
allAvailablePlacementBoolean가능한 모든 지면 노출
adultBoolean성인 타게팅 여부
false : 성인 타게팅 비허용
isDailyBudgetAmountOverBoolean일 예산 초과 여부
isValidPeriodBoolean집행기간 유효 여부
createdDateString광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString광고그룹 마지막 수정일시
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 ${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": "M55550301",

                "description": "전북특별자치도 전주시 덕진구 금암1동",

                "depth1Name": "전북특별자치도",

                "depth2Name": "전주시 덕진구",

                "depth3Name": "금암1동",

                "deprecated": true

            }

        ],

        "ufoInterests": [

                "I0202",

                "I020601",

                "I03",

                "I320104"

         ],

         "ufoDeprecatedInterests": [

                "I320104"

         ],

         "ufoBusinessTypes": [

                "P1021",

                "P2003"

         ],

         "ufoDeprecatedBusinessTypes": [

                "P2003"

         ]

    },

    "schedule": {

        "detailTime": false,

        "beginDate": "2022-05-20",

        "beginTime": "00:00:00",

        "mondayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "tuesdayTime":[

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "wednesdayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "thursdayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "fridayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "saturdayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "sundayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "lateNight": false

    },

    "campaign": {

        "id": 33626,

        "name": "픽셀&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 400 Bad request

Content-Type: application/json;charset=UTF-8

{

    "code": -813,

    "msg": "KakaoMomentException",

    "extras": {

        "detailCode": 32001,

       "detailMsg": "광고그룹이 존재하지 않습니다."

    }

}

디스플레이 광고그룹 생성

기본 정보
메서드URL인증 방식
POSThttps://apis.moment.kakao.com/openapi/v4/adGroups비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

캠페인의 하위에 디스플레이 광고그룹을 생성할 수 있습니다.

아래의 타게팅 설정, 집행전략 설정 등의 정보를 참고하여 요청 시 파라미터 값을 지정합니다.

집행전략 설정

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

최소
  • CPA: 100
  • CPC: 10
  • CPM: 100

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

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

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

최소
  • CPC: 10
  • CPM: 1,000

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

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

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

최소
  • CPV: 10

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

집행전략

그룹 일 예산

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

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

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

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

요청

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

입찰 방식 MANUAL(수동): NORMAL(일반게재), QUICK(빠른게재) 중 하나
입찰 방식 AUTOBID(자동): NONE		O
scheduleSchedule스케줄 정보O
* 특정 조건 만족 시 필수 파라미터, 이 외의 경우 필수 파라미터 아님
Campaign
이름타입설명
idLong캠페인 번호
Targeting
이름타입설명필수
idLong오디언스를 사용하는 경우 해당 오디언스의 IDX
typeString오디언스 사용여부
NORMAL(일반 타겟팅 설정), DISPLAY(디스플레이 오디언스 관리기능 설정), MESSAGE(메시지 오디언스 관리기능 설정) 중 하나
DISPLAY 또는 MESSAGE를 사용하는 경우 나머지 타겟 정보는 빈 값으로 요청
  • 광고타입이 DISPLAY인 경우, 오디언스도 DISPLAY로 요청해야 함
X
ageTypeString연령대 전체 선택 종류
ALL (전체 선택), NOT_ALL (부분 선택) 중 하나
adult(성인 타게팅 여부)가 true인 경우 해당 필드는 NOT_ALL로만 요청 가능		O
agesString[]연령대
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*
genderTypeString성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나		O
gendersString[]성별
M : 남자
F : 여자
genderType(성별 전체 선택 종류)이 ALL 인 경우 genders는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함		O*
ufoInterestsSet of UfoInterest맞춤타겟 > 카카오 데이터 > 카테고리 > 관심사
맞춤타겟 카테고리 타입 조회 참고		X
ufoBusinessTypesSet of UfoBusinessType맞춤타겟 > 카카오 데이터 > 카테고리 > 업종
맞춤타겟 카테고리 타입 조회 참고		X
locationTypeString지역선택 타입
ALL (전체선택), AREA (지역선택) 중 하나		O
locationsSet of Location데모그래픽 > 행정구역 > 시/도
시/도 조회 참고
locationType(ALL)으로 요청된 경우 해당 필드는 요청할 수 없음
캠페인 유형이 카카오 비즈보드인 경우 해외(Z)는 요청할 수 없음
locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 함께 요청 가능		X
depth2LocationsSet of Depth2Location데모그래픽 > 행정구역 > 시/군/구
시/군/구 조회 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야함. 행정구역 타게팅 세 가지 함께 요청 가능		X
depth3LocationsSet of Depth3Location데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 조회 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능		X
customerFileTargetingsSet of CustomerFileTargeting맞춤타겟 > 내 데이터 > 고객파일
타게팅 가능한 고객파일 목록 조회 API로 조회 가능한 정보를 활용		X
trackerTargetingsSet of TrackerTargeting맞춤타겟 > 내 데이터 > 픽셀 & SDK
타게팅 가능한 픽셀 & SDK 이벤트 목록 보기 API로 조회 가능한 정보를 활용		X
cohortTargetingsSet of CohortTargeting맞춤타겟 > 내 데이터 > 광고반응타겟
타게팅 가능한 광고반응 타겟 목록 보기 API로 조회 가능한 정보를 활용		X
talkChannelTargetingsSet of TalkChannelTargeting맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구
타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용		X
syncAppTargetingsSet of SyncAppTargeting맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자
타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용		X
talkChannelGroupTargetingsSet of TalkChannelGroupTargeting맞춤타겟 > 내 데이터 > 친구그룹
타게팅 가능한 친구그룹 목록 조회로 조회 가능한 정보를 활용
중요: 카카오톡 채널 X 도달 캠페인에서만 사용 가능		X
CustomerFileTargeting
이름타입설명필수
customerFileIdLong등록된 고객파일 번호O
inclusionTypeString포함 여부
INCLUDE (포함), EXCLUDE (제외) 중 하나		O
TrackerTargeting
이름타입설명필수
trackIdString트래킹 아이디O
inclusionTypeString포함여부
INCLUDE (포함),
EXCLUDE (제외) 중 하나		O
eventCodeString이벤트 코드
'모든 이벤트'의 경우 * 값으로 요청		O
trackRuleIdString트랙 룰 아이디O
trackRuleNameString트랙 룰 이름O
termInteger타겟 기간(최소: 1, 최대: 180)O
CohortTargeting
이름타입설명필수
cohortIdString등록된 광고반응 타겟 번호O
inclusionTypeString포함여부
INCLUDE(포함),
EXCLUDE(제외) 중 하나		O
TalkChannelTargeting
이름타입설명필수
profileIdString카카오톡 채널 프로필 ID

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

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

응답

본문
이름타입설명
idLong광고그룹 번호
nameString광고그룹 이름
configString광고그룹 상태
pacingString게재 종류
pricingTypeString과금 종류
bidAmountInteger광고그룹 입찰가
bidStrategyString입찰 방식
bidStrategyTargetBidStrategyTarget자동입찰 옵션
statusDescriptionString광고그룹 상태 설명
statusString[]광고그룹 상태, Status 참고
optimizationStatusString[]최적화 상태, OptimizationStatus 참고
최적화 상태값이 없는 경우 응답에서 제외
deviceTypesDeviceType[]디바이스
adServingCategoriesString[]게재 지면 네트워크의 하위
sectionCategoriesString[]섹션 카테고리
(현재 카카오 비즈보드 유형 '채팅탭에만 노출' 옵션으로만 지원)
placementsPlacement[]게재 지면
targetingTargeting타게팅
ScheduleSchedule스케줄
campaignCampaign캠페인
useWifiOnlyBooleanWIFI에서만 노출 여부
creativeCountLong하위에 등록된 소재 개수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceTypeBoolean가능한 모든 디바이스 지원 여부
allAvailablePlacementBoolean가능한 모든 게재 지면 지원 여부
adultBoolean성인 타게팅
totalBudgetInteger총 예산
dailyBudgetAmountLong일 예산
isDailyBudgetAmountOverBoolean광고그룹 일 예산 초과 여부
isValidPeriodBoolean집행 기간 유효 여부
createdDateString등록일시
lastModifiedDateString마지막 수정일시
* 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": "M55550301",

                "description": "전북특별자치도 전주시 덕진구 금암1동",

                "depth1Name": "전북특별자치도",

                "depth2Name": "전주시 덕진구",

                "depth3Name": "금암1동",

                "deprecated": true

            }

        ],

    },

    "schedule": {

        "detailTime": false,

        "beginDate": "2022-05-20",

        "beginTime": "00:00:00",

        "mondayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "tuesdayTime":[

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "wednesdayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "thursdayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "fridayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "saturdayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "sundayTime": [

            "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "1"

        ],

        "lateNight": false

    },

    "campaign": {

        "id": 33626,

        "name": "픽셀&SDK수정_카카오 비즈보드_방문_202204211136",

        "campaignTypeGoal": {

            "campaignType": "TALK_BIZ_BOARD",

            "goal": "VISITING"

        },

        "objective": null,

        "dailyBudgetAmount": null,

        "config": "ON",

        "statusDescription": "운영중",

        "trackId": null,

        "adAccountId": 27429,

        "status": [

            "LIVE"

        ],

        "systemConfig": "ON",

        "isDailyBudgetAmountOver": false,

        "adminStop": false

    },

    "useWifiOnly": false,

    "creativeCount": 0,

    "systemConfig": "ON",

    "allAvailableDeviceType": false,

    "allAvailablePlacement": true,

    "adult": false,

    "dailyBudgetAmount": 100000,

    "isDailyBudgetAmountOver": false,

    "isValidPeriod": true,

    "createdDate": "2022-05-20T15:57:51",

    "lastModifiedDate": "2022-05-20T15:57:51",

    "adminStop": false

}

디스플레이 광고그룹 수정

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

캠페인 하위의 디스플레이 광고그룹 상세 정보를 수정합니다.

광고그룹 수정 시에는 광고그룹 조회로 기존 광고그룹의 정보를 조회한 후 수정할 필드와 수정하지 않을 필드를 조합하여 요청해야 합니다. 수정을 원치 않는 필드도 기존 값으로 요청되어야 광고그룹의 정보를 유지할 수 있습니다.

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
본문
이름타입설명필수
idLong광고그룹 번호O
campaignCampaign캠페인O
nameString광고그룹 이름
최대 50자
요청 시 포함되지 않으면 생성 시 설정된 이름으로 대체		X
placementsString[]게재 지면
  • KAKAO_SERVICE: 카카오 서비스
  • KAKAO_TALK: 카카오톡
  • DAUM: 다음
  • NETWORK: 네트워크
O
adServingCategoriesString[]게재 지면 네트워크 하위
placements에 NETWORK가 요청되었을 경우에 해당 필드는 필수로 요청
캠페인 유형이 카카오 비즈보드인 경우에는 해당 필드 전체 값으로 요청
타게팅의 네트워크 하위 보기 API를 사용하여 응답 JSON 중에 code를 사용하여 요청		O*
sectionCategoriesString[]섹션 카테고리
캠페인 유형이 카카오 비즈보드이고, placements에 KAKAO_TALK 요청되었을 경우 선택 가능
그 외의 경우 요청 불가
섹션 카테고리 목록 조회 API의 응답 JSON 중에 code를 사용하여 요청		X
allAvailableDeviceTypeBoolean가능한 모든 디바이스 노출
캠페인 유형이 동영상 X 조회 또는 디스플레이 X 방문이거나 디스플레이 X 전환 중 광고 목표 대상이 픽셀 & SDK의 구매, 회원가입, 잠재고객, 서비스 신청, 장바구니인 경우에 true 설정 가능
요청 시 포함되지 않으면 true로 자동 전달
true로 설정할 경우 하단의 deviceTypes에 ANDROID, IOS, PC 가 Array of String으로 요청되어야 함		X
allAvailablePlacementBoolean가능한 모든 지면 노출
캠페인 유형이 디스플레이, 동영상, 카카오 비즈보드인 경우에만 true 설정 가능
요청 시 포함되지 않으면 true로 자동 전달		X
deviceTypesString[]디바이스
  • ANDROID: 안드로이드
  • IOS: IOS
  • PC: PC
캠페인 유형이 디스플레이 X 방문과 동영상 X 조회가 아닌 경우 ANDROID, IOS만 요청 가능
allAvailableDeviceType(가능한 모든 디바이스 노출)을 true로 설정한 경우 ANDROID, IOS, PC 모두 요청해야 함		O
targetingTargeting타게팅O
adultBoolean성인 타게팅 여부
true로 설정 시 20세 이상에게만 광고 노출이 가능
targeting.ages에 "20","25","30","35","40","45","50","55","60","65","70"을 배열에 담아 요청해야 함
광고그룹 생성시 성인 타게팅 여부 허용으로 했을 경우 허용 안함으로 변경은 불가능
요청 시 포함되지 않으면 false로 자동 전달		X
dailyBudgetAmountInteger일 예산O
bidStrategyString입찰 방식
MANUAL(수동), AUTOBID(자동입찰) 중 하나		O
pricingTypeString수동 입찰 방식
CPA, CPM, CPC, CPV 중 하나		O
bidAmountInteger수동 입찰금액
자동입찰일 경우 0 입력		O
bidStrategyTargetBidStrategyTarget자동입찰 옵션X
pacingString게재 방식
  • NORMAL: 일반게재
  • QUICK: 빠른게재
NONE (설정해제) 중 하나
단, 입찰방식이 MANUAL(수동)일 경우에만 설정 가능
카카오 비즈보드 X 전환 유형 하위에 광고그룹을 생성할 경우 NONE으로만 요청		O
scheduleSchedule스케줄 정보O
* 특정 조건 만족 시 필수 파라미터, 이 외의 경우 필수 파라미터 아님
Campaign
이름타입설명
idLong캠페인 번호
Targeting
이름타입설명필수
idLong오디언스를 사용하는 경우 해당 오디언스의 IDX
typeString오디언스 사용여부
NORMAL(일반 타겟팅 설정), DISPLAY(디스플레이 오디언스 관리기능 설정), MESSAGE(메시지 오디언스 관리기능 설정) 중 하나
DISPLAY 또는 MESSAGE를 사용하는 경우 나머지 타겟 정보는 빈 값으로 요청		X
ageTypeString연령대 전체 선택 종류
ALL (전체 선택), NOT_ALL (부분 선택) 중 하나
adult(성인 타게팅 여부)가 true인 경우 해당 필드는 NOT_ALL로만 요청 가능		O
agesString[]연령대
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*
genderTypeString성별 전체 선택 종류
ALL (전체), NOT_ALL (부분 선택) 중 하나		O
gendersString[]성별
M : 남자
F : 여자
genderType(성별 전체 선택 종류)이 ALL 인 경우 genders는 요청하지 않아야 하며 NOT_ALL 일 경우에는 요청되어야 함		O*
ufoInterestsSet of UfoInterest맞춤타겟 > 카카오 데이터 > 카테고리 > 관심사
맞춤 타겟 카테고리 타입 보기 참고		X
ufoBusinessTypesSet of UfoBusinessType맞춤타겟 > 카카오 데이터 > 카테고리 > 업종
맞춤타겟 카테고리 타입 조회 참고		X
locationTypeString지역선택 타입
ALL (전체선택), AREA (지역선택) 중 하나		O
locationsSet of Location데모그래픽 > 행정구역 > 시/도
시/도 조회 참고
locationType(ALL)으로 요청된 경우 해당 필드는 요청할 수 없음
캠페인 유형이 카카오 비즈보드인 경우 해외(Z)는 요청할 수 없음
locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 함께 요청 가능		X
depth2LocationsSet of Depth2Location데모그래픽 > 행정구역 > 시/군/구
시/군/구 조회 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야함. 행정구역 타게팅 세 가지 함께 요청 가능		X
depth3LocationsSet of Depth3Location데모그래픽 > 행정구역 > 동/읍/면
동/읍/면 조회 참고
locationType(AREA)로 요청한 경우 locations(시/도) 타게팅, depth2Locations(시/군/구) 타게팅, depth3Locations(동/읍/면) 타게팅 중 하나는 요청해야 함
행정구역 타게팅 세 가지 함께 요청 가능		X
customerFileTargetingsSet of CustomerFileTargeting맞춤타겟 > 내 데이터 > 고객파일
타게팅 가능한 고객파일 목록 조회 API로 조회 가능한 정보를 활용		X
trackerTargetingsSet of TrackerTargeting맞춤타겟 > 내 데이터 > 픽셀 & SDK
타게팅 가능한 픽셀 & SDK 이벤트 목록 보기 API로 조회 가능한 정보를 활용		X
cohortTargetingsSet of CohortTargeting맞춤타겟 > 내 데이터 > 광고반응타겟
타게팅 가능한 광고반응 타겟 목록 보기 API로 조회 가능한 정보를 활용		X
talkChannelTargetingsSet of TalkChannelTargeting맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구
타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용		X
syncAppTargetingsSet of SyncAppTargeting맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자
타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용		X

응답

본문
이름타입설명
idLong광고그룹 번호
nameString광고그룹 이름
configString광고그룹 상태
pacingString게재 종류
pricingTypeString과금 종류
bidAmountInteger광고그룹 입찰가
bidStrategyString입찰 방식
bidStrategyTargetBidStrategyTarget자동입찰 옵션
statusDescriptionString광고그룹 상태 설명
statusString[]광고그룹 상태, Status 참고
optimizationStatusString[]최적화 상태, OptimizationStatus 참고
최적화 상태값이 없는 경우 응답에서 제외
deviceTypesString[]디바이스
adServingCategoriesString[]게재 지면 네트워크의 하위
sectionCategoriesString[]섹션 카테고리
(현재 카카오 비즈보드 유형 '채팅탭에만 노출' 옵션으로만 지원)
placementsPlacement[]게재 지면
targetingTargeting타게팅
ScheduleSchedule스케줄
campaignCampaign캠페인
useWifiOnlyBooleanWIFI에서만 노출 여부
creativeCountLong하위에 등록된 소재 개수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceTypeBoolean가능한 모든 디바이스 지원 여부
allAvailablePlacementBoolean가능한 모든 게재 지면 지원 여부
adultBoolean성인 타게팅
totalBudgetInteger총 예산
dailyBudgetAmountLong일 예산
isDailyBudgetAmountOverBoolean광고그룹 일 예산 초과 여부
isValidPeriodBoolean집행 기간 유효 여부
createdDateString등록일시
lastModifiedDateString마지막 수정일시
* 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

}

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

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups/dailyBudgetAmount비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

디스플레이 광고그룹 일 예산을 변경합니다.

일 예산은 최소 1만 원에서 최대 5억 원까지 설정 가능하며 10원 단위로 가능합니다. 캠페인 일예산이 설정되어 있는 경우, 광고그룹 일예산은 캠페인 일예산보다 작거나 같아야 합니다.

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

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

요청

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

예제

요청
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만원보다 크거나 같아야 합니다."

    }

}

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

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups/bidAmount비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

디스플레이 광고그룹 최대 입찰금액을 수정합니다.

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

입찰금액 최소 값은 광고그룹 타입, 광고 목적, 과금방식에 따라 다릅니다. 또한 입찰금액은 광고그룹에서 설정한 일예산의 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% 이하 중 작은 값
동영상기본
  • CPV: 20

최소
  • CPV: 10

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

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

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

요청

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

예제

요청
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": "관련 작업을 지원하지 않는 광고그룹입니다."

    }

}

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

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups/pacing비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

디스플레이 광고그룹 게재 방식을 변경하는 API로 디스플레이, 동영상, 비즈보드 유형 (도달 목표 제외) 캠페인 하위 광고그룹만 가능합니다.

입찰 방식이 수동(MANUAL)일 경우에만 설정 가능하고, 그 외의 입찰 방식은 게재 방식을 설정할 수 없습니다.

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

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

요청

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

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

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

예제

요청
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": "게재방식을 선택할 수 없습니다."

    }

}

메시지 광고그룹 생성

기본 정보
메서드URL인증 방식
POSThttps://apis.moment.kakao.com/openapi/v4/adGroups비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

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

비즈니스 토큰과 광고계정 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만의 예상 발송 모수가 필요합니다.

기타 설정

분산 발송하기

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

푸시 알림 보내지 않기

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
본문
이름타입설명필수
campaignCampaign캠페인O
nameString광고그룹 이름
최대 50자
요청 시 포함되지 않으면 자동 생성		X
placementsString[]게재 지면
고정값(KAKAO_TALK)		O
allAvailableDeviceTypeBoolean가능한 모든 디바이스 노출
캠페인 유형이 디스플레이 X 방문인 경우에만 true 설정 가능
true로 설정할 경우 하단의 deviceTypes에 ANDROID, IOS, PC 가 Array of String으로 요청되어야 함		O
allAvailablePlacementBoolean가능한 모든 지면 노출
false만 전달 가능		O
deviceTypesString[]디바이스
ANDROID (안드로이드),
IOS (IOS)
캠페인 유형이 디스플레이 X 방문이 아닌 경우 ANDROID, IOS만 요청 가능
allAvailableDeviceType (가능한 모든 디바이스 노출)을 true로 설정한 경우 ANDROID, IOS, PC 모두 요청해야 함		O
messageSendingInfoMessageSendingInfo메시지 정보O
targetingTargeting타게팅O
adultBoolean성인 타게팅 여부
사용하지 않음 (false)로 요청		O
bidStrategyString입찰 방식
고정값 MANUAL(수동)		O
pricingTypeString수동 입찰 방식
고정값(CPMS)		O
bidAmountInteger수동 입찰금액(발송단가)
메시지 정보 (MessageSendingInfo)의 price와 같은 값으로 요청		O
pacingString게재 방식
고정값 NONE 으로 요청		O
scheduleSchedule스케줄 정보O
smartMessageBoolean스마트 메시지 사용여부
사용 (true), 사용하지 않음 (false) 중 하나
메시지 발송 중 실시간으로 수집한 데이터를 바탕으로 소재를 클릭한 친구와 유사한 친구를 찾아 메시지를 발송하며
성능 최적화를 위해 친구의 최대 50%를 대상으로 발송이 가능하며, 10만 이상의 친구를 가진 채널에만 제공 또한 맞춤타겟의 타겟 정보는 설정이 불가능
소재최적화 기능을 사용하면 성과가 좋은 소재들의 노출 기회를 높여 광고그룹의 효율을 향상시킴
최대 10개의 소재를 등록할 수 있으며, 성능 최적화를 위해 최소 3만의 예상 발송 모수가 필요		O
MessageSendingInfo
이름타입설명필수
contractCountInteger구매발송수
예상 발송 모수보다 작게 설정할 수 없음		O
longTermboolean전체발송 후 새 친구에게도 보내기
보내기 (true),
보내지 않기 (false) 중 하나
실시간 타겟 선택시 해당 필드는 false로 요청되어야 함
또한 보내기로 설정한 경우 schedule 항목의
beginDate(시작일), beginTime(시작시간),
endDate(종료일), endTime(종료시간)을 필수로 전달
또한 allAvailableDeviceType 가 true 여야함		O
priceLong발송단가타겟 정보가 변경되는 경우 건당 금액 변경됨 타게팅이 적용되지 않은 경우 15원, 타게팅이 적용된 경우 20원O
pushAlarmboolean푸시알림 보내지 않기
보내지 않기 (true),
보내기 (false) 중 하나		O
sendRateInteger분산발송 하기
분산발송 하기 (100, 500, 1000, 1500, 2000),
분산발송 하지 않기 (0) 중 하나		O
statusString메시지 발송 상태
SAVE (고정값)		O
syncStatusString발송시스템과의 연동 상태
READY (고정값)		O
ageVerificationBoolean연령인증 메시지 여부
  • true: 연령인증 메시지
  • false: 일반 메시지
O

응답

본문
이름타입설명
idLong광고그룹 번호
nameString광고그룹명
configString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
smartMessageBoolean스마트 메시지 여부
pricingTypePricingType과금 방식
CPMS
bidAmountInteger입찰금액
bidStrategyString입찰 방식
MANUAL(수동) 고정값
totalBudgetLong구매 금액
totalBudgetWithVATLongVAT 포함 기간 예산
statusString[]상태, Status 참고
placementsPlacement게재 지면
targetingTargeting타게팅
scheduleSchedule스케줄
messageSendingInfoMessageSendingInfo메시지
profileIdString카카오톡 채널 프로필 아이디
campaignCampaign캠페인
useWifiOnlyBooleanWIFI에서만 노출 여부
creativeCountLong등록된 소재수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceTypeBoolean가능한 모든 디바이스 노출
allAvailablePlacementBoolean가능한 모든 지면 노출
adultBoolean성인 타게팅 여부
false : 성인 타게팅 비허용
isDailyBudgetAmountOverBoolean일 예산 초과 여부
isValidPeriodBoolean집행기간 유효 여부
createdDateString광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString광고그룹 마지막 수정일시
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 ${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"

}

메시지 광고그룹 수정

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

카카오톡 채널 X 도달 캠페인 하위의 광고 그룹의 상세 정보를 수정합니다.

광고 그룹 수정 시에는 광고 그룹 보기 API로 기존 광고 그룹의 정보를 조회한 아래에 수정할 필드와 수정하지 않을 필드를 조합해 요청해야 합니다. 수정을 원치 않는 필드도 기존 값으로 요청되어야 광고 그룹의 정보를 유지할 수 있습니다.

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

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

요청

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

응답

본문
이름타입설명
idLong광고그룹 번호
nameString광고그룹명
configString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
smartMessageBoolean스마트 메시지 여부
pricingTypePricingType과금 방식
CPMS
bidAmountInteger입찰금액
bidStrategyString입찰 방식
MANUAL(수동) 고정값
totalBudgetLong구매 금액
totalBudgetWithVATLongVAT 포함 기간 예산
statusStatus상태
placementsPlacement게재 지면
targetingTargeting타게팅
scheduleSchedule스케줄
messageSendingInfoMessageSendingInfo메시지 정보
profileIdString카카오톡 채널 프로필 아이디
campaignCampaign캠페인
useWifiOnlyBooleanWIFI에서만 노출 여부
creativeCountLong등록된 소재수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
allAvailableDeviceTypeBoolean가능한 모든 디바이스 노출
allAvailablePlacementBoolean가능한 모든 지면 노출
adultBoolean성인 타게팅 여부
false : 성인 타게팅 비허용
isDailyBudgetAmountOverBoolean일 예산 초과 여부
isValidPeriodBoolean집행기간 유효 여부
createdDateString광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString광고그룹 마지막 수정일시
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 ${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",

}

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

기본 정보
메서드URL인증 방식
POSThttps://apis.moment.kakao.com/openapi/v4/targetings/populationScore비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

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

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

요청

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

응답

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

예제

요청
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

}

메시지 광고그룹 계약 해지

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups/cancel/${ID}비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
경로 변수
이름타입설명필수
IDLong메시지 광고그룹 IDO

예제

요청
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

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

기본 정보
메서드URL인증 방식
POSThttps://apis.moment.kakao.com/openapi/v4/adGroups비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

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

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

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

집행 전략

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

집행 대상

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
본문
이름타입설명필수
campaignCampaign캠페인O
nameString광고그룹 이름
요청 시 포함되지 않으면 자동 생성
(최대: 50자)		X

응답

본문
이름타입설명
idLong광고그룹 번호
nameString광고그룹명
configString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
pricingTypePricingType과금 방식
CPMS
statusStatus상태
placementsPlacement게재 지면
profileIdString카카오톡 채널 프로필 아이디
campaignCampaign캠페인
creativeCountLong등록된 소재 수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
createdDateString광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
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"

}

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

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

개인화 메시지 X 도달 캠페인 하위의 광고 그룹의 상세 정보를 수정합니다.

수정 가능한 항목은 광고그룹의 이름이며 기타 광고그룹 정보는 수정이 불가합니다.

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
본문
이름타입설명필수
campaignCampaign캠페인O
idLong광고그룹 번호O
nameString광고그룹 이름
요청 시 포함되지 않으면 자동 생성
(최대: 50자)		X

응답

본문
이름타입설명
idLong광고그룹 번호
nameString광고그룹명
configString광고그룹 상태
ON, OFF, DEL(삭제) 중 하나
pricingTypePricingType과금 방식
CPMS
statusStatus상태
placementsPlacement게재 지면
profileIdString카카오톡 채널 프로필 아이디
campaignCampaign캠페인
creativeCountLong등록된 소재 수
systemConfigString광고그룹 시스템 상태
ON, ADMIN_STOP(관리자정지), EXTERNAL_SERVICE_STOP(연결 서비스 제한) 중 하나
createdDateString광고그룹 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString광고그룹 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
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"

}

광고그룹 상태 변경

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/adGroups/onOff비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

광고그룹 상태를 ON, OFF 중에서 변경합니다.

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

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
본문
이름타입설명필수
idLong광고그룹 번호O
configStringON, OFF 중 하나O

예제

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

    }

}

광고그룹 삭제

기본 정보
메서드URL인증 방식
DELETEhttps://apis.moment.kakao.com/openapi/v4/adGroups/${ID}비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

광고그룹을 삭제합니다.

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

삭제 시 주의 사항

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
경로 변수
이름타입설명필수
IDLong광고그룹 번호O

예제

요청
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}" \

  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \

  -H "adAccountId: ${AD_ACCOUNT_ID}" \

  -H "Content-Type: application/json"
응답: 성공
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인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/latestSystemConfigHistory비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

지정한 한 광고그룹의 시스템 정지 사유를 조회합니다.

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
경로 변수
이름타입설명필수
IDLong광고그룹 번호O

응답

본문
이름타입설명
idLong시스템 정지 번호
systemConfigString시스템 상태
reasonString시스템 정지 사유
detailReasonString시스템 정지 사유 상세, 있는 경우에만 응답에 포함
createdDateString시스템 정지 사유 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString시스템 정지 사유 마지막 수정일시
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 ${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": "광고그룹이 존재하지 않습니다."

  }

}

광고그룹 시스템 정지 사유 목록 조회

기본 정보
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/systemConfigHistories비즈니스 토큰
권한사전 설정비즈니스 인증비즈니스 동의항목
필요: 사용 권한 신청비즈 앱 전환
비즈니스 인증 리다이렉트 URI
비즈니스 동의항목		필요필요

지정한 한 광고그룹의 최근 2년 동안의 시스템 정지 사유를 조회합니다.

광고그룹의 systemConfig가 ADMIN_STOP 또는 EXTERNAL_SERVICE_STOP인 경우에만 응답이 있습니다.

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		O
경로 변수
이름타입설명필수
IDLong광고그룹 번호O

응답

본문
이름타입설명
-SystemStopReason[]시스템 정지 사유 목록
SystemStopReason
이름타입설명
idLong시스템 정지 번호
systemConfigString시스템 상태
reasonString시스템 정지 사유
detailReasonString시스템 정지 사유 상세, 있는 경우에만 응답에 포함
createdDateString시스템 정지 사유 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDateString시스템 정지 사유 마지막 수정일시
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 ${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": "광고그룹이 존재하지 않습니다."

  }

}

더 보기

도움이 되었나요?