이 문서는 개인화 메시지 소재 API 사용 방법을 안내합니다.
캐러셀 커머스형(CAROUSEL_COMMERCE_MESSAGE), 캐러셀 피드형(CAROUSEL_FEED_MESSAGE), 프리미엄동영상(PREMIUM_VIDEO_MESSAGE) 유형 및 쿠폰북 에셋 그룹(CouponBookAssetGroup)이 포함된 소재는 오픈API로 생성이 불가합니다.
메시지 집행 가이드와 맞지 않는 이미지와 문구는 사용할 수 없습니다.
항목 | 내용 |
---|---|
포맷 | JPG, JPEG, PNG |
사이즈 | 800x400, 800x800, 800x600 권장 단, 가로 80px 이하 사용 불가 |
용량 | 10MB 이하 |
비율 | 2:1, 1:1, 4:3 비율 권장 단, 가로:세로 1:2.5 이상 사용 불가 |
카카오TV 채널에 업로드된 공개 영상 중 선택 가능합니다.
변수 포함 최대 1,000자까지 작성 가능합니다. 단, 발송 요청 시 변수 치환 후에는 메시지 유형별, 영역별 가이드를 준수하여야 발송이 됩니다.
변수 포함 최대 1,000자까지 작성 가능합니다. 단, 발송 요청 시 변수 치환 후에는 최대 8글자까지 작성되어야 발송이 됩니다.
항목 | 기본 텍스트 | 와이드 이미지 | 와이드 리스트 |
---|---|---|---|
홍보 이미지/동영상 | 필수 아님 | 둘 중 하나 필수 | 리스트 1~3 중 하나 필수 |
홍보 문구 | 필수 | 필수 | - |
버튼 1 | 필수 아님 | 필수 아님 | 필수 아님 |
버튼 2 | 필수 아님 | 필수 아님 | 필수 아님 |
리스트 1 홍보 타이틀 | - | - | 필수 아님 |
리스트 2,3 홍보 타이틀 | - | - | 필수 |
* 와이드 리스트 유형의 4번째 리스트는 선택 항목이며, 사용한다면 홍보 이미지/홍보 동영상 둘 중 하나 필수, 홍보 문구 필수, 홍보 타이틀 필수로 요청
항목 | 기본 텍스트 | 와이드 이미지 | 와이드 리스트 |
---|---|---|---|
홍보 이미지/동영상 | 고정 URL 혹은 변수값 사용 가능 | 고정 URL 혹은 변수값 사용 가능 | 고정 URL 혹은 변수값 사용 가능 |
홍보 문구 | 변수값 변환 이후 - 이미지/동영상 미 첨부 시 최대 400자 - 이미지/동영상 첨부 시 최대 300자 - 링크 입력 불가, 개행은 29개까지 가능 |
변수값 변환 이후 - 최대 76자 입력 가능 - 링크 입력 불가, 개행은 1개까지 가능 |
- |
버튼 1, 2 | 변수값 변환 이후 - 띄어쓰기 포함 최대 8자 |
변수값 변환 이후 - 띄어쓰기 포함 최대 8자 |
변수값 변환 이후 - 띄어쓰기 포함 최대 8자 |
리스트 타이틀 | - | - | 변수값 변환 이후 - 최대 20자 - 개행 불가 |
리스트 1 홍보 문구 | - | - | 변수값 변환 이후 - 최대 25자 - 개행 불가 |
리스트 2,3 홍보 문구 | - | - | 변수값 변환 이후 - 최대 30자 - 개행 불가 |
* 와이드 리스트 유형의 4번째 리스트는 선택항목이며, 사용하기를 선택한다면 홍보 문구 정책은 리스트 2,3 홍보 문구와 동일
항목 | 기본 텍스트 | 와이드 이미지 | 와이드 리스트 |
---|---|---|---|
홍보 이미지 | 랜딩 불가 | 버튼 1에 설정한 랜딩 동일 | 버튼 1에 설정한 랜딩 동일 |
홍보 동영상 | 설정된 카카오TV 랜딩 | 설정된 카카오TV 랜딩 | 설정된 카카오TV 랜딩 |
홍보 문구 | 랜딩 불가 | 랜딩 불가 | - |
버튼 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} |
16 | 동영상 | video_url |
${video_url} |
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 | 문자 |
16 | 동영상²⁾ | 동영상 | 복수 | 4 | 1000 | 문자 |
17 | 모바일 URL | 랜딩 | 복수 | 13 | 1000 | 문자 |
18 | PC URL | 랜딩 | 복수 | 13 | 1000 | 문자 |
¹⁾ 개인화 메시지 이미지 업로드하기를 통해 반환받은 URL만 허용
²⁾ 개인화 메시지 비디오 등록하기로 등록한 카카오TV URL만 가능 (예: https://tv.kakao.com/v/302308909)
소재 유형별, 요소별 소재 생성에 사용 가능한 변수값은 아래와 같습니다. 발송 요청 시 치환될 결과 값은 개행 입력이 불가능합니다.
항목 | 사용 가능 변수값 |
---|---|
홍보 이미지 / 홍보 동영상 | 변수 이미지/동영상 등록 가능 고정 이미지/동영상 or 변수 이미지/동영상 중 1개만 등록 가능 |
홍보 문구 | 텍스트/가격 유형의 변수 입력 가능 |
버튼 1~2 | 랜딩 유형: URL에 한하여 변수값 지원 - 모바일 URL( mobile_url1 )- PC URL( pc_url1 )버튼명은 텍스트/가격 유형의 변수 입력 가능 |
항목 | 사용 가능 변수값 |
---|---|
홍보 이미지 / 홍보 동영상 | 변수 이미지/동영상 등록 가능 고정 이미지/동영상 or 변수 이미지/동영상 중 1개만 등록 가능 |
랜딩 | 이미지 등록 시에만 랜딩 등록 기능 지원 동영상 등록 시 랜딩은 카카오TV랜딩 자동 설정 랜딩 유형: URL에 한하여 변수값 지원 - 모바일 URL( mobile_url1 )- PC URL( pc_url1 ) |
홍보 문구 | 텍스트/가격 유형의 변수 입력 가능 |
버튼 1~2 | 랜딩 유형: URL에 한하여 변수값 지원 - 모바일 URL( mobile_url1 )- PC URL( pc_url1 )버튼명은 텍스트/가격 유형의 변수 입력 가능 |
항목 | 사용 가능 변수값 |
---|---|
타이틀 | 텍스트/가격 유형의 변수 입력 가능 |
각 리스트 홍보 이미지 / 홍보 동영상 | 변수 이미지/동영상 등록 가능 고정 이미지/동영상 or 변수 이미지/동영상 중 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 |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈앱 |
필요 | - |
개인화 메시지 X 도달 캠페인 하위의 소재를 생성합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST
로 요청하며, 요청이 성공하면 응답 본문에 JSON 객체로 생성된 소재의 상세 정보를 목록으로 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
adGroupId | Long |
광고그룹 번호 | O |
format | String |
소재 유형, 다음 중 하나 BASIC_TEXT_MESSAGE (기본텍스트) WIDE_MESSAGE (와이드이미지) WIDE_LIST_MESSAGE (와이드리스트) |
O |
name | String |
소재 이름 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간} 으로 설정(최대: 40자) |
X |
messageElement | MessageElement |
생성할 메시지 내용MULTIPART/FORM-DATA 로 mesasgeElement.{} 형식으로 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
creativeFormat | String |
메시지 소재 유형, 다음 중 하나 BASIC_TEXT_MESSAGE (기본 텍스트) WIDE_MESSAGE (와이드 이미지) WIDE_LIST_MESSAGE (와이드 리스트) format 과 동일해야 함 |
O |
profileId | String |
카카오톡 채널 프로필 ID | O |
title | String |
홍보문구 기본 텍스트 (BASIC_TEXT_MESSAGE), 와이드 이미지 (WIDE_MESSAGE) 일 경우에만 필수로 요청 기본 텍스트 (BASIC_TEXT_MESSAGE) 는 최대 400자, 와이드 이미지 (WIDE_MESSAGE) 는 최대 76자 단, 변수활용하여 생성시 글자수는 최대 1,000자까지 입력하여 생성 가능 발송 시 치환된 글자 수는 위의 가이드를 준수해야 발송 가능 |
O* |
buttonAssetGroups | ButtonAssetGroup[] |
버튼 항목들 최대 2개의 버튼 에셋 그룹을 요청할 수 있으며 버튼을 모두 미설정으로 요청할 경우 모든 메시지 유형에서 미설정 가능 버튼 1일 경우 랜딩은 URL, 포스트, 쿠폰만 설정 가능하며 버튼 2의 경우 애드뷰, 비즈니스폼까지 설정 가능 |
X |
itemAssetGroups | ItemAssetGroup[] |
리스트 항목 | O |
shareFlag | Boolean |
공유하기 개인화 메시지는 반드시 해당값을 미설정(false)로 설정해야 함 |
O |
adFlag | Boolean |
정보성 메시지 설정 (true), 미설정 (false) 중 하나 |
O |
imageFile | Multipart file |
업로드할 이미지 파일 (개인화메시지에서 고정 이미지 사용하는 경우 사용 가능) 메시지 유형이 기본 텍스트 (BASIC_TEXT_MESSAGE) 일 경우에만 요청 가능 그 외 유형은 itemAssetGroup 객체를 통해 요청 가능 |
X |
image | Image |
개인화 메시지 사용 이미지 변수 (개인화 메시지에서 가변 이미지 변수 사용하는 경우 요청) 메시지 유형이 기본 텍스트 (BASIC_TEXT_MESSAGE) 일 경우에만 요청 가능 그 외 유형은 ItemAssetGroup 객체를 통해 요청 가능 |
X* |
videoMeta | VideoMeta |
연동할 카카오TV 정보 메시지 유형이 기본 텍스트 (BASIC_TEXT_MESSAGE) 일 경우에만 요청 가능 그 외 유형은 itemAssetGroup 객체를 통해 요청 가능 |
X |
csInfo | String | 고객센터 전화번호 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ordering | Integer | 버튼 순서 0,1 전달가능 |
O |
pcLandingUrl | String |
PC 랜딩 URL 랜딩 유형이 LANDING_URL 인 경우 요청 가능하며 PC 랜딩 URL은 PC 카카오톡에서 버튼 클릭 시 별도의 URL로 랜딩 시키려는 경우 사용 http:// 또는 https:// 형식의 정상적인 랜딩 URL을 입력 |
X |
mobileLandingUrl | String |
모바일 랜딩 URLhttp:// 또는 https:// 형식의 정상적인 랜딩 URL을 입력 |
O* |
title | String |
버튼명 최대 8자까지 요청 가능 비즈니스폼의 경우 아래에 정의된 버튼명으로만 요청 가능 "톡에서 설문하기" "톡에서 시승신청" "톡에서 예약하기" "톡에서 응모하기" "톡에서 참여하기" 단, 변수활용하여 생성시 글자수는 최대 1,000자까지 입력하여 생성 가능 발송 시 치환된 글자 수는 위의 가이드를 준수해야 발송 가능 |
O |
landingType | String |
랜딩 유형, 다음 중 하나 URL 랜딩 (LANDING_URL) 쿠폰 랜딩 (CHANNEL_COUPON) 포스트 랜딩 (CHANNEL_POST) 비즈니스폼 랜딩 (BIZ_FORM) 애드뷰 랜딩 (AD_VIEW) |
O |
channelCouponId | Long |
쿠폰 ID 랜딩 유형이 쿠폰 랜딩 (CHANNEL_COUPON) 인 경우 요청 가능 메시지 버튼 쿠폰 목록 보기 API 로 조회되는 쿠폰 ID |
O* |
channelPostId | Long |
포스트 ID 랜딩 유형이 포스트 랜딩 (CHANNEL_POST) 인 경우 요청 가능 메시지 버튼 포스트 목록 보기 API로 조회되는 포스트 ID |
O* |
bizFormId | Long |
비즈니스폼 ID 랜딩 유형이 비즈니스폼 랜딩 (BIZ_FORM) 인 경우 요청 가능 메시지 버튼 비즈니스폼 목록 보기 API로 조회되는 비즈니스폼 ID |
O* |
adViewId | Long |
애드뷰 ID 랜딩 유형이 애드뷰 랜딩 (AD_VIEW) 인 경우 요청 가능 메시지 버튼 애드뷰 목록 보기 API로 조회되는 애드뷰 ID |
O* |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
landingType | String |
랜딩 유형, 다음 중 하나 URL 랜딩 (LANDING_URL) 쿠폰 랜딩 (CHANNEL_COUPON) 포스트 랜딩 (CHANNEL_POST) |
O |
title | String |
홍보문구 와이드 리스트 (WIDE_LIST_MESSAGE) 유형일때만 요청 |
O |
mobileLandingUrl | String |
모바일 랜딩URLhttp:// 또는 https:// 형식의 정상적인 랜딩 URL을 입력 |
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 (와이드 리스트) 유형에만 사용 가능하며 랜딩 유형이 URL인 경우엔 사용 불가능 |
O* |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | Long |
연동할 카카오TV 클립링크 ID 카카오TV 채널 영상 목록 보기 API로 얻은 clipLinkId |
O |
thumbnail | String |
썸네일 URL 카카오TV 채널 영상 상세 보기 API를 이용하여 응답받는 썸네일 URL |
O |
isLoad | Boolean |
카카오TV 영상 로드 여부 고정값( true )으로 전달해야 함 |
O |
isLive | Boolean |
카카오TV 라이브 영상 여부 고정값( false )으로 전달해야 함 |
O |
isLink | Boolean |
카카오TV 영상 링크 여부 고정값( true )으로 전달해야 함 |
O |
valueWithVariable | String |
변수 입력 정보 (* 개인화메시지인 경우에만 사용되며, 이 값이 입력되는 경우 다른 필드는 무시됩니다.) (예 : ${video_url1} ) |
O* |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
imageFile | Multipart File |
업로드할 이미지 파일 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
valueWithVariable | String |
변수 입력 정보 (예 : ${image_url1} ) |
O* |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
소재 대표 번호 |
creativeId | Long |
소재 번호 |
name | String |
소재명 |
adGroupId | Long |
광고 그룹 아이디 |
format | String |
소재 유형 BASIC_TEXT_MESSAGE (기본텍스트), WIDE_MESSAGE (와이드이미지), WIDE_LIST_MESSAGE (와이드리스트) |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
creativeStatus | String |
소재의 운영 상태 OPERATING(운영가능), UNAPPROVED(심사미승인), INVALID_DATE(기간오류), MONITORING_REJECTED(관리자정지), OFF(사용자OFF), DELETED(삭제), ADGROUP_UNAVAILABLE(광고그룹 운영불가) 중 하나 |
creativeDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
messageElement | MessageElement |
메시지 상세 설명 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
메시지 소재 ID |
adAccountId | Long |
광고계정 ID |
profileId | String |
카카오톡 채널 프로필 ID |
profileName | String |
카카오톡 채널 프로필명 |
name | String |
메시지 소재명 |
shareFlag | boolean |
공유하기 |
adFlag | boolean |
정보성 메시지 |
creativeFormat | String |
메시지 소재 유형 기본 텍스트 (BASIC_TEXT_MESSAGE), 와이드 이미지 (WIDE_MESSAGE), 와이드 리스트 (WIDE_LIST_MESSAGE) 중 하나 |
title | String |
홍보문구 or 타이틀 모먼트에서 기본 텍스트 (BASIC_TEXT_MESSAGE) 및 와이드 이미지 (WIDE_MESSAGE) 유형에는 홍보문구로 와이드 리스트 (WIDE_LIST_MESSAGE) 유형에는 타이틀 보여짐 |
image | Image |
이미지 소재 기본 텍스트 (BASIC_TEXT_MESSAGE) 유형에만 응답됨 |
video | Video |
카카오 TV 동영상 소재 기본 텍스트 (BASIC_TEXT_MESSAGE) 유형에만 응답됨 |
buttonAssetGroups | ButtonAssetGroup |
버튼 항목 |
itemAssetGroups | ItemAssetGroup |
리스트 항목 와이드 이미지 (WIDE_MESSAGE) 혹은 와이드 리스트 (WIDE_LIST_MESSAGE) 유형에만 응답됨 |
thumbnailUrl | String |
썸네일 이미지 URL |
csInfo | String |
고객센터 전화번호 |
createdDate | String |
메시지 소재 생성일yyyy-MM-dd'T'HH:mm:ss 형식 |
lastModifiedDate | String |
메시지 소재 마지막 수정일yyyy-MM-dd'T'HH:mm:ss 형식 |
이름 | 타입 | 설명 |
---|---|---|
size | Long |
파일 사이즈 |
url | String |
이미지 URL |
fileName | String |
이미지 파일명 |
width | Integer |
넓이 |
height | Integer |
높이 |
mimeType | String |
Mime 유형 |
valueWithVariable | String |
변수 입력 정보 (예 : ${image_url1} ) |
이름 | 타입 | 설명 |
---|---|---|
vid | String |
고유한 카카오TV 동영상 ID |
name | String |
카카오TV 동영상명 |
previewImage | String |
미리보기 이미지 URL |
thumbnail | String |
썸네일 URL |
duration | Double |
재생 시간 |
clipId | String |
Mime 유형 |
clipLinkId | Long |
클립 링크 ID |
liveLinkId | Long |
라이브 링크 ID |
channelId | Long |
채널 ID |
channelName | String |
채널명 |
isVertical | Boolean |
세로 여부 |
videoType | String |
동영상 유형 UPLOAD, PREUPLOAD, LINK, NONE 중 하나 |
isOwner | Boolean |
소유자 여부 |
valueWithVariable | String |
변수 입력 정보 (예 : ${video_url1} ) |
이름 | 타입 | 설명 |
---|---|---|
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 | String |
랜딩 유형 LANDING_URL (URL), CHANNEL_COUPON (쿠폰), CHANNEL_POST (포스트), AD_VIEW (애드뷰), BIZ_FORM (비즈니스폼) 중 하나 |
이름 | 타입 | 설명 |
---|---|---|
thumbnail | Long |
썸네일 URL |
landingType | String |
랜딩 유형 카카오TV 동영상 소재일 경우 Null이며 그 외의 경우엔 아래 유형으로 응답 LANDING_URL (URL), CHANNEL_COUPON (쿠폰), CHANNEL_POST (포스트) 중 하나 |
ordering | Integer |
정렬 순번 |
title | String |
홍보문구 아이템 에셋 그룹 내 홍보문구는 와이드 이미지, 와이드 리스트 유형에만 응답 |
mobileLandingUrl | String |
모바일 랜딩 URL 랜딩 유형이 LANDING_URL (URL) 일 경우 응답 |
pcLandingUrl | String |
PC 랜딩 URL 랜딩 유형이 LANDING_URL (URL) 일 경우 응답 |
image | Image |
이미지 소재 아이템 에셋 그룹 내 Image는 와이드 이미지, 와이드 리스트 유형에만 응답 |
video | Video |
카카오TV 동영상 소재 아이템 에셋 그룹 내 Video는 와이드 이미지, 와이드 리스트 유형에만 응답 |
thumbnail | Thumbnail |
대표 이미지 카카오TV 동영상 소재일 경우 대표 이미지로 사용되는 이미지 정보 |
이름 | 타입 | 설명 |
---|---|---|
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 {ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
-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"
curl -X POST "https://apis.moment.kakao.com/openapi/v4/creatives" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
-F messageElement.creativeFormat:WIDE_LIST_MESSAGE \
-F "Format:WIDE_LIST_MESSAGE" \
-F "messageElement.profileId=_Xxju" \
-F "messageElement.title=${brand_name1}" \
-F "messageElement.buttonAssetGroups[0].ordering=0" \
-F "messageElement.buttonAssetGroups[0].title=버튼1" \
-F "messageElement.buttonAssetGroups[0].landingType=LANDING_URL" \
-F "messageElement.buttonAssetGroups[0].pcLandingUrl=${pc_url1}" \
-F "messageElement.buttonAssetGroups[0].mobileLandingUrl=${mobile_url1}" \
-F "messageElement.shareFlag=true" \
-F "messageElement.adFlag=true" \
-F "messageElement.csInfo=014-1122-1251" \
-F "adGroupId=12345" \
-F "name=와이드리스트소재" \
-F "messageElement.itemAssetGroups[0].ordering=0" \
-F "messageElement.itemAssetGroups[0].title=${product_name1}" \
-F "messageElement.itemAssetGroups[0].landingType=LANDING_URL" \
-F "messageElement.itemAssetGroups[0].mobileLandingUrl=${mobile_url1}" \
-F "messageElement.itemAssetGroups[1].ordering=1" \
-F "messageElement.itemAssetGroups[1].title=${product_name2}" \
-F "messageElement.itemAssetGroups[1].landingType=LANDING_URL" \
-F "messageElement.itemAssetGroups[1].mobileLandingUrl=${mobile_url2}" \
-F "messageElement.itemAssetGroups[2].ordering=2" \
-F "messageElement.itemAssetGroups[2].title=${product_name3}" \
-F "messageElement.itemAssetGroups[2].landingType=LANDING_URL" \
-F "messageElement.itemAssetGroups[2].mobileLandingUrl=${mobile_url3}" \
-F "messageElement.itemAssetGroups[3].ordering=3" \
-F "messageElement.itemAssetGroups[3].title=${product_name4}" \
-F "messageElement.itemAssetGroups[3].landingType=LANDING_URL" \
-F "messageElement.itemAssetGroups[3].mobileLandingUrl=${mobile_url4}" \
-F "messageElement.itemAssetGroups[0].image.valueWithVariable=${image_url1}" \
-F "messageElement.itemAssetGroups[1].image.valueWithVariable=${image_url2}" \
-F "messageElement.itemAssetGroups[2].image.valueWithVariable=${image_url3}" \
-F "messageElement.itemAssetGroups[3].image.valueWithVariable=${image_url4}"
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 | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/creatives |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | 플랫폼 등록 카카오 로그인 활성화 비즈앱 |
필요 | - |
개인화 메시지 X 도달 캠페인 하위의 소재를 수정합니다. 캐러셀 커머스형(CAROUSEL_COMMERCE_MESSAGE), 캐러셀 피드형(CAROUSEL_FEED_MESSAGE) 유형 및 쿠폰북 에셋 그룹(CouponBookAssetGroup)이 포함된 소재는 오픈API로 수정이 불가합니다.
발송요청중이던 메시지가 있는 경우 요청 및 발송 상태가 모두 중지됩니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 PUT
으로 요청하며, 요청이 성공하면 응답 본문에 JSON 객체로 소재 상세 정보를 목록으로 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
adGroupId | Long |
광고그룹 번호 | O |
format | String |
소재 유형, 다음 중 하나 BASIC_TEXT_MESSAGE (기본텍스트) WIDE_MESSAGE (와이드이미지) WIDE_LIST_MESSAGE (와이드리스트) |
O |
name | String |
소재 이름 설정하지 않은 경우 {캠페인 유형}_{캠페인 목표}_{현재시간} 으로 설정(최대: 40자) |
X |
messageElement | MessageElement |
생성할 메시지 내용MULTIPART/FORM-DATA 로 mesasgeElement.{} 형식으로 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
creativeFormat | String |
메시지 소재 유형, 다음 중 하나 BASIC_TEXT_MESSAGE (기본 텍스트) WIDE_MESSAGE (와이드 이미지) WIDE_LIST_MESSAGE (와이드 리스트) format 과 동일해야 함 |
O |
profileId | String |
카카오톡 채널 프로필 ID | O |
title | String |
홍보문구 기본 텍스트 (BASIC_TEXT_MESSAGE), 와이드 이미지 (WIDE_MESSAGE) 일 경우에만 필수로 요청 기본 텍스트 (BASIC_TEXT_MESSAGE) 는 최대 400자, 와이드 이미지 (WIDE_MESSAGE) 는 최대 76자 |
O* |
buttonAssetGroups | ButtonAssetGroup[] |
버튼 항목들 최대 2개의 버튼 에셋 그룹을 요청할 수 있으며 버튼을 모두 미설정으로 요청할 경우 모든 메시지 유형에서 미설정 가능 버튼 1일 경우 랜딩은 URL, 포스트, 쿠폰만 설정 가능하며 버튼 2의 경우 애드뷰, 비즈니스폼까지 설정 가능 |
X |
itemAssetGroups | ItemAssetGroup[] |
리스트 항목 | O |
shareFlag | Boolean |
공유하기 개인화 메시지는 반드시 해당값을 미설정(false)로 설정해야 함 |
O |
adFlag | Boolean |
정보성 메시지 설정 (true), 미설정 (false) 중 하나 |
O |
imageFile | Multipart file |
업로드할 이미지 파일 (개인화메시지에서 고정 이미지 사용하는 경우 사용 가능) 메시지 유형이 기본 텍스트 (BASIC_TEXT_MESSAGE) 일 경우에만 요청 가능 그 외 유형은 itemAssetGroup 객체를 통해 요청 가능 |
X |
image | Image |
개인화 메시지 사용 이미지 변수 (개인화 메시지에서 가변 이미지 변수 사용하는 경우 요청) 메시지 유형이 기본 텍스트 (BASIC_TEXT_MESSAGE) 일 경우에만 요청 가능 그 외 유형은 ItemAssetGroup 객체를 통해 요청 가능 |
X* |
videoMeta | VideoMeta |
연동할 카카오TV 정보 메시지 유형이 기본 텍스트 (BASIC_TEXT_MESSAGE) 일 경우에만 요청 가능 그 외 유형은 ItemAssetGroup 객체를 통해 요청 가능 |
X |
csInfo | String | 고객센터 전화번호 | O |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
소재 대표 번호 |
creativeId | Long |
소재 번호 |
name | String |
소재명 |
adGroupId | Long |
광고 그룹 아이디 |
format | String |
소재 유형 BASIC_TEXT_MESSAGE (기본텍스트), WIDE_MESSAGE (와이드이미지), WIDE_LIST_MESSAGE (와이드리스트) |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
creativeStatus | String |
소재의 운영 상태 OPERATING(운영가능), UNAPPROVED(심사미승인), INVALID_DATE(기간오류), MONITORING_REJECTED(관리자정지), 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 {ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
-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"
}
}