광고 만들기: 개인화 메시지 소재

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

시작하기 전에

주의 사항

캐러셀 커머스형(CAROUSEL_COMMERCE_MESSAGE), 캐러셀 피드형(CAROUSEL_FEED_MESSAGE), 프리미엄동영상(PREMIUM_VIDEO_MESSAGE) 유형 및 쿠폰북 에셋 그룹(CouponBookAssetGroup)이 포함된 소재는 오픈API로 생성이 불가합니다.

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

공통 요소 가이드

홍보 이미지

홍보 동영상

카카오TV 채널에 업로드된 공개 영상 중 선택 가능합니다.

홍보 문구

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

버튼

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

구성 요소별 가이드

구성 요소별 필수 여부

* 와이드 리스트 유형의 4번째 리스트는 선택 항목이며, 사용한다면 홍보 이미지/홍보 동영상 둘 중 하나 필수, 홍보 문구 필수, 홍보 타이틀 필수로 요청

구성 요소별 규격

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

랜딩

변수값 필드명

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

변수값 입력 가능 요소

¹⁾ 개인화 메시지 이미지 업로드하기를 통해 반환받은 URL만 허용

²⁾ 개인화 메시지 비디오 등록하기로 등록한 카카오TV URL만 가능 (예: https://tv.kakao.com/v/302308909)

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

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

기본 텍스트형

와이드 이미지형

와이드 리스트형

개인화 메시지 소재 생성하기

기본 정보

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

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청하며, 요청이 성공하면 응답 본문에 JSON 객체로 생성된 소재의 상세 정보를 목록으로 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

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

요청

헤더

본문

MessageElement

ButtonAssetGroup

ItemAssetGroup

VideoMeta

ImageFile

Image

응답

본문

MessageElement

Image

Video

ButtonAssetGroup

ItemAssetGroup

Thumbnail

예제

요청

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"
    }
}

개인화 메시지 소재 수정하기

기본 정보

개인화 메시지 X 도달 캠페인 하위의 소재를 수정합니다. 캐러셀 커머스형(CAROUSEL_COMMERCE_MESSAGE), 캐러셀 피드형(CAROUSEL_FEED_MESSAGE) 유형 및 쿠폰북 에셋 그룹(CouponBookAssetGroup)이 포함된 소재는 오픈API로 수정이 불가합니다.

발송요청중이던 메시지가 있는 경우 요청 및 발송 상태가 모두 중지됩니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하며, 요청이 성공하면 응답 본문에 JSON 객체로 소재 상세 정보를 목록으로 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

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

요청

헤더

본문

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"
    }
}

더 보기

카카오모먼트 API 레퍼런스