카카오모먼트

광고 생성: 개인화 메시지 소재

이 문서는 개인화 메시지 소재 API 사용 방법을 안내합니다.

시작하기 전에

주의 사항

프리미엄동영상(PREMIUM_VIDEO_MESSAGE) 유형 및 쿠폰북 에셋 그룹(CouponBookAssetGroup)이 포함된 소재는 오픈API로 생성이 불가합니다.

메시지 집행 가이드와 맞지 않는 이미지와 문구는 사용할 수 없습니다.

공통 요소 가이드

홍보 이미지

항목	내용
포맷	JPG, JPEG, PNG
사이즈	800x400, 800x800, 800x600 픽셀 권장 단, 가로 80 픽셀 이하 사용 불가
용량	10MB 이하
비율	2:1, 1:1, 4:3 비율 권장 단, 가로:세로 1:2.5 이상 사용 불가

홍보 문구

변수 포함 최대 1,000자까지 작성 가능합니다. 단, 발송 요청 시 변수 치환 후에는 메시지 유형별, 영역별 가이드를 준수해야 발송이 됩니다.

버튼

변수 포함 최대 1,000자까지 작성 가능합니다. 단, 발송 요청 시 변수 치환 후에는 최대 8글자까지 작성되어야 발송이 됩니다.

구성 요소별 가이드

구성 요소별 필수 여부

항목	기본 텍스트	와이드 이미지	와이드 리스트
홍보 이미지	필수 아님	둘 중 하나 필수	리스트 1~3 중 하나 필수
홍보 문구	필수	필수	-
버튼 1	필수 아님	필수 아님	필수 아님
버튼 2	필수 아님	필수 아님	필수 아님
리스트 1 홍보 타이틀	-	-	필수 아님
리스트 2,3 홍보 타이틀	-	-	필수

* 와이드 리스트 유형의 4번째, 5번째 리스트는 선택 항목, 사용 시 홍보 이미지, 홍보 문구, 홍보 타이틀 모두 필수

구성 요소별 규격

항목	기본 텍스트	와이드 이미지	와이드 리스트
홍보 이미지	고정 URL 혹은 변수값 사용 가능	고정 URL 혹은 변수값 사용 가능	고정 URL 혹은 변수값 사용 가능
홍보 문구	변수값 변환 이후 이미지 미 첨부 시 최대 400자 이미지 첨부 시 최대 300자 링크 입력 불가, 개행은 29개까지 가능	변수값 변환 이후 최대 76자 입력 가능 링크 입력 불가, 개행은 1개까지 가능	-
버튼 1, 2	변수값 변환 이후 띄어쓰기 포함 최대 8자	변수값 변환 이후 띄어쓰기 포함 최대 8자	변수값 변환 이후 띄어쓰기 포함 최대 8자
리스트 타이틀	-	-	변수값 변환 이후 최대 20자 개행 불가
리스트 1 홍보 문구	-	-	변수값 변환 이후 최대 25자 개행 불가
리스트 2,3 홍보 문구	-	-	변수값 변환 이후 최대 30자 개행 불가

* 와이드 리스트 유형의 4번째, 5번째 리스트는 선택항목이며, 사용하기를 선택한다면 홍보 문구 정책은 리스트 2,3 홍보 문구와 동일

랜딩

항목	기본 텍스트	와이드 이미지	와이드 리스트
홍보 이미지	랜딩 불가	버튼 1에 설정한 랜딩 동일	버튼 1에 설정한 랜딩 동일
홍보 문구	랜딩 불가	랜딩 불가	-
버튼 1	URL, 소식, 쿠폰	URL, 소식, 쿠폰	URL, 소식, 쿠폰
버튼 2	URL, 소식, 쿠폰, 애드뷰, 비즈니스폼	URL, 소식, 쿠폰, 애드뷰, 비즈니스폼	URL, 소식, 쿠폰, 애드뷰, 비즈니스폼
리스트 타이틀	-	-	랜딩 불가
리스트 1,2,3 홍보 문구	-	-	각 항목에 설정된 홍보이미지와 동일

변수값 필드명

소재를 생성하거나 발송을 요청할 때 아래의 변수에 숫자를 붙여 사용합니다. 숫자를 붙이지 않은 경우 단일 변수라도 사용이 불가합니다. (예: ${brand_name1})

주의

정의되지 않은 변수 항목을 사용할 경우 소재 생성 및 발송이 불가합니다. 변수 항목에 부합하지 않는 데이터를 포함하여 메시지 발송 요청할 수 없으며, 관련 법률을 준수하지 않은 개인정보를 포함하거나 수신자에게 불편함을 줄 수 있는 변수가 포함된 개인화 메시지를 발송할 경우 광고계정 및 기타 운영 제재가 발생할 수 있습니다.

항목	데이터	필드명	패턴
1	날짜	`date`	`${date1}` ~ `${date4}`
2	사이트명	`site_name`	`${site_name1}`
3	브랜드명	`brand_name`	`${brand_name1}`
4	고객 이름	`user_name`	`${user_name1}`
5	고객 ID	`user_id`	`${user_id1}`
6	고객 등급	`user_rating`	`${user_rating1}`
7	적립금	`available_point`	`${available_point1}`
8	쿠폰 개수	`available_coupon`	`${available_coupon1}`
9	상품 ID	`product_id`	`${product_id1}` ~ `${product_id7}`
10	상품명	`product_name`	`${product_name1}` ~ `${product_name7}`
11	상품 가격 - 정가	`price`	`${price1}` ~ `${price7}`
12	상품 가격 - 세일가	`sale_price`	`${sale_price1}` ~ `${sale_price7}`
13	할인금액	`discount_amount`	`${discount_amount1}` ~ `${discount_amount7}`
14	할인율	`discount_percent`	`${discount_percent1}` ~ `${discount_percent7}`
15	홍보 이미지	`image_url`	`${image_url1}` ~ `${image_url7}`
17	모바일 URL	`mobile_url`	`${mobile_url1}` ~ `${mobile_url13}`
18	PC URL	`pc_url`	`${pc_url1}` ~ `${pc_url13}`

변수값 입력 가능 요소

항목	데이터	유형	단일/복수	사용 가능 개수	길이	자료형
1	날짜	텍스트	복수	4	20	문자
2	사이트명	텍스트	단일	1	30	문자
3	브랜드명	텍스트	단일	1	30	문자
4	고객 이름	텍스트	단일	1	20	문자
5	고객 ID	텍스트	단일	1	20	문자
6	고객 등급	텍스트	단일	1	20	문자
7	적립금	텍스트	단일	1	10	숫자
8	쿠폰 개수	텍스트	단일	1	10	숫자
9	상품 ID	텍스트	복수	7	50	문자
10	상품명	텍스트	복수	7	25	문자
11	상품 가격 - 정가	가격	복수	7	8	숫자
12	상품 가격 - 세일가	가격	복수	7	8	숫자
13	할인금액	가격	복수	7	8	숫자
14	할인율	텍스트	복수	7	2	숫자
15	홍보 이미지¹⁾	이미지	복수	7	1000	문자
17	모바일 URL	랜딩	복수	13	1000	문자
18	PC URL	랜딩	복수	13	1000	문자

¹⁾ 개인화 메시지 이미지 업로드 API의 응답으로 받은 URL만 허용

소재 유형별 사용 가능 변수값

소재 유형별, 요소별 소재 생성에 사용 가능한 변수값은 아래와 같습니다. 발송 요청 시 치환될 결과 값은 개행 입력이 불가능합니다.

기본 텍스트형

항목	사용 가능 변수값
홍보 이미지	변수 이미지 등록 가능 고정 이미지 또는 변수 이미지 중 1개만 등록 가능
홍보 문구	텍스트/가격 유형의 변수 입력 가능
버튼 1~2	랜딩 유형: URL에 한하여 변수값 지원 모바일 URL(`mobile_url1`) PC URL(`pc_url1`) 버튼명은 텍스트/가격 유형의 변수 입력 가능

와이드 이미지형

항목	사용 가능 변수값
홍보 이미지	변수 이미지 등록 가능 고정 이미지 또는 변수 이미지 중 1개만 등록 가능
랜딩	이미지 등록 시에만 랜딩 등록 기능 지원 랜딩 유형: URL에 한하여 변수값 지원 모바일 URL(`mobile_url1`) PC URL(`pc_url1`)
홍보 문구	텍스트/가격 유형의 변수 입력 가능
버튼 1~2	랜딩 유형: URL에 한하여 변수값 지원 모바일 URL(`mobile_url1`) PC URL(`pc_url1`) 버튼명은 텍스트/가격 유형의 변수 입력 가능

와이드 리스트형

항목	사용 가능 변수값
타이틀	텍스트/가격 유형의 변수 입력 가능
각 리스트 홍보 이미지	변수 이미지 등록 가능 고정 이미지 또는 변수 이미지 중 1개만 등록 가능
랜딩	랜딩 유형: URL에 한하여 변수값 지원 모바일 URL(`mobile_url1`) PC URL(`pc_url1`)
홍보 문구	텍스트/가격 유형의 변수 입력 가능
버튼 1~2	랜딩 유형: URL에 한하여 변수값 지원 모바일 URL(`mobile_url1`) PC URL(`pc_url1`) 버튼명은 텍스트/가격 유형의 변수 입력 가능

개인화 메시지 소재 템플릿 생성

기본 정보

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

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

개인화 메시지 X 도달 캠페인 하위의 소재 템플릿을 생성합니다.

요청 수 제한

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

요청

헤더

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

본문

이름	타입	설명	필수
adGroupId	`Long`	광고그룹 번호	O
format	`Enum`	소재 유형 `BASIC_TEXT_MESSAGE`: 기본텍스트 `WIDE_MESSAGE`: 와이드이미지 `WIDE_LIST_MESSAGE`: 와이드리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드	O
name	`String`	소재 이름(최대: 50자) 생략 시 `{캠페인 유형}_{캠페인 목표}_{현재시간}` 형식으로 자동 생성	X
messageElement	`MessageElement`	생성할 메시지 내용 `MULTIPART/FORM-DATA`로 `messageElement.{}` 형식으로 요청	O

MessageElement

이름	타입	설명	필수
creativeFormat	`Enum`	메시지 소재 유형 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드 중요: `format`과 같은 값으로 요청	O
profileId	`String`	카카오톡 채널 프로필 ID 참고: 카카오톡 채널 프로필 ID 확인 방법	O
title	`String`	홍보문구 또는 타이틀 소재 유형에 따라 노출 위치 상이 `BASIC_TEXT_MESSAGE`: 기본텍스트의 홍보 문구(최대: 400자, 이미지 첨부 시 300자) `WIDE_MESSAGE`: 와이드 이미지의 홍보 문구(최대: 76자) `WIDE_LIST_MESSAGE`: 와이드 리스트의 타이틀(최대: 20자) `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스 인트로 카드의 홍보 타이틀(최대: 20자) 참고: 변수를 활용하는 경우 최대 1,000자까지 입력 가능, 발송 시 치환된 글자 수는 위 가이드를 준수해야 발송 가능	X
description	`String`	캐러셀 커머스형 인트로 카드 홍보문구(최대: 50자) 참고: 변수를 활용하는 경우 최대 1,000자까지 입력 가능, 발송 시 치환된 글자 수는 위 가이드를 준수해야 발송 가능	X
buttonAssetGroups	`ButtonAssetGroup[]`	버튼 항목들 최대 2개의 버튼 에셋 그룹을 요청할 수 있으며 기본 텍스트, 와이드 이미지, 와이드 리스트 유형은 버튼 미설정 가능 캐러셀 커머스, 캐러셀 피드는 버튼 1 필수 버튼 1일 경우 랜딩은 URL, 소식, 쿠폰만 설정 가능하며 버튼 2의 경우 애드뷰, 비즈니스폼까지 설정 가능 단, 캐러셀 유형의 경우 랜딩은 URL 랜딩만 활용 가능	X
itemAssetGroups	`ItemAssetGroup[]`	리스트 항목	O
shareFlag	`Boolean`	공유하기 사용 여부 `false`(공유 비허용)로 고정	O
adFlag	`Boolean`	광고성 메시지 `true`: 설정 `false`: 미설정	O
imageFile	`Multipart File`	업로드할 이미지 파일 (개인화메시지에서 고정 이미지 사용하는 경우 사용 가능) 메시지 유형이 기본 텍스트(BASIC_TEXT_MESSAGE)이거나 CAROUSEL_COMMERCE_MESSAGE(캐러셀커머스) 유형 인트로 카드일 경우에만 요청 가능 그 외 유형은 `itemAssetGroup`로 요청 가능	X
image	`Image`	개인화 메시지 사용 이미지 변수 (개인화 메시지에서 가변 이미지 변수 사용하는 경우 요청) 메시지 유형이 기본 텍스트 (BASIC_TEXT_MESSAGE) 일 경우에만 요청 가능 그 외 유형은 `ItemAssetGroup`로 요청 가능	X
csInfo	`String`	고객센터 전화번호	O
hasIntro	`Boolean`	캐러셀 커머스 인트로 카드 유무	X
introLandingType	`String`	캐러셀 커머스 인트로 카드 랜딩 타입	X
introMobileLandingUrl	`String`	캐러셀 커머스 인트로 카드 모바일 랜딩 URL	X
introPcLandingUrl	`String`	캐러셀 커머스 인트로 카드 pc 랜딩 URL	X

ButtonAssetGroup

이름	타입	설명	필수
ordering	`Integer`	버튼 순서 0,1 전달가능	O
pcLandingUrl	`String`	PC 랜딩 URL 랜딩 유형이 LANDING_URL 인 경우 요청 가능하며 PC 랜딩 URL은 PC 카카오톡에서 버튼 클릭 시 별도의 URL로 랜딩 시키려는 경우 사용 `http://` 또는 `https://` 형식의 정상적인 랜딩 URL을 입력	X
mobileLandingUrl	`String`	모바일 랜딩 URL `http://` 또는 `https://` 형식의 정상적인 랜딩 URL을 입력	X
title	`String`	버튼명(최대: 8자) 비즈니스폼의 경우 아래에 정의된 버튼명으로만 요청 가능 "톡에서 설문하기" "톡에서 시승신청" "톡에서 예약하기" "톡에서 응모하기" "톡에서 참여하기" 캐러셀커머스 유형의 경우 버튼 1번은 "구매하기"만 요청 가능 참고: 변수를 활용하는 경우 최대 1,000자까지 입력 가능, 발송 시 치환된 글자 수는 위 가이드를 준수해야 발송 가능	O
landingType	`Enum`	랜딩 유형 `LANDING_URL`: URL 랜딩 `CHANNEL_COUPON`: 쿠폰 랜딩 `CHANNEL_POST`: 소식 랜딩 `BIZ_FORM`: 비즈니스폼 랜딩 `AD_VIEW`: 애드뷰 랜딩 중요: 캐러셀 유형은 `LANDING_URL`(URL 랜딩)만 사용 가능	O
channelCouponId	`Long`	쿠폰 ID 랜딩 유형이 쿠폰 랜딩 (CHANNEL_COUPON) 인 경우 요청 가능 메시지 버튼 쿠폰 목록 조회 API 로 조회되는 쿠폰 ID	X
channelPostId	`Long`	소식 ID 랜딩 유형이 소식 랜딩 (CHANNEL_POST) 인 경우 요청 가능 메시지 버튼 소식 목록 조회 API로 조회되는 소식 ID	X
bizFormId	`Long`	비즈니스폼 ID 랜딩 유형이 비즈니스폼 랜딩 (BIZ_FORM) 인 경우 요청 가능 메시지 버튼 비즈니스폼 목록 조회 API로 조회되는 비즈니스폼 ID	X
adViewId	`Long`	애드뷰 ID 랜딩 유형이 애드뷰 랜딩 (AD_VIEW) 인 경우 요청 가능 메시지 버튼 애드뷰 목록 조회 API로 조회되는 애드뷰 ID	X

ItemAssetGroup

이름	타입	설명	필수
landingType	`Enum`	랜딩 유형 `LANDING_URL`: URL 랜딩 `CHANNEL_COUPON`: 쿠폰 랜딩 `CHANNEL_POST`: 소식 랜딩 중요: 캐러셀 유형은 `LANDING_URL`(URL 랜딩)만 사용 가능	O
title	`String`	홍보문구 소재 유형에 따라 노출 위치 상이 `WIDE_LIST_MESSAGE`: 와이드리스트의 타이틀(1번째 최대: 25자, 2~5번째 최대: 30자), 1번, 4번, 5번 리스트는 필수 아님 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스의 타이틀(최대: 25자) `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드의 타이틀(최대: 20자) 참고: 변수를 활용하는 경우 최대 1,000자까지 입력 가능, 발송 시 치환된 글자 수는 위 가이드를 준수해야 발송 가능	O
description	`String`	캐러셀 피드형 홍보문구(최대: 180자) 참고: 변수를 활용하는 경우 최대 1,000자까지 입력 가능, 발송 시 치환된 글자 수는 위 가이드를 준수해야 발송 가능	O
priceAmount	`String`	캐러셀 커머스형 캐러셀 내 가격 정보(최소: 0, 최대: 99999999), 정수만 입력 가능 중요: `CAROUSEL_COMMERCE_MESSAGE`인 경우 필수 참고: 변수를 활용하는 경우 최대 1,000자까지 입력 가능, 발송 시 치환된 글자 수는 위 가이드를 준수해야 발송 가능	X
priceCurrencyCode	`Enum: CurrencyCode`	통화 정보 중요: `CAROUSEL_COMMERCE_MESSAGE`인 경우 필수	X
discountedPriceAmount	`String`	할인 가격 정보 캐러셀 커머스형 캐러셀 내 가격 정보(최소: 0, 최대: 99999999), 정수만 입력 가능 가격 정보 대비 입력 값이 1% 이상 차이가 나야 입력 가능 참고: 변수를 활용하는 경우 최대 1,000자까지 입력 가능, 발송 시 치환된 글자 수는 위 가이드를 준수해야 발송 가능	X
mobileLandingUrl	`String`	모바일 랜딩URL `http://` 또는 `https://` 형식의 정상적인 랜딩 URL을 입력 캐러셀 커머스, 캐러셀 피드는 버튼 1과 동일한 랜딩만 설정 가능	X
pcLandingUrl	`String`	PC 랜딩 URL 랜딩 유형이 LANDING_URL 인 경우 요청 가능하며 PC 랜딩 URL은 PC 카카오톡에서 버튼 클릭 시 별도의 URL로 랜딩 시키려는 경우 사용 `http://` 또는 `https://` 형식의 정상적인 랜딩 URL을 입력	X
channelPostId	`Long`	소식 ID 랜딩 유형이 소식 랜딩 (CHANNEL_POST) 인 경우 요청 가능 메시지 버튼 소식 목록 조회 API로 조회되는 소식 ID	X
channelCouponId	`Long`	쿠폰 ID 랜딩 유형이 쿠폰 랜딩 (CHANNEL_COUPON) 인 경우 요청 가능 메시지 버튼 쿠폰 목록 조회 API 로 조회되는 쿠폰 ID	X
imageFile	`Multipart File`	업로드할 이미지 파일 아래 유형에 사용 가능 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스(인트로 제외 카드) `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드	X
image	`Image`	개인화 메시지에 사용할 이미지 변수 (개인화 메시지에서 가변 이미지 변수 사용하는 경우 요청) 아래 유형에 사용 가능 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스(인트로 제외 카드) `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드	X

ImageFile

이름	타입	설명	필수
imageFile	`Multipart File`	업로드할 이미지 파일	O

Image

이름	타입	설명	필수
valueWithVariable	`String`	변수 입력 정보 (예: `${image_url1}`)	O

응답

본문

이름	타입	설명
id	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값
creativeId	`Long`	소재 번호 메시지 소재는 심사 상태가 존재하지 않으며, 항상 원본 소재 번호와 동일함
name	`String`	소재명
adGroupId	`Long`	광고 그룹 아이디
format	`Enum`	소재 유형 `BASIC_TEXT_MESSAGE`: 기본텍스트 `WIDE_MESSAGE`: 와이드이미지 `WIDE_LIST_MESSAGE`: 와이드리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드
config	`Enum: Config`	소재 상태
creativeStatus	`Enum`	소재의 운영 상태 `OPERATING`: 운영가능 `INVALID_DATE`: 기간오류 `OFF`: 사용자OFF `DELETED`: 삭제 `ADGROUP_UNAVAILABLE`: 광고그룹 운영불가
creativeDate	`String`	소재 생성일시
lastModifiedDate	`String`	소재 마지막 수정일시
messageElement	`MessageElement`	메시지 상세 설명

MessageElement

이름	타입	설명
id	`Long`	메시지 소재 ID
adAccountId	`Long`	광고계정 ID
profileId	`String`	카카오톡 채널 프로필 ID 참고: 카카오톡 채널 프로필 ID 확인 방법
profileName	`String`	카카오톡 채널 프로필명
name	`String`	메시지 소재명
shareFlag	`Boolean`	공유하기
adFlag	`Boolean`	광고성 메시지
creativeFormat	`Enum`	메시지 소재 유형 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드
title	`String`	홍보문구 또는 타이틀 소재 유형별 노출 위치가 상이함 `BASIC_TEXT_MESSAGE`: 기본텍스트의 홍보 문구 `WIDE_MESSAGE`: 와이드이미지의 홍보 문구 `WIDE_LIST_MESSAGE`: 와이드리스트의 타이틀 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 인트로 카드의 홍보타이틀
description	`String`	캐러셀 커머스형 인트로 카드 홍보문구
image	`Image`	이미지 소재 기본 텍스트 (BASIC_TEXT_MESSAGE) 유형에만 응답됨
buttonAssetGroups	`ButtonAssetGroup`	버튼 항목
itemAssetGroups	`ItemAssetGroup`	리스트 항목 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드
thumbnailUrl	`String`	썸네일 이미지 URL
csInfo	`String`	고객센터 전화번호
createdDate	`String`	메시지 소재 생성일 `yyyy-MM-dd'T'HH:mm:ss` 형식
lastModifiedDate	`String`	메시지 소재 마지막 수정일 `yyyy-MM-dd'T'HH:mm:ss` 형식
hasIntro	`Boolean`	캐러셀 커머스 인트로 카드 유무
introLandingType	`String`	캐러셀 커머스 인트로 카드 랜딩 타입
introMobileLandingUrl	`String`	캐러셀 커머스 인트로 카드 모바일 랜딩 URL
introPcLandingUrl	`String`	캐러셀 커머스 인트로 카드 pc 랜딩 URL

Image

이름	타입	설명
size	`Long`	파일 사이즈
url	`String`	이미지 URL
fileName	`String`	이미지 파일명
width	`Integer`	넓이
height	`Integer`	높이
mimeType	`String`	Mime 유형
valueWithVariable	`String`	변수 입력 정보 (예: `${image_url1}`)

ButtonAssetGroup

이름	타입	설명
ordering	`Long`	정렬순번
title	`String`	버튼명
rspvLandingUrl	`String`	반응형 랜딩 URL
mobileLandingUrl	`String`	모바일 랜딩 URL
pcLandingUrl	`String`	PC 랜딩 URL
adViewId	`Long`	애드뷰 ID
bizFormId	`Long`	비즈니스폼 ID
channelPostId	`Long`	채널 소식 ID
channelCouponId	`Long`	채널 쿠폰 ID
thumbnail	`String`	썸네일
highlighted	`Boolean`	하이라이트 버튼 사용
landingType	`Enum`	랜딩 유형 `LANDING_URL`: URL `CHANNEL_COUPON`: 쿠폰 `CHANNEL_POST`: 소식 `AD_VIEW`: 애드뷰 `BIZ_FORM`: 비즈니스폼

ItemAssetGroup

이름	타입	설명
thumbnail	`String`	썸네일 URL
landingType	`Enum`	랜딩 유형 `LANDING_URL`: URL `CHANNEL_COUPON`: 쿠폰 `CHANNEL_POST`: 소식
ordering	`Integer`	정렬 순번
title	`String`	홍보문구 아이템 에셋 그룹 내 홍보문구는 와이드 이미지, 와이드 리스트, 캐러셀 피드형, 캐러셀 커머스 유형에만 응답
description	`String`	캐러셀 피드형 홍보문구
priceAmount	`Integer`	가격 정보 캐러셀 커머스형 캐러셀 내 가격 정보, 달러와 유로의 경우 소수점 2자리까지 요청 가능
priceCurrencyCode	`Enum: CurrencyCode`	통화 정보
discountedPriceAmount	`Integer`	할인 가격 정보 캐러셀 커머스형 캐러셀 내 가격 정보
mobileLandingUrl	`String`	모바일 랜딩 URL 랜딩 유형이 `LANDING_URL` (URL) 일 경우 응답
pcLandingUrl	`String`	PC 랜딩 URL 랜딩 유형이 `LANDING_URL` (URL) 일 경우 응답
image	`Image`	이미지 소재 아이템 에셋 그룹 내 Image는 와이드 이미지, 와이드 리스트, 캐러셀 커머스, 캐러셀 피드 유형에 응답
thumbnail	`Thumbnail`	대표 이미지

Thumbnail

이름	타입	설명
fileSize	`Long`	파일 사이즈
url	`String`	대표 썸네일 이미지 URL
fileName	`String`	대표 썸네일 파일명
imageWidth	`Integer`	넓이
imageHeight	`Integer`	높이
mimeType	`String`	Mime 유형

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
    -F "messageElement.creativeFormat=BASIC_TEXT_MESSAGE" \
    -F "messageElement.profileId=_Xxo" \
    -F "messageElement.title=홍보문구" \
    -F "messageElement.buttonAssetGroups[0].ordering=0" \
    -F "messageElement.buttonAssetGroups[0].landingType=LANDING_URL" \
    -F "messageElement.buttonAssetGroups[0].title=버튼1" \
    -F "messageElement.buttonAssetGroups[0].pcLandingUrl=${pc_url1}" \
    -F "messageElement.buttonAssetGroups[0].mobileLandingUrl=${mobile_url1}" \
    -F "messageElement.buttonAssetGroups[1].ordering=1" \
    -F "messageElement.buttonAssetGroups[1].landingType=BIZ_FORM" \
    -F "messageElement.buttonAssetGroups[1].bizFormId=1" \
    -F "messageElement.buttonAssetGroups[1].title=톡에서 시승신청" \
    -F "messageElement.name=기본텍스트" \
    -F "messageElement.shareFlag=true" \
    -F "messageElement.adFlag=true" \
    -F "messageElement.csInfo=02-1234-5678" \
    -F "messageElement.image.valueWithVariable=${image_url1}" \
    -F "adGroupId=12345" \
    -F "format=BASIC_TEXT_MESSAGE"

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 12345,
  "creativeId": 12345,
  "name": "카카오톡 채널_도달_20210625",
  "adGroupId": 11223,
  "format": "BASIC_TEXT_MESSAGE",
  "config": "ON",
  "statusDescription": "발송 대기",
  "creativeStatus": "OPERATING",
  "createdDate": "2021-06-25T17:04:02.883575",
  "lastModifiedDate": "2021-06-25T17:04:06.291245",
  "messageElement": {
    "id": 12345,
    "adAccountId": 123,
    "profileId": "_xbHxd",
    "name": "카카오톡 채널_도달_20210625",
    "creativeFormat": "BASIC_TEXT_MESSAGE",
    "title": "홍보문구입니다.",
    "image": {
      "valueWithVariable": "${image_url1}"
    },
    "shareFlag": true,
    "adFlag": true,
    "thumbnail": {
      "fileSize": 168816,
      "url": "//beta.daumcdn.net/b2/creative/759/d7961bd0662a240f43f047d3116a25f3.jpg",
      "fileName": "풀뷰 1280x720.jpg",
      "imageWidth": 1280,
      "imageHeight": 720,
      "mimeType": "image/jpeg",
      "imageHash": "35156f0c1393434ced4be21423d08a6a"
    },
    "buttonAssetGroups": [
      {
        "ordering": 0,
        "title": "버튼1",
        "pcLandingUrl": "http://www.daum.net",
        "mobileLandingUrl": "http://www.google.com",
        "landingType": "LANDING_URL"
      }
    ],
    "thumbnailUrl": "//beta.daumcdn.net/b2/creative/759/d7961bd0662a240f43f047d3116a25f3.jpg",
    "messageThumbnail": {
      "fileSize": 168816,
      "url": "//beta.daumcdn.net/b2/creative/759/d7961bd0662a240f43f047d3116a25f3.jpg",
      "fileName": "풀뷰 1280x720.jpg",
      "imageWidth": 1280,
      "imageHeight": 720,
      "mimeType": "image/jpeg",
      "imageHash": "35156f0c1393434ced4be21423d08a6a"
    },
    "createdDate": "2021-06-25T17:04:02.883575",
    "lastModifiedDate": "2021-06-25T17:04:06.291245"
  }
}

개인화 메시지 소재 템플릿 수정

기본 정보

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

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

개인화 메시지 X 도달 캠페인 하위의 소재 템플릿을 수정합니다.

사용 조건

쿠폰북 에셋 그룹(CouponBookAssetGroup)이 포함된 소재는 오픈API로 수정 불가
발송 요청 중이던 메시지가 있는 경우 요청 및 발송 상태가 모두 중지됨

요청 수 제한

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

요청

헤더

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

본문

이름	타입	설명	필수
adGroupId	`Long`	광고그룹 번호	O
format	`Enum`	소재 유형 `BASIC_TEXT_MESSAGE`: 기본텍스트 `WIDE_MESSAGE`: 와이드이미지 `WIDE_LIST_MESSAGE`: 와이드리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드	O
name	`String`	소재 이름(최대: 50자) 생략 시 `{캠페인 유형}_{캠페인 목표}_{현재시간}` 형식으로 자동 생성	X
messageElement	`MessageElement`	생성할 메시지 내용 `MULTIPART/FORM-DATA`로 `messageElement.{}` 형식으로 요청	O

응답

본문

이름	타입	설명
id	`Long`	원본 소재 번호 실제 집행 시 활용되는 소재 식별 값
creativeId	`Long`	소재 번호 메시지 소재는 심사 상태가 존재하지 않으며, 항상 원본 소재 번호와 동일함
name	`String`	소재명
adGroupId	`Long`	광고 그룹 아이디
format	`Enum`	소재 유형 `BASIC_TEXT_MESSAGE`: 기본텍스트 `WIDE_MESSAGE`: 와이드이미지 `WIDE_LIST_MESSAGE`: 와이드리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드
config	`Enum: Config`	소재 상태
creativeStatus	`Enum`	소재의 운영 상태 `OPERATING`: 운영가능 `INVALID_DATE`: 기간오류 `OFF`: 사용자OFF `DELETED`: 삭제 `ADGROUP_UNAVAILABLE`: 광고그룹 운영불가
creativeDate	`String`	소재 생성일시
lastModifiedDate	`String`	소재 마지막 수정일시
messageElement	`MessageElement`	메시지 상세 설명

예제

요청

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
    -F "messageElement.creativeFormat=BASIC_TEXT_MESSAGE" \
    -F "messageElement.profileId=_Xxo" \
    -F "messageElement.title=홍보문구" \
    -F "messageElement.buttonAssetGroups[0].ordering=0" \
    -F "messageElement.buttonAssetGroups[0].landingType=LANDING_URL" \
    -F "messageElement.buttonAssetGroups[0].title=버튼1" \
    -F "messageElement.buttonAssetGroups[0].pcLandingUrl=http://www.daum.net" \
    -F "messageElement.buttonAssetGroups[0].mobileLandingUrl=http://www.kakaocorp.com" \
    -F "messageElement.buttonAssetGroups[1].ordering=1" \
    -F "messageElement.buttonAssetGroups[1].landingType=BIZ_FORM" \
    -F "messageElement.buttonAssetGroups[1].bizFormId=1" \
    -F "messageElement.buttonAssetGroups[1].title=톡에서 시승신청" \
    -F "messageElement.name=기본텍스트" \
    -F "messageElement.shareFlag=true" \
    -F "messageElement.adFlag=true" \
    -F "messageElement.csInfo=02-1234-5678" \
    -F "messageElement.imageFile=@/directory/banner.png" \
    -F "adGroupId=39688" \
    -F "format=BASIC_TEXT_MESSAGE"

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": 12345,
  "creativeId": 12345,
  "name": "카카오톡 채널_도달_20210625",
  "adGroupId": 11223,
  "format": "BASIC_TEXT_MESSAGE",
  "config": "ON",
  "statusDescription": "발송 대기",
  "creativeStatus": "OPERATING",
  "createdDate": "2021-06-25T17:04:02.883575",
  "lastModifiedDate": "2021-06-25T17:04:06.291245",
  "messageElement": {
    "id": 12345,
    "adAccountId": 123,
    "profileId": "_xbHxd",
    "name": "카카오톡 채널_도달_20210625",
    "creativeFormat": "BASIC_TEXT_MESSAGE",
    "title": "홍보문구입니다.",
    "image": {
      "fileSize": 168816,
      "url": "//beta.daumcdn.net/b2/creative/759/d7961bd0662a240f43f047d3116a25f3.jpg",
      "fileName": "풀뷰 1280x720.jpg",
      "imageWidth": 1280,
      "imageHeight": 720,
      "mimeType": "image/jpeg",
      "imageHash": "35156f0c1393434ced4be21423d08a6a"
    },
    "shareFlag": true,
    "adFlag": true,
    "thumbnail": {
      "fileSize": 168816,
      "url": "//beta.daumcdn.net/b2/creative/759/d7961bd0662a240f43f047d3116a25f3.jpg",
      "fileName": "풀뷰 1280x720.jpg",
      "imageWidth": 1280,
      "imageHeight": 720,
      "mimeType": "image/jpeg",
      "imageHash": "35156f0c1393434ced4be21423d08a6a"
    },
    "buttonAssetGroups": [
      {
        "ordering": 0,
        "title": "버튼1",
        "pcLandingUrl": "http://www.daum.net",
        "mobileLandingUrl": "http://www.google.com",
        "landingType": "LANDING_URL"
      }
    ],
    "thumbnailUrl": "//beta.daumcdn.net/b2/creative/759/d7961bd0662a240f43f047d3116a25f3.jpg",
    "messageThumbnail": {
      "fileSize": 168816,
      "url": "//beta.daumcdn.net/b2/creative/759/d7961bd0662a240f43f047d3116a25f3.jpg",
      "fileName": "풀뷰 1280x720.jpg",
      "imageWidth": 1280,
      "imageHeight": 720,
      "mimeType": "image/jpeg",
      "imageHash": "35156f0c1393434ced4be21423d08a6a"
    },
    "createdDate": "2021-06-25T17:04:02.883575",
    "lastModifiedDate": "2021-06-25T17:04:06.291245"
  }
}

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

광고 생성: 개인화 메시지 소재

시작하기 전에

주의 사항

공통 요소 가이드

홍보 이미지

홍보 문구

버튼

구성 요소별 가이드

구성 요소별 필수 여부

구성 요소별 규격

랜딩

변수값 필드명

변수값 입력 가능 요소

소재 유형별 사용 가능 변수값

기본 텍스트형

와이드 이미지형

와이드 리스트형

개인화 메시지 소재 템플릿 생성

기본 정보

요청 수 제한

요청

헤더

본문

MessageElement

ButtonAssetGroup

ItemAssetGroup

ImageFile

Image

응답

본문

MessageElement

Image

ButtonAssetGroup

ItemAssetGroup

Thumbnail

예제

요청

응답

개인화 메시지 소재 템플릿 수정

기본 정보

사용 조건

요청 수 제한

요청

헤더

본문

응답

본문

예제

요청

응답

더 보기

도움이 되었나요?