카카오모먼트

광고그룹

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

광고그룹 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고그룹 목록을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

쿼리 파라미터

이름	타입	설명	필수
campaignId	`Long`	캠페인 번호	O
config	`Enum: Config[]`	광고그룹 상태(기본값: `ON`, `OFF`)	X

응답

본문

이름	타입	설명
content	`AdGroup[]`	광고그룹 정보 목록

AdGroup

이름	타입	설명
id	`Long`	광고그룹 번호
name	`String`	광고그룹명
config	`Enum: Config`	광고그룹 상태
userConfig	`Enum: Config`	광고그룹 상태 참고: `config`와 동일한 값으로, `config`로 개선하기 이전에 사용하던 필드입니다. 현재 해당 필드는 사용이 불가하며, 히스토리 관리를 위한 조회용으로만 참고 가능합니다.
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

각 광고그룹 상세 정보를 반환합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Long`	광고그룹 번호	O

응답

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

이름	타입	설명
id	`Long`	광고그룹 번호
name	`String`	광고그룹명
config	`Enum: Config`	광고그룹 상태
pacing	`Enum: Pacing`	게재 방식
pricingType	`Enum: PricingType`	과금 방식 `CPM`: Cost per Mille `CPC`: Cost per Click `CPA`: Cost per Action
bidAmount	`Integer`	최대 입찰금액
bidStrategy	`Enum`	입찰 방식 `MANUAL`: 수동 `AUTOBID`: 자동입찰 `OPTIMIZATION`: 목적 최적화
bidStrategyTarget	`BidStrategyTarget`	자동입찰 옵션
statusDescription	`String`	광고그룹의 게재와 관련된 현재 상태
status	`Enum: Status[]`	상태
optimizationStatus	`Enum: OptimizationStatus[]`	최적화 상태 제공 조건: 최적화 상태값이 있는 경우
deviceTypes	`Enum: DeviceType[]`	디바이스 타입
adServingCategories	`String[]`	게재 지면의 네트워크 하위 카테고리
sectionCategories	`String[]`	섹션 카테고리 참고: 캠페인 유형이 카카오 비즈보드, 디스플레이, 동영상, 상품 카탈로그인 경우에만 제공
placements	`Enum: Placement[]`	게재 지면
targeting	`Targeting`	타게팅
schedule	`Schedule`	스케줄
campaign	`Campaign`	캠페인
useWifiOnly	`Boolean`	WIFI에서만 노출 여부
creativeCount	`Integer`	등록된 소재의 수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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	`Enum: Config`	광고그룹 상태
smartMessage	`Boolean`	스마트 메시지 여부
pricingType	`Enum: PricingType`	과금 방식 `CPMS`: Cost per Message Send
bidAmount	`Integer`	입찰금액
bidStrategy	`String`	입찰 방식 `MANUAL`(수동)으로 고정
totalBudget	`Long`	구매 금액
totalBudgetWithVAT	`Long`	VAT 포함 기간 예산
status	`Enum: Status[]`	상태
placements	`Enum: Placement[]`	게재 지면
targeting	`Targeting`	타게팅
schedule	`Schedule`	스케줄
messageSendingInfo	`MessageSendingInfo`	메시지
profileId	`String`	카카오톡 채널 프로필 아이디
campaign	`Campaign`	캠페인
useWifiOnly	`Boolean`	WIFI에서만 노출 여부
creativeCount	`Long`	등록된 소재수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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 ${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",
        "description": "경기도 여주시",
        "depth1Name": "경기도",
        "depth2Name": "여주시"
      },
      {
        "value": "I1009",
        "description": "서울특별시 도봉구",
        "depth1Name": "광주광역시",
        "depth2Name": "도봉구"
      }
    ],
    "depth3Locations": [
      {
        "value": "A70052424",
        "description": "강원도 삼척시 원덕읍",
        "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	인증 방식
`POST`	`https://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% 입력 단위: 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% 이하 중 작은 값	미제공

기본값

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만

동영상

기본값

CPV: 20

최소

CPV: 10

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

미제공

집행전략

그룹 일 예산

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

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

집행 기간

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

시작일	종료일	요일	시작시간/종료시간
오늘부터 최대 6개월 이후 날짜까지 선택 가능 기본값: 오늘 날짜	시작일부터 이후 날짜 선택 가능 "종료일 없음" 상태 선택 가능 기본값: 종료일 없음	선택불가 기본값: 전체	선택불가 단, 심야타게팅 (22:00~06:59)은 설정 가능

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
campaign	`Campaign`	캠페인	O
name	`String`	광고그룹 이름(최대: 50자) 생략 시 자동 생성	X
placements	`Enum: Placement[]`	게재 지면	O
adServingCategories	`String[]`	게재 지면 네트워크 하위 캠페인 유형이 카카오 비즈보드인 경우에는 해당 필드 전체 값으로 요청 네트워크 게재지면 하위 목록 조회 API를 사용하여 응답 JSON 중에 `code`를 사용하여 요청 중요: `placements`에 `NETWORK`가 요청되었을 경우에 해당 필드는 필수로 요청	X
sectionCategories	`String[]`	섹션 카테고리 섹션 카테고리 목록 조회 API의 응답 `JSON` 중 `code`를 사용하여 요청 중요: 캠페인 유형이 카카오 비즈보드, 디스플레이, 동영상, 상품 카탈로그이고, `placements`에 `KAKAO_TALK` 요청되었을 경우 선택 가능, 그 외의 경우 요청 불가	X
allAvailableDeviceType	`Boolean`	가능한 모든 디바이스 노출(기본값: `true`) 중요: 캠페인 유형이 동영상 X 조회 또는 디스플레이 X 방문이거나, 디스플레이 X 전환 중 광고 목표 대상이 픽셀 & SDK의 구매, 회원가입, 잠재고객, 서비스 신청, 장바구니인 경우에만 `true` 요청 가능 중요: `true`인 경우 `deviceTypes`에 `ANDROID`, `IOS`, `PC` 모두 요청 필수	X
allAvailablePlacement	`Boolean`	가능한 모든 지면 노출(기본값: `true`) 중요: 캠페인 유형이 디스플레이, 동영상, 카카오 비즈보드인 경우에만 `true` 요청 가능	X
deviceTypes	`Enum: DeviceType[]`	디바이스 중요: 캠페인 유형이 디스플레이 X 방문과 동영상 X 조회가 아닌 경우 `ANDROID`, `IOS`만 요청 가능 중요: `allAvailableDeviceType`(가능한 모든 디바이스 노출)이 `true`인 경우 `ANDROID`, `IOS`, `PC` 모두 요청 필수	O
targeting	`Targeting`	타게팅	O
adult	`Boolean`	성인 타게팅 여부(기본값: `false`) 중요: `true`로 설정 시 20세 이상에게만 광고 노출 가능, `targeting.ages`에 `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70`을 배열에 담아 요청	X
dailyBudgetAmount	`Integer`	일 예산	O
bidStrategy	`Enum`	입찰 방식 `MANUAL`: 수동 `AUTOBID`: 자동입찰	O
pricingType	`Enum: PricingType`	수동 입찰 방식 `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View	O
bidAmount	`Integer`	수동 입찰금액 자동입찰일 경우 0 입력	O
bidStrategyTarget	`BidStrategyTarget`	자동입찰 옵션	X
pacing	`Enum: Pacing`	게재 방식 중요: `bidStrategy`(입찰 방식)가 `MANUAL`인 경우 `NORMAL` 또는 `QUICK`, `AUTOBID`인 경우 `NONE`으로 요청	O
schedule	`Schedule`	스케줄 정보	O

Campaign

이름	타입	설명
id	`Long`	캠페인 번호

Targeting

이름	타입	설명	필수
id	`Long`	오디언스를 사용하는 경우 해당 오디언스의 ID	X
type	`Enum`	오디언스 사용 여부 `NORMAL`: 일반 타겟팅 설정 `DISPLAY`: 디스플레이 오디언스 관리기능 설정 `MESSAGE`: 메시지 오디언스 관리기능 설정 중요: `DISPLAY` 또는 `MESSAGE`인 경우 나머지 타겟 정보는 빈 값으로 요청 중요: 광고 유형이 `DISPLAY`인 경우 오디언스 유형도 `DISPLAY`로 요청 필수	X
ageType	`Enum`	연령대 전체 선택 종류 `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`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가 중요: `adult`(성인 타게팅 여부)가 `true`인 경우 `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70`을 배열에 담아 요청	X
genderType	`Enum`	성별 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택	O
genders	`String[]`	성별 `M`: 남자 `F`: 여자 중요: `genderType`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가	X
ufoInterests	`UfoInterest[]`	맞춤타겟 > 카카오 데이터 > 카테고리 > 관심사 맞춤타겟 카테고리 타입 조회 API 참고	X
ufoBusinessTypes	`UfoBusinessType[]`	맞춤타겟 > 카카오 데이터 > 카테고리 > 업종 맞춤타겟 카테고리 타입 조회 API 참고	X
locationType	`Enum`	지역선택 타입 `ALL`: 국내 전체 `AREA`: 지역 선택 중요: `locationType`을 지정하지 않은 경우 전체 지역(국내 + 해외)으로 설정됨	X
locations	`Location[]`	데모그래픽 > 행정구역 > 시/도 시/도 조회 참고 중요: `locationType`이 `ALL`(국내 전체)인 경우 시/도 전체 코드(`A`, `B`, ...)와 알 수 없음(`U`)을 모두 포함해 요청, 해외(`Z`)는 제외 참고: `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면)와 함께 요청 가능	X
depth2Locations	`Depth2Location[]`	데모그래픽 > 행정구역 > 시/군/구 시/군/구 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
customerFileTargetings	`CustomerFileTargeting[]`	맞춤타겟 > 내 데이터 > 고객파일 타게팅 가능한 고객파일 목록 조회 API로 조회 가능한 정보를 활용	X
trackerTargetings	`TrackerTargeting[]`	맞춤타겟 > 내 데이터 > 픽셀 & SDK 타게팅 가능한 픽셀 & SDK 이벤트 목록 보기 API로 조회 가능한 정보를 활용	X
cohortTargetings	`CohortTargeting[]`	맞춤타겟 > 내 데이터 > 광고반응타겟 타게팅 가능한 광고반응 타겟 목록 보기 API로 조회 가능한 정보를 활용	X
talkChannelTargetings	`TalkChannelTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구 타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용	X
syncAppTargetings	`SyncAppTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자 타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용	X
talkChannelGroupTargetings	`TalkChannelGroupTargeting[]`	맞춤타겟 > 내 데이터 > 친구그룹 타게팅 가능한 친구그룹 목록 조회 API로 조회 가능한 정보를 활용 중요: 카카오톡 채널 X 도달 캠페인에서만 사용 가능	X

CustomerFileTargeting

이름	타입	설명	필수
customerFileId	`Long`	등록된 고객파일 번호	O
inclusionType	`Enum: InclusionType`	포함 여부	O

TrackerTargeting

이름	타입	설명	필수
trackId	`String`	트래킹 아이디	O
inclusionType	`Enum: InclusionType`	포함여부	O
eventCode	`String`	이벤트 코드 모든 이벤트의 경우 `*` 값으로 요청	O
trackRuleId	`String`	트랙 룰 아이디	O
trackRuleName	`String`	트랙 룰 이름	O
term	`Integer`	타겟 기간(최소: 1, 최대: 180)	O

CohortTargeting

이름	타입	설명	필수
cohortId	`String`	등록된 광고반응 타겟 번호	O
inclusionType	`Enum: InclusionType`	포함여부	O

TalkChannelTargeting

이름	타입	설명	필수
profileId	`String`	카카오톡 채널 프로필 ID 참고: 카카오톡 채널 프로필 ID 확인 방법	O
inclusionType	`Enum: InclusionType`	포함여부	O

SyncAppTargeting

이름	타입	설명	필수
profileId	String	카카오톡 채널 프로필 ID 참고: 카카오톡 채널 프로필 ID 확인 방법	O
inclusionType	`Enum: InclusionType`	포함여부	O

TalkChannelGroupTargeting

이름	타입	설명	필수
talkChannelGroupFileId	`Long`	친구그룹 파일 ID	O
name	`String`	친구그룹 이름	O
inclusionType	`Enum: InclusionType`	포함 여부	O
fileType	`Enum`	친구그룹 유형 `APP_USER_ID`: 앱유저아이디 `PHONE_NUMBER`: 전화번호 `MESSAGE_RETARGET`: 메시지 발송 대상자	O
groupKey	`String`	친구그룹 파일의 그룹 키	O

응답

본문

이름	타입	설명
id	`Long`	광고그룹 번호
name	`String`	광고그룹 이름
config	`Enum: Config`	광고그룹 상태
pacing	`Enum: Pacing`	게재 종류
pricingType	`Enum: PricingType`	과금 방식 `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View
bidAmount	`Integer`	광고그룹 입찰가
bidStrategy	`Enum`	입찰 방식 `MANUAL`: 수동 `AUTOBID`: 자동입찰 `OPTIMIZATION`: 목적 최적화
bidStrategyTarget	`BidStrategyTarget`	자동입찰 옵션
statusDescription	`String`	광고그룹 상태 설명
status	`Enum: Status[]`	광고그룹 상태
optimizationStatus	`Enum: OptimizationStatus[]`	최적화 상태 제공 조건: 최적화 상태값이 있는 경우
deviceTypes	`Enum: DeviceType[]`	디바이스
adServingCategories	`String[]`	게재 지면 네트워크의 하위
sectionCategories	`String[]`	섹션 카테고리 참고: 캠페인 유형이 카카오 비즈보드, 디스플레이, 동영상, 상품 카탈로그인 경우에만 제공
placements	`Enum: Placement[]`	게재 지면
targeting	`Targeting`	타게팅
schedule	`Schedule`	스케줄
campaign	`Campaign`	캠페인
useWifiOnly	`Boolean`	WIFI에서만 노출 여부
creativeCount	`Long`	하위에 등록된 소재 개수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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 ${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",
                        "description": "경기도 여주시",
                        "depth1Name": "경기도",
                         "depth2Name": "여주시"
                    },
                    {
                        "value": "I1009",
                        "description": "서울특별시 도봉구",
                        "depth1Name": "광주광역시",
                        "depth2Name": "도봉구"
                    }
                ],
        "depth3Locations": [
                {
                "value": "A70052424",
                "description": "강원도 삼척시 원덕읍",
                "depth1Name": "강원도",
                "depth2Name": "삼척시",
                "depth3Name": "원덕읍"
                },
                {
                "value": "E13010702",
                "description": "광주광역시 남구 백운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",
        "description": "경기도 여주시",
        "depth1Name": "경기도",
        "depth2Name": "여주시"
      },
      {
        "value": "I1009",
        "description": "서울특별시 도봉구",
        "depth1Name": "광주광역시",
        "depth2Name": "도봉구"
      }
    ],
    "depth3Locations": [
      {
        "value": "A70052424",
        "description": "강원도 삼척시 원덕읍",
        "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	인증 방식
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

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

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
id	`Long`	광고그룹 번호	O
campaign	`Campaign`	캠페인	O
name	`String`	광고그룹 이름(최대: 50자) 생략 시 이전 이름 유지	X
placements	`Enum: Placement[]`	게재 지면	O
adServingCategories	`String[]`	게재 지면 네트워크 하위 캠페인 유형이 카카오 비즈보드인 경우에는 해당 필드 전체 값으로 요청 타게팅의 네트워크 하위 보기 API를 사용하여 응답 JSON 중에 `code`를 사용하여 요청 중요: `placements`에 `NETWORK`가 요청되었을 경우에 해당 필드는 필수로 요청	X
sectionCategories	`String[]`	섹션 카테고리 섹션 카테고리 목록 조회 API의 응답 `JSON` 중에 `code`를 사용하여 요청 중요: 캠페인 유형이 카카오 비즈보드, 디스플레이, 동영상, 상품 카탈로그이고, `placements`에 `KAKAO_TALK` 요청되었을 경우 선택 가능, 그 외의 경우 요청 불가	X
allAvailableDeviceType	`Boolean`	가능한 모든 디바이스 노출(기본값: `true`) 중요: 캠페인 유형이 동영상 X 조회 또는 디스플레이 X 방문이거나, 디스플레이 X 전환 중 광고 목표 대상이 픽셀 & SDK의 구매, 회원가입, 잠재고객, 서비스 신청, 장바구니인 경우에만 `true` 요청 가능 중요: `true`인 경우 `deviceTypes`에 `ANDROID`, `IOS`, `PC` 모두 요청 필수	X
allAvailablePlacement	`Boolean`	가능한 모든 지면 노출(기본값: `true`) 중요: 캠페인 유형이 디스플레이, 동영상, 카카오 비즈보드인 경우에만 `true` 요청 가능	X
deviceTypes	`Enum: DeviceType[]`	디바이스 중요: 캠페인 유형이 디스플레이 X 방문과 동영상 X 조회가 아닌 경우 `ANDROID`, `IOS`만 요청 가능 중요: `allAvailableDeviceType`(가능한 모든 디바이스 노출)이 `true`인 경우 `ANDROID`, `IOS`, `PC` 모두 요청 필수	O
targeting	`Targeting`	타게팅	O
adult	`Boolean`	성인 타게팅 여부(기본값: `false`) 중요: `true`로 설정 시 20세 이상에게만 광고 노출 가능, `targeting.ages`에 `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70`을 배열에 담아 요청 중요: 광고그룹 생성 시 `true`로 설정한 경우 `false`로 변경 불가	X
dailyBudgetAmount	`Integer`	일 예산	O
bidStrategy	`Enum`	입찰 방식 `MANUAL`: 수동 `AUTOBID`: 자동입찰	O
pricingType	`Enum: PricingType`	수동 입찰 방식 `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View	O
bidAmount	`Integer`	수동 입찰금액 자동입찰일 경우 0 입력	O
bidStrategyTarget	`BidStrategyTarget`	자동입찰 옵션	X
pacing	`Enum: Pacing`	게재 방식 중요: `bidStrategy`(입찰 방식)가 `MANUAL`인 경우만 설정 가능 중요: 카카오 비즈보드 X 전환 유형 캠페인의 광고그룹은 `NONE`으로만 요청	O
schedule	`Schedule`	스케줄 정보	O

Campaign

이름	타입	설명
id	`Long`	캠페인 번호

Targeting

이름	타입	설명	필수
id	`Long`	오디언스를 사용하는 경우 해당 오디언스의 ID	X
type	`Enum`	오디언스 사용 여부 `NORMAL`: 일반 타겟팅 설정 `DISPLAY`: 디스플레이 오디언스 관리기능 설정 `MESSAGE`: 메시지 오디언스 관리기능 설정 중요: `DISPLAY` 또는 `MESSAGE`를 사용하는 경우 나머지 타겟 정보는 빈 값으로 요청	X
ageType	`Enum`	연령대 전체 선택 종류 `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`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가 중요: `adult`(성인 타게팅 여부)가 `true`인 경우 `20`, `25`, `30`, `35`, `40`, `45`, `50`, `55`, `60`, `65`, `70`을 배열에 담아 요청	X
genderType	`Enum`	성별 전체 선택 종류 `ALL`: 전체 `NOT_ALL`: 부분 선택	O
genders	`String[]`	성별 `M`: 남자 `F`: 여자 중요: `genderType`이 `NOT_ALL`인 경우 필수, `ALL`인 경우 요청 불가	X
ufoInterests	`UfoInterest[]`	맞춤타겟 > 카카오 데이터 > 카테고리 > 관심사 맞춤 타겟 카테고리 타입 보기 참고	X
ufoBusinessTypes	`UfoBusinessType[]`	맞춤타겟 > 카카오 데이터 > 카테고리 > 업종 맞춤타겟 카테고리 타입 조회 API 참고	X
locationType	`Enum`	지역선택 타입 `ALL`: 국내 전체 `AREA`: 지역 선택 중요: `locationType`을 지정하지 않은 경우 전체 지역(국내 + 해외)으로 설정됨	X
locations	`Location[]`	데모그래픽 > 행정구역 > 시/도 시/도 조회 참고 중요: `locationType`이 `ALL`(국내 전체)인 경우 시/도 전체 코드(`A`, `B`, ...)와 알 수 없음(`U`)을 모두 포함해 요청, 해외(`Z`)는 제외 참고: `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면)와 함께 요청 가능	X
depth2Locations	`Depth2Location[]`	데모그래픽 > 행정구역 > 시/군/구 시/군/구 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고 중요: `locationType`이 `AREA`인 경우 `locations`(시/도), `depth2Locations`(시/군/구), `depth3Locations`(동/읍/면) 중 하나 이상 요청 필수	X
customerFileTargetings	`CustomerFileTargeting[]`	맞춤타겟 > 내 데이터 > 고객파일 타게팅 가능한 고객파일 목록 조회 API로 조회 가능한 정보를 활용	X
trackerTargetings	`TrackerTargeting[]`	맞춤타겟 > 내 데이터 > 픽셀 & SDK 타게팅 가능한 픽셀 & SDK 이벤트 목록 보기 API로 조회 가능한 정보를 활용	X
cohortTargetings	`CohortTargeting[]`	맞춤타겟 > 내 데이터 > 광고반응타겟 타게팅 가능한 광고반응 타겟 목록 보기 API로 조회 가능한 정보를 활용	X
talkChannelTargetings	`TalkChannelTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오톡 채널 친구 타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용	X
syncAppTargetings	`SyncAppTargeting[]`	맞춤타겟 > 내 데이터 > 카카오 사용자 > 카카오 로그인 이용자 타게팅 가능한 카카오 채널 정보 보기 API로 조회 가능한 정보를 활용	X

응답

본문

이름	타입	설명
id	`Long`	광고그룹 번호
name	`String`	광고그룹 이름
config	`Enum: Config`	광고그룹 상태
pacing	`Enum: Pacing`	게재 종류
pricingType	`Enum: PricingType`	과금 방식 `CPA`: Cost per Action `CPM`: Cost per Mille `CPC`: Cost per Click `CPV`: Cost per View
bidAmount	`Integer`	광고그룹 입찰가
bidStrategy	`Enum`	입찰 방식 `MANUAL`: 수동 `AUTOBID`: 자동입찰 `OPTIMIZATION`: 목적 최적화
bidStrategyTarget	`BidStrategyTarget`	자동입찰 옵션
statusDescription	`String`	광고그룹 상태 설명
status	`Enum: Status[]`	광고그룹 상태
optimizationStatus	`Enum: OptimizationStatus[]`	최적화 상태 제공 조건: 최적화 상태값이 있는 경우
deviceTypes	`Enum: DeviceType[]`	디바이스
adServingCategories	`String[]`	게재 지면 네트워크의 하위
sectionCategories	`String[]`	섹션 카테고리 참고: 캠페인 유형이 카카오 비즈보드, 디스플레이, 동영상, 상품 카탈로그인 경우에만 제공
placements	`Enum: Placement[]`	게재 지면
targeting	`Targeting`	타게팅
schedule	`Schedule`	스케줄
campaign	`Campaign`	캠페인
useWifiOnly	`Boolean`	WIFI에서만 노출 여부
creativeCount	`Long`	하위에 등록된 소재 개수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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 ${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",
                        "description": "경기도 여주시",
                       "depth1Name": "경기도",
                       "depth2Name": "여주시"
                        },
                        {
                        "value": "I1009",
                        "description": "서울특별시 도봉구",
                        "depth1Name": "광주광역시",
                        "depth2Name": "도봉구"
                        }
                    ],
                "depth3Locations": [
                        {
                        "value": "A70052424",
                        "description": "강원도 삼척시 원덕읍",
                      "depth1Name": "강원도",
                      "depth2Name": "삼척시",
                     "depth3Name": "원덕읍"
                        },
                        {
                        "value": "E13010702",
                        "description": "광주광역시 남구 백운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",
        "description": "경기도 여주시",
        "depth1Name": "경기도",
        "depth2Name": "여주시"
      },
      {
        "value": "I1009",
        "description": "서울특별시 도봉구",
        "depth1Name": "광주광역시",
        "depth2Name": "도봉구"
      }
    ],
    "depth3Locations": [
      {
        "value": "A70052424",
        "description": "강원도 삼척시 원덕읍",
        "depth1Name": "강원도",
        "depth2Name": "삼척시",
        "depth3Name": "원덕읍"
      },
      {
        "value": "E13010702",
        "description": "광주광역시 남구 백운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`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

일 예산 설정 조건

일 예산은 최소 1만 원에서 최대 5억 원까지, 10원 단위로 설정 가능
캠페인 일 예산이 설정된 경우 광고그룹 일 예산은 캠페인 일 예산 이하로 설정

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_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 ${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	인증 방식
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups/bidAmount`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

입찰금액 설정 조건

디스플레이, 동영상, 비즈보드 유형 캠페인(도달 목표 제외) 하위 광고그룹만 가능
입찰금액 최소값은 광고그룹 유형, 광고 목적, 과금 방식에 따라 다름
입찰금액은 광고그룹 일 예산의 50% 또는 최대 10만 원을 초과할 수 없음

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

Type 최대 입찰금액(수동입찰)

디스플레이

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% 이하 중 작은 값

기본값

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% 이하 중 작은 값

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_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 ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
            "id": 1234,
            "bidAmount": 5000
        }'

Response: 성공

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

응답: 실패

// 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`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

디스플레이 광고그룹 게재 방식을 변경합니다.

게재 방식 변경 조건

디스플레이, 동영상, 비즈보드 유형 캠페인(도달 목표 제외) 하위 광고그룹만 변경 가능
입찰 방식이 수동(MANUAL)인 경우에만 설정 가능

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
id	`Long`	광고그룹 번호	O
pacing	`Enum: Pacing`	게재 방식 `NORMAL`: 일반 게재 `QUICK`: 빠른 게재 중요: 입찰 방식이 `MANUAL`인 경우만 설정 가능	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	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

요청 수 제한

이 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 ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
campaign	`Campaign`	캠페인	O
name	`String`	광고그룹 이름(최대: 50자) 생략 시 자동 생성	X
placements	`Enum: Placement[]`	게재 지면 `KAKAO_TALK`으로 고정	O
allAvailableDeviceType	`Boolean`	가능한 모든 디바이스 노출 중요: 캠페인 유형이 디스플레이 X 방문인 경우에만 `true` 요청 가능 중요: `true`인 경우 `deviceTypes`에 `ANDROID`, `IOS`, `PC` 모두 요청 필수	O
allAvailablePlacement	`Boolean`	가능한 모든 지면 노출 `false`로 고정	O
deviceTypes	`Enum: DeviceType[]`	디바이스 `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	`Enum: PricingType`	수동 입찰 방식 `CPMS`로 고정	O
bidAmount	`Integer`	수동 입찰금액(발송단가) 중요: `messageSendingInfo`(메시지 정보)의 `price`와 같은 값으로 요청	O
pacing	`Enum: Pacing`	게재 방식 `NONE`으로 고정	O
schedule	`Schedule`	스케줄 정보	O
smartMessage	`Boolean`	스마트 메시지 사용 여부 `true`: 사용 `false`: 사용하지 않음 참고: 스마트 메시지는 메시지 발송 중 실시간으로 수집한 데이터를 바탕으로 소재를 클릭한 친구와 유사한 친구를 찾아 메시지를 발송하고, 소재 최적화 기능으로 성과가 좋은 소재의 노출 기회를 높여 광고그룹의 효율을 향상시키는 기능 중요: 친구가 10만 이상인 채널에만 제공, 성능 최적화를 위해 친구의 최대 50%를 대상으로 발송 가능 중요: `true`인 경우 맞춤타겟의 타겟 정보 설정 불가, 소재는 최대 10개 등록 가능, 성능 최적화를 위해 최소 3만의 예상 발송 모수 필요	O

MessageSendingInfo

이름	타입	설명	필수
contractCount	`Integer`	구매발송수 중요: 예상 발송 모수보다 작게 요청 불가	O
longTerm	`Boolean`	전체발송 후 새 친구에게도 보내기 `true`: 보내기 `false`: 보내지 않기 중요: 실시간 타겟을 선택한 경우 `false`로 요청 중요: `true`인 경우 `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	`Enum: Config`	광고그룹 상태
smartMessage	`Boolean`	스마트 메시지 여부
pricingType	`Enum: PricingType`	과금 방식 `CPMS`: Cost per Message Send
bidAmount	`Integer`	입찰금액
bidStrategy	`String`	입찰 방식 `MANUAL`(수동)으로 고정
totalBudget	`Long`	구매 금액
totalBudgetWithVAT	`Long`	VAT 포함 기간 예산
status	`Enum: Status[]`	상태
placements	`Enum: Placement[]`	게재 지면
targeting	`Targeting`	타게팅
schedule	`Schedule`	스케줄
messageSendingInfo	`MessageSendingInfo`	메시지
profileId	`String`	카카오톡 채널 프로필 아이디
campaign	`Campaign`	캠페인
useWifiOnly	`Boolean`	WIFI에서만 노출 여부
creativeCount	`Long`	등록된 소재수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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 ${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	인증 방식
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

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

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
campaign	`Campaign`	캠페인	O
name	`String`	광고그룹 이름(최대: 50자) 생략 시 이전 이름 유지	X
placements	`Enum: Placement[]`	게재 지면 `KAKAO_TALK`으로 고정	O
adServingCategories	`String[]`	게재 지면 네트워크 하위 캠페인 유형이 카카오 비즈보드인 경우에는 요청 불가능 네트워크 게재지면 하위 목록 조회를 사용하여 응답 `JSON` 중에 `code`를 사용하여 요청 중요: `placements`에 `NETWORK`가 요청되었을 경우에 해당 필드는 필수로 요청	X
sectionCategories	`String[]`	섹션 카테고리 섹션 카테고리 목록 조회 API의 응답 `JSON` 중 `code`를 사용하여 요청 중요: 캠페인 유형이 카카오 비즈보드, 디스플레이, 동영상, 상품 카탈로그이고, `placements`에 `KAKAO_TALK` 요청되었을 경우 선택 가능, 그 외의 경우 요청 불가	X
allAvailableDeviceType	`Boolean`	가능한 모든 디바이스 노출 중요: 캠페인 유형이 디스플레이 X 방문인 경우에만 `true` 요청 가능 중요: `true`인 경우 `deviceTypes`에 `ANDROID`, `IOS`, `PC` 모두 요청 필수	O
allAvailablePlacement	`Boolean`	가능한 모든 지면 노출 `false`로 고정	O
deviceTypes	`Enum: DeviceType[]`	디바이스 `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	`Enum: PricingType`	수동 입찰 방식 `CPMS`로 고정	O
smartMessage	`Boolean`	스마트 메시지 사용 여부 `true`: 사용 `false`: 사용하지 않음 참고: 스마트 메시지는 메시지 발송 중 실시간으로 수집한 데이터를 바탕으로 소재를 클릭한 친구와 유사한 친구를 찾아 메시지를 발송하고, 소재 최적화 기능으로 성과가 좋은 소재의 노출 기회를 높여 광고그룹의 효율을 향상시키는 기능 중요: 친구가 10만 이상인 채널에만 제공, 성능 최적화를 위해 친구의 최대 50%를 대상으로 발송 가능 중요: `true`인 경우 맞춤타겟의 타겟 정보 설정 불가, 소재는 최대 10개 등록 가능, 성능 최적화를 위해 최소 3만의 예상 발송 모수 필요	O
bidAmount	`Integer`	수동 입찰금액(발송단가) 중요: `messageSendingInfo`(메시지 정보)의 `price`와 같은 값으로 요청	O
pacing	`Enum: Pacing`	게재 방식 `NONE`으로 고정	O
schedule	`Schedule`	스케줄 정보	O

응답

본문

이름	타입	설명
id	`Long`	광고그룹 번호
name	`String`	광고그룹명
config	`Enum: Config`	광고그룹 상태
smartMessage	`Boolean`	스마트 메시지 여부
pricingType	`Enum: PricingType`	과금 방식 `CPMS`: Cost per Message Send
bidAmount	`Integer`	입찰금액
bidStrategy	`String`	입찰 방식 `MANUAL`(수동)으로 고정
totalBudget	`Long`	구매 금액
totalBudgetWithVAT	`Long`	VAT 포함 기간 예산
status	`Enum: Status[]`	상태
placements	`Enum: Placement[]`	게재 지면
targeting	`Targeting`	타게팅
schedule	`Schedule`	스케줄
messageSendingInfo	`MessageSendingInfo`	메시지 정보
profileId	`String`	카카오톡 채널 프로필 아이디
campaign	`Campaign`	캠페인
useWifiOnly	`Boolean`	WIFI에서만 노출 여부
creativeCount	`Long`	등록된 소재수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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 ${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	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/targetings/populationScore`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
campaignTypeGoal	`CampaignTypeGoal`	캠페인 유형 X 목표	O
objective	`Objective`	광고 목표 대상 중요: 캠페인 유형 X 목표가 채널 X 도달인 경우 채널 필수	X
placements	`Enum: Placement[]`	게재 지면 `KAKAO_TALK`으로 고정	O
adServingCategories	`String[]`	게재 지면 네트워크 하위 캠페인 유형이 카카오 비즈보드인 경우에는 요청 불가능 네트워크 게재지면 하위 목록 조회를 사용하여 응답 `JSON` 중에 `code`를 사용하여 요청 중요: `placements`에 `NETWORK`가 요청되었을 경우에 해당 필드는 필수로 요청	X
allAvailableDeviceType	`Boolean`	가능한 모든 디바이스 노출 중요: 캠페인 유형이 디스플레이 X 방문인 경우에만 `true` 요청 가능 중요: `true`인 경우 `deviceTypes`에 `ANDROID`, `IOS`, `PC` 모두 요청 필수	O
allAvailablePlacement	`Boolean`	가능한 모든 지면 노출 `false`로 고정	O
deviceTypes	`Enum: DeviceType[]`	디바이스 `ANDROID`: 안드로이드 `IOS`: iOS 중요: 캠페인 유형이 디스플레이 X 방문이 아닌 경우 `ANDROID`, `IOS`만 요청 가능 중요: `allAvailableDeviceType`(가능한 모든 디바이스 노출)이 `true`인 경우 `ANDROID`, `IOS`, `PC` 모두 요청 필수	O
targeting	`Targeting`	타게팅	O
smartMessage	`Boolean`	스마트 메시지 사용 여부 `true`: 사용 `false`: 사용하지 않음 참고: 스마트 메시지는 메시지 발송 중 실시간으로 수집한 데이터를 바탕으로 소재를 클릭한 친구와 유사한 친구를 찾아 메시지를 발송하고, 소재 최적화 기능으로 성과가 좋은 소재의 노출 기회를 높여 광고그룹의 효율을 향상시키는 기능 중요: 친구가 10만 이상인 채널에만 제공, 성능 최적화를 위해 친구의 최대 50%를 대상으로 발송 가능 중요: `true`인 경우 맞춤타겟의 타겟 정보 설정 불가, 소재는 최대 10개 등록 가능, 성능 최적화를 위해 최소 3만의 예상 발송 모수 필요	O

응답

본문

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

예제

요청

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	인증 방식
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups/cancel/${ID}`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

카카오톡 채널 X 도달 캠페인 하위 광고그룹의 계약을 해지합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Long`	메시지 광고그룹 ID	O

예제

요청

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	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

요청 수 제한

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

집행 전략

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

집행 대상

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

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

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
campaign	`Campaign`	캠페인	O
name	`String`	광고그룹 이름(최대: 50자) 생략 시 자동 생성	X

응답

본문

이름	타입	설명
id	`Long`	광고그룹 번호
name	`String`	광고그룹명
config	`Enum: Config`	광고그룹 상태
pricingType	`Enum: PricingType`	과금 방식 `CPMS`: Cost per Message Send
status	`Enum: Status[]`	상태
placements	`Enum: Placement[]`	게재 지면
profileId	`String`	카카오톡 채널 프로필 아이디
campaign	`Campaign`	캠페인
creativeCount	`Long`	등록된 소재 수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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 ${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	인증 방식
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adGroups`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

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

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
campaign	`Campaign`	캠페인	O
id	`Long`	광고그룹 번호	O
name	`String`	광고그룹 이름(최대: 50자) 생략 시 이전 이름 유지	X

응답

본문

이름	타입	설명
id	`Long`	광고그룹 번호
name	`String`	광고그룹명
config	`Enum: Config`	광고그룹 상태
pricingType	`Enum: PricingType`	과금 방식 `CPMS`: Cost per Message Send
status	`Enum: Status[]`	상태
placements	`Enum: Placement[]`	게재 지면
profileId	`String`	카카오톡 채널 프로필 아이디
campaign	`Campaign`	캠페인
creativeCount	`Long`	등록된 소재 수
systemConfig	`Enum: SystemConfig`	광고그룹 시스템 상태 `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 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": 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`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

사용 조건

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

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

본문

이름	타입	설명	필수
id	`Long`	광고그룹 번호	O
config	`Enum: Config`	광고그룹 상태 `ON`: 활성화 `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	인증 방식
`DELETE`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고그룹을 삭제합니다.

삭제 시 주의 사항

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Long`	광고그룹 번호	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	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/latestSystemConfigHistory`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Long`	광고그룹 번호	O

응답

본문

이름	타입	설명
id	`Long`	시스템 정지 번호
systemConfig	`Enum: SystemConfig`	시스템 상태
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 ${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	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/${ID}/systemConfigHistories`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Long`	광고그룹 번호	O

응답

본문

이름	타입	설명
-	`SystemStopReason[]`	시스템 정지 사유 목록

SystemStopReason

이름	타입	설명
id	`Long`	시스템 정지 번호
systemConfig	`Enum: SystemConfig`	시스템 상태
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 ${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": "광고그룹이 존재하지 않습니다."
  }
}

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

광고그룹

광고그룹 목록 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

AdGroup

예제

요청

응답

광고그룹 조회

기본 정보

요청

헤더

경로 변수

응답

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

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

예제

요청

응답: 성공

응답: 실패

디스플레이 광고그룹 생성

기본 정보

집행전략 설정

입찰 방식

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

집행전략

그룹 일 예산

집행 기간

요청 수 제한

요청

헤더

본문

Campaign

Targeting

CustomerFileTargeting

TrackerTargeting

CohortTargeting

TalkChannelTargeting

SyncAppTargeting

TalkChannelGroupTargeting

응답

본문

예제

요청

응답

디스플레이 광고그룹 수정

기본 정보

요청 수 제한

요청

헤더

본문

Campaign

Targeting

응답

본문

예제

요청

응답

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

기본 정보

일 예산 설정 조건

요청 수 제한

요청

헤더

본문