카카오모먼트

광고 생성: 소재 공통

이 문서는 소재 공통 API 사용 방법을 안내합니다.

소재 목록 조회

기본 정보

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

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

소재 목록을 반환합니다.

요청

헤더

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

쿼리 파라미터

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

응답

본문

이름	타입	설명
content	`Creative[]`	소재 정보 목록

Creative

이름	타입	설명
id	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값
name	`String`	소재명
config	`Enum: Config`	소재 상태
systemConfig	`Enum: SystemConfig`	소재 시스템 상태 `ON`: 활성화 `ADMIN_STOP`: 관리자정지

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives?adGroupId=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"
    },
    {
      "id": 1112,
      "name": "소재 2",
      "config": "OFF"
    }
  ]
}

소재 조회

기본 정보

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

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

각 소재의 상세 정보를 반환합니다.

응답 참고

의견 및 증빙 파일은 심사 처리 연동으로 인해 조회가 지연될 수 있으며, 연동 완료 전에는 null로 조회
익스팬더블 요소 상세 정보는 지원하지 않음
사용하지 않는 값도 null로 응답될 수 있음

요청

헤더

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

경로 변수

이름	타입	설명	필수
ID	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값	O

응답

본문: 디스플레이 소재

이름	타입	설명
id	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값
creativeId	`Long`	소재 번호 최초로 소재가 생성된 경우: 심사 상태와 무관하게 원본 소재 번호와 동일함 최초 소재 생성 > 심사 승인 > 심사 과정이 필요한 소재를 수정한 경우: 신규 소재번호가 생성되어, 원본 소재 번호와 다른 값 가짐 최초 소재 생성 > 심사 승인 > 심사 과정이 필요 없는 소재를 수정한 경우: 신규 소재번호가 생성되지 않으며, 원본 소재 번호와 동일함
name	`String`	소재명
format	`Enum`	소재 유형 `IMAGE_BANNER`: 이미지 배너 `IMAGE_NATIVE`: 이미지 네이티브 `VIDEO_NATIVE`: 비디오 네이티브
pcLandingUrl	`String`	랜딩 URL (PC용 랜딩 URL)
mobileLandingUrl	`String`	랜딩 URL (모바일용 랜딩 URL)
rspvLandingUrl	`String`	랜딩 URL (반응형 랜딩 URL)
frequencyCapType	`Enum`	게재빈도 `AUTO`: 자동 설정 `DAY_IMP`: 상세 설정
frequencyCapTime	`Long`	게재빈도 시간
frequencyCap	`Long`	게재빈도 횟수
config	`Enum: Config`	소재 상태
systemConfig	`Enum: SystemConfig`	소재 시스템 상태 `ON`: 활성화 `ADMIN_STOP`: 관리자정지
reviewStatus	`Enum`	심사 상태 `APPROVED`: 승인 `WAITING`: 심사중 `REJECTED`: 심사보류 `MODIFICATION_WAITING`: 수정사항심사중 `MODIFICATION_REJECTED`: 수정사항심사보류
creativeStatus	`Enum`	소재의 운영 상태 `OPERATING`: 운영가능 `UNAPPROVED`: 심사미승인 `INVALID_DATE`: 기간오류 `MONITORING_REJECTED`: 모니터링 보류 `OFF`: 사용자OFF `DELETED`: 삭제 `ADGROUP_UNAVAILABLE`: 광고그룹 운영불가 `SYSTEM_CONFIG_ADMIN_STOP`: 관리자 정지
statusDescription	`String`	소재의 게재와 관련된 현재 상태
image	`Image`	IMAGE_BANNER, IMAGE_NATIVE, VIDEO_NATIVE 소재의 메인 이미지
landingInfo	`LandingInfo`	랜딩 정보
altText	`String`	IMAGE_BANNER 소재의 이미지 대체 설명문구
title	`String`	IMAGE_NATIVE, VIDEO_NATIVE 소재의 타이틀
description	`String`	IMAGE_NATIVE, VIDEO_NATIVE 소재의 홍보문구
actionButton	`String`	IMAGE_NATIVE, VIDEO_NATIVE 소재의 행동유도버튼
profileName	`String`	IMAGE_NATIVE, VIDEO_NATIVE 소재의 프로필 이름
profileImage	`Image`	업로드 된 프로필 이미지
video	`Video`	VIDEO_NATIVE 소재의 비디오
videoSkippableType	`Enum`	`VIDEO_INSTREAM` 소재의 비디오 노출 유형 `SECONDS_5`: 최대 5초까지 노출 `SECONDS_15`: 최대 15초까지 노출
rejectedReason	`RejectedReason[]`	소재 보류 사유
assetGroups	`AssetGroup[]`	슬라이드 아이템
hasExpandable	`Boolean`	익스팬더블 요소 포함 여부
opinion	`String`	심사 처리를 위한 참조 의견
opinionProof	`OpinionFile[]`	심사 처리를 위한 의견, 증빙자료 파일 목록
createdDate	`String`	소재 생성일시
lastModifiedDate	`String`	소재 마지막 수정일시
ageVerification	`Boolean`	연령인증 메시지 여부 `true`: 연령인증 메시지 `false`: 일반 메시지

본문: 메시지 소재

이름	타입	설명
id	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값
creativeId	`Long`	소재 번호 메시지 소재는 심사 상태가 존재하지 않으며, 항상 원본 소재 번호와 동일함
name	`String`	소재명
adGroupId	`Long`	광고그룹 번호
format	`Enum`	소재 유형 `BASIC_TEXT_MESSAGE`: 기본텍스트 `WIDE_MESSAGE`: 와이드이미지 `WIDE_LIST_MESSAGE`: 와이드리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀피드 `PREMIUM_VIDEO_MESSAGE`: 프리미엄동영상
config	`Enum: Config`	소재 상태
systemConfig	`Enum: SystemConfig`	소재 시스템 상태 `ON`: 활성화 `ADMIN_STOP`: 관리자정지
statusDescription	`Enum`	카카오톡채널 X 도달 하위 광고그룹의 현재 상태 `발송 대기` `발송중` `발송중지` `발송종료`
creativeStatus	`Enum`	소재의 운영 상태 `OPERATING`: 운영가능 `INVALID_DATE`: 기간오류 `OFF`: 사용자OFF `DELETED`: 삭제 `ADGROUP_UNAVAILABLE`: 광고그룹 운영불가
createdDate	`String`	소재 생성일시
lastModifiedDate	`String`	소재 마지막 수정일시
messageElement	`MessageElement`	메시지 상세 설명
ageVerification	`Boolean`	연령인증 메시지 여부 `true`: 연령인증 메시지 `false`: 일반 메시지

본문: 동영상 소재

이름	타입	설명
id	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값
creativeId	`Long`	소재 번호 최초로 소재가 생성된 경우: 심사 상태와 무관하게 원본 소재 번호와 동일함 최초 소재 생성 > 심사 승인 > 심사 과정이 필요한 소재를 수정한 경우: 신규 소재번호가 생성되어, 원본 소재 번호와 다른 값 가짐 최초 소재 생성 > 심사 승인 > 심사 과정이 필요 없는 소재를 수정한 경우: 신규 소재번호가 생성되지 않으며, 원본 소재 번호와 동일함
format	`String`	소재 유형 `VIDEO_NATIVE`로 고정
name	`String`	소재 이름
adGroupId	`Long`	광고그룹 번호
pcLandingUrl	`String`	랜딩 URL (PC용 URL)
mobileLandingUrl	`String`	랜딩 URL (모바일용 URL)
rspvLandingUrl	`String`	랜딩 URL (반응형 URL)
frequencyCapType	`Enum`	게재빈도 `AUTO`: 자동 설정 `DAY_IMP`: 상세 설정
frequencyCapTime	`Long`	게재빈도 시간
frequencyCap	`Long`	게재빈도 횟수
config	`Enum: Config`	소재 상태
systemConfig	`Enum: SystemConfig`	소재 시스템 상태 `ON`: 활성화 `ADMIN_STOP`: 관리자정지
reviewStatus	`Enum`	심사 상태 `APPROVED`: 승인 `WAITING`: 심사중 `REJECTED`: 심사보류 `MONITORING_REJECTED`: 모니터링 보류
creativeStatus	`Enum`	소재의 운영 상태 `OPERATING`: 운영가능 `UNAPPROVED`: 심사미승인 `INVALID_DATE`: 기간오류 `MONITORING_REJECTED`: 모니터링 보류 `OFF`: 사용자OFF `DELETED`: 삭제 `ADGROUP_UNAVAILABLE`: 광고그룹 운영불가
image	`Image`	업로드 된 홍보 이미지
title	`String`	타이틀
description	`String`	홍보문구
actionButton	`String`	행동유도버튼
profileName	`String`	프로필 이름
profileImage	`Image`	업로드 된 프로필 이미지
video	`Video`	업로드 된 홍보 비디오
statusDescription	`String`	소재의 게재와 관련된 현재 상태
rejectedReason	`RejectedReason[]`	소재 보류 사유, 빈 배열로 응답
createdDate	`String`	소재 생성일시
lastModifiedDate	`String`	소재 마지막 수정일시
opinionProof	`OpinionFile[]`	심사 처리를 위한 의견, 증빙자료 파일 목록
thumbnailImage	`Image`	업로드 된 맞춤 썸네일

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${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": 1111,
  "name": "디스플레이 광고 소재",
  "landingInfo": {
    "landingType": "AD_VIEW",
    "communicatorAdViewId": 1
  },
  "format": "IMAGE_BANNER",
  "landingUrl": "http://www.daum.net",
  "frequencyCapType": "DAY_IMP",
  "frequencyCap": 3,
  "frequencyCapTime": 24,
  "config": "ON",
  "image": {
    "url": "http://xxx.kakao.co.kr/sample.jpg",
    "fileName": "sample.jpeg",
    "width": 640,
    "height": 100,
    "size": 50000
  },
  "reviewStatus": "REJECTED",
  "creativeStatus": "UNAPPROVED",
  "statusDescription": "심사보류",
  "rejectedReason": [
    {
      "rejectedTitle": "공통1>가격 불일치",
      "rejectedContent": "등록하신 광고 소재 내 가격 정보가 랜딩페이지 내 실제 판매금액과 일치하지 않아 광고 등록이 보류되었습니다.\n* 광고 소재 내 가격 정보 : 39,800\n* 랜딩 페이지 내 가격 정보 : 49,800\n - 수정방법 : 모든 이용자가 구매 가능한 정확한 가격을 기재해 주시기 바랍니다."
    }
  ],
  "createdDate": "2020-01-01T00:00:00",
  "lastModifiedDate": "2020-01-01T01:00:00",
  "hasExpandable": false
}

응답: 실패

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 33003,
    "detailMsg": "소재가 존재하지 않습니다."
  }
}

소재 상태 변경

기본 정보

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

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

소재 상태를 변경합니다.

상태 변경 조건

디스플레이 광고 소재만 변경 가능
카카오톡 채널 유형 캠페인 하위 소재는 변경 불가

요청 수 제한

이 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/creatives/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 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 33003,
    "detailMsg": "소재가 존재하지 않습니다."
  }
}

소재 삭제

기본 정보

메서드	URL	인증 방식
`DELETE`	`https://apis.moment.kakao.com/openapi/v4/creatives/${ID}`	비즈니스 토큰

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

소재를 삭제합니다.

소재 삭제는 데이터 삭제를 의미하는 것이 아닌, 소재에 대한 운영을 포기한다는 의미입니다.

요청

헤더

이름	설명	필수
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/creatives/${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

응답: 요청 실패

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 75008,
    "detailMsg": "카카오톡 채널_도달 소재는 삭제할 수 없습니다.",
    "path": "/v2/moment/creatives",
    "timestamp": "2020-04-01T10:16:14.294+0000"
  }
}

시스템 정지 사유 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistory`	비즈니스 토큰

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

지정한 한 소재의 시스템 정지 사유를 반환합니다.

시스템 정지 사유가 여러 건 있는 경우 가장 최근의 관리자 정지 사유를 반환합니다. 소재의 systemConfig가 ADMIN_STOP일 경우에만 응답이 있습니다.

요청

헤더

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

경로 변수

이름	타입	설명	필수
ID	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값	O

응답

본문

이름	타입	설명
id	`Long`	시스템 정지 번호
systemConfig	`Enum: SystemConfig`	시스템 정지 상태 `ON`: 활성화 `ADMIN_STOP`: 관리자정지
reason	`String`	시스템 정지 사유
createdDate	`String`	시스템 정지 사유 생성일시 (`yyyy-MM-dd'T'HH:mm:ss` 형식)
lastModifiedDate	`String`	시스템 정지 사유 마지막 수정일시 (`yyyy-MM-dd'T'HH:mm:ss` 형식)

예제

요청

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

응답: 요청 성공

{
  "id": 1234,
  "systemConfig": "ADMIN_STOP",
  "reason": "해당 소재 랜딩 지원 종료로 관리자 정지되었습니다.",
  "createdDate": "2021-01-01T00:00:00",
  "lastModifiedDate": "2021-01-01T00:00:00"
}

응답: 요청 실패

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 33003,
    "detailMsg": "소재가 존재하지 않습니다."
  }
}

시스템 정지 사유 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistories`	비즈니스 토큰

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

지정한 한 소재의 최근 2년 동안의 시스템 정지 사유를 반환합니다.

소재의 systemConfig가 ADMIN_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`	시스템 정지 상태 `ON`: 활성화 `ADMIN_STOP`: 관리자정지
reason	`String`	시스템 정지 사유
createdDate	`String`	시스템 정지 사유 생성일시 (`yyyy-MM-dd'T'HH:mm:ss` 형식)
lastModifiedDate	`String`	시스템 정지 사유 마지막 수정일시 (`yyyy-MM-dd'T'HH:mm:ss` 형식)

예제

요청

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

응답: 요청 성공

[
  {
    "id": 1235,
    "systemConfig": "ADMIN_STOP",
    "reason": "해당 소재 랜딩 지원 종료로 관리자 정지되었습니다.",
    "createdDate": "2021-01-01T00:00:00",
    "lastModifiedDate": "2021-01-01T00:00:00"
  },
  {
    "id": 1234,
    "systemConfig": "ADMIN_STOP",
    "reason": "해당 소재 랜딩 지원 종료로 관리자 정지되었습니다.",
    "createdDate": "2021-01-01T00:00:00",
    "lastModifiedDate": "2021-01-01T00:00:00"
  }
]

응답: 요청 실패

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 33003,
    "detailMsg": "소재가 존재하지 않습니다."
  }
}

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

광고 생성: 소재 공통

소재 목록 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

Creative

예제

요청

응답

소재 조회

기본 정보

응답 참고

요청

헤더

경로 변수

응답

본문: 디스플레이 소재

본문: 메시지 소재

본문: 동영상 소재

예제

요청

응답

응답: 실패

소재 상태 변경

기본 정보

상태 변경 조건

요청 수 제한

요청

헤더

본문

예제

요청

응답: 성공

응답: 실패

소재 삭제

기본 정보

요청

헤더

경로 변수

예제

요청

응답: 요청 성공

응답: 요청 실패

시스템 정지 사유 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답: 요청 성공

응답: 요청 실패

시스템 정지 사유 목록 조회

기본 정보

요청

헤더

경로 변수

응답

본문

SystemStopReason

예제

요청

응답: 요청 성공

응답: 요청 실패

더 보기