쉬운 메시지광고: 개인화 메시지광고 운영

이 문서는 카카오모먼트 쉬운 메시지광고의 개인화 메시지광고 운영 및 발송 요청 API에 대한 사용 방법을 안내합니다.

시작하기 전에

개인화 메시지광고는 메시지 유형에 따라 구성 요소가 상이해 사용 가능한 파라미터와 변수가 서로 다릅니다. 자세한 내용은 자세한 내용은 개인화 메시지 유형별 구성 요소, 개인화 메시지 유형별 사용 가능 변수를 참고합니다.

발송 가능 메시지 유형

쉬운 메시지광고는 아래 유형의 메시지를 발송할 수 있습니다. 각 메시지 유형별 세부 사항은 카카오비즈니스 채널 메시지 가이드를 참고합니다.

이름	메시지 유형
기본 텍스트	`BASIC_TEXT_MESSAGE`
와이드 이미지	`WIDE_MESSAGE`
와이드 리스트	`WIDE_LIST_MESSAGE`
캐러셀 커머스	`CAROUSEL_COMMERCE_MESSAGE`
캐러셀 피드	`CAROUSEL_FEED_MESSAGE`

프리미엄 동영상(PREMIUM_VIDEO_MESSAGE) 메시지 유형은 쉬운 메시지광고 API로 발송할 수 없습니다.

개인화 메시지 유형별 구성 요소

개인화 메시지 유형별 구성 요소의 필드 경로, 규격, 필수 여부 정보에 대해 안내합니다.

기본 텍스트(BASIC_TEXT_MESSAGE)

구성 요소 및 필드 경로	규격	필수
홍보 영역 `message.items.imageUrl` `message.items.videoUrl`	홍보 영역 공통 규격을 준수한 이미지 또는 동영상 중 하나 적용 가능 랜딩: 이미지 적용 시 버튼1 랜딩 URL로 연결(별도 설정 불가), 동영상 적용 시 카카오TV 동영상 URL로 자동 등록	X
홍보 문구 `message.title`	글자 수: 홍보 영역 이미지 또는 동영상 적용 시 최대 300자(미포함 시 최대 400자), 링크 입력 불가 개행: 최대 29개 랜딩: 사용 불가	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
버튼2 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X

와이드 이미지(WIDE_MESSAGE)

구성 요소 및 필드 경로	규격	필수
홍보 영역 `message.items.imageUrl` `message.items.videoUrl`	홍보 영역 공통 규격을 준수한 이미지 또는 동영상 중 하나 적용 가능 랜딩: 이미지 적용 시 아이템 랜딩 URL 등록 필수 및 해당 URL로 연결, 동영상 적용 시 카카오TV 동영상 URL로 자동 등록	O
홍보 문구 `message.title`	글자 수: 최대 76자, 링크 입력 불가 개행: 최대 1개(필드에서 포커스 이동 시 유효성 검증) 랜딩: 홍보 영역 이미지 적용 시 아이템 랜딩 URL 등록 필수 및 해당 URL로 연결, 동영상 적용 시 카카오TV 동영상 URL로 자동 등록	O
아이템 모바일 랜딩 URL `message.items.mobileLandingUrl`	PC 카카오톡에서 별도의 URL로 랜딩이 필요한 경우 아이템 PC 랜딩 URL 추가 등록 가능	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
버튼2 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X

와이드 리스트(WIDE_LIST_MESSAGE)

구성 요소 및 필드 경로	규격	필수
홍보 영역 `message.items.imageUrl` `message.items.videoUrl`	홍보 영역 공통 규격을 준수한 이미지 또는 동영상 중 하나 적용 가능 랜딩: 이미지 적용 시 필수 등록 필요, 동영상 적용 시 카카오TV 동영상 URL로 자동 등록 필수 여부: 리스트1~3 필수, 리스트4 선택	X
타이틀 `message.title`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가 랜딩: 홍보 영역 이미지 적용 시 아이템 랜딩 URL 등록 필수 및 해당 URL로 연결, 동영상 적용 시 카카오TV 동영상 URL로 자동 등록	O
아이템 홍보 문구 `message.items.title`	리스트1 글자 수: 최대 25자, 링크 입력 불가, 개행 불가 리스트2~4 글자 수: 최대 30자, 링크 입력 불가, 개행 불가 랜딩: 홍보 영역 이미지 적용 시 아이템 랜딩 URL 등록 필수 및 해당 URL로 연결, 동영상 적용 시 카카오TV 동영상 URL로 자동 등록 필수 여부: 리스트2~3 필수, 리스트1과 리스트4 선택	X
아이템 모바일 랜딩 URL `message.items.mobileLandingUrl`	PC 카카오톡에서 별도의 URL로 랜딩이 필요한 경우 아이템 PC 랜딩 URL 추가 등록 가능	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
버튼2 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X

캐러셀 커머스(CAROUSEL_COMMERCE_MESSAGE)

인트로와 캐러셀(1~6)으로 구분
인트로 포함 시 캐러셀1 필수, 미포함 시 캐러셀1~2 필수

인트로

구성 요소 및 필드 경로	규격	필수
타이틀 `message.introCarousel.title`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가	O
홍보 이미지 `message.introCarousel.imageUrl`	홍보 영역 공통 규격을 준수한 이미지만 적용 가능 권장 크기: 800x400 픽셀(2:1 비율), 800x800 픽셀(1:1 비율), 800x600 픽셀(4:3 비율) 랜딩: 등록한 인트로 랜딩 URL로 연결	O
홍보 문구 `message.introCarousel.description`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가 랜딩: 등록한 인트로 랜딩 URL로 연결	O
인트로 모바일 랜딩 URL `message.introCarousel.mobileLandingUrl`	PC 카카오톡에서 별도의 URL로 랜딩이 필요한 경우 인트로 PC 랜딩 URL 추가 등록 가능	X

캐러셀

구성 요소 및 필드 경로	규격	필수
타이틀 `message.carousels.title`	글자 수: 최대 25자, 링크 입력 불가, 개행 불가	O
홍보 이미지 `message.carousels.imageUrl`	홍보 영역 공통 규격을 준수한 이미지만 적용 가능 권장 크기: 800x400 픽셀(2:1 비율), 800x800 픽셀(1:1 비율), 800x600 픽셀(4:3 비율) 랜딩: 버튼1 랜딩 URL로 연결	O
홍보 문구 `message.carousels.description`	글자 수: 최대 50자, 링크 입력 불가 개행: 최대 2개 랜딩: 버튼1 랜딩 URL로 연결	O
캐러셀 모바일 랜딩 URL `message.carousels.mobileLandingUrl`	버튼1 랜딩 URL로 적용 PC 카카오톡에서 별도의 URL로 랜딩이 필요한 경우 캐러셀 PC 랜딩 URL 추가 등록 가능	O
가격 정보 `message.carousels.priceAmount`	통화 정보가 원화(원) 또는 엔화(￥)인 경우 8자리 이하 정수(0~99999999)만 입력 가능 통화 정보가 달러($) 또는 유로(€)인 경우 8자리 이하 정수 또는 8자리 이하 정수와 소수점 2자리까지 포함한 수(0~99999999.99) 입력 가능	O
통화 정보 `message.carousels.priceCurrencyCode`	가격 정보의 통화 단위 설정 원화(원), 달러($), 엔화(￥), 유로(€) 중 하나로 적용 가능	O
할인 가격 정보 `message.carousels.discountedPriceAmount`	가격 정보값 미만의 1% 이상 차이나는 값 입력 필수 할인율: 할인 가격 정보 입력 시 자동 계산 및 소수점 이하 버림 후 적용(1%~100%)	X
버튼1 `message.carousels`	사용자 설정 불가, 아래 속성을 갖는 버튼으로 자동 생성됨 버튼명: `구매하기` 랜딩: 등록한 캐러셀 랜딩 URL로 연결	O
버튼2 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X

캐러셀 피드(CAROUSEL_FEED_MESSAGE)

캐러셀1~2 필수, 캐러셀3~6은 선택

구성 요소 및 필드 경로	규격	필수
타이틀 `message.carousels.title`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가 랜딩: 버튼1 랜딩 URL로 연결	O
홍보 이미지 `message.carousels.imageUrl`	홍보 영역 공통 규격을 준수한 이미지만 적용 가능 캐러셀1~6 모두 동일한 비율의 이미지 등록 필수 권장 크기: 800x400 픽셀(2:1 비율), 800x600 픽셀(4:3 비율) 랜딩: 버튼1 랜딩 URL로 연결	O
홍보 문구 `message.carousels.description`	글자 수: 최대 180자, 링크 입력 불가, 개행 불가 랜딩: 버튼1 랜딩 URL로 연결	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	O
버튼2 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X

홍보 영역 공통 규격

이미지
- 포맷: JPG, JPEG, PNG
- 크기: 가로 80 픽셀 초과(권장: 800x400, 800x800, 800x600 픽셀)
- 용량: 10MB 이하
- 비율: 가로:세로 비율 1:2.5 미만(권장: 2:1, 1:1, 4:3)
동영상
- 카카오TV 채널에 업로드 된 공개 영상만 등록 가능

개인화 메시지 유형별 사용 가능 변수

개인화 메시지광고로 발송하는 개인화 메시지의 변수 사용 정책에 대해 안내합니다.

각 메시지 유형 항목에서 구성 요소별 사용 가능한 변수 유형을 확인할 수 있습니다. 변수 유형별 세부 규격 및 제약 사항은 변수 유형 목록을 참고합니다.

변수 사용 시 구성 요소 글자 수

메시지 유형별 구성 요소의 글자 수는 변수를 포함하면 변수 유형 목록의 최대 길이까지 작성할 수 있지만, 변수를 제외한 실제 노출 글자 수는 개인화 메시지 유형별 구성 요소의 규격을 따라야 합니다.

기본 텍스트(BASIC_TEXT_MESSAGE)

구성 요소 및 필드 경로	사용 가능 변수
홍보 영역 `message.items.imageUrl` `message.items.videoUrl`	이미지 URL: 미디어 중 [이미지 URL] 만 사용 가능 동영상 URL: 미디어 중 [동영상 URL] 만 사용 가능 랜딩: 이미지 적용 시 랜딩 사용 가능, 동영상 적용 시 카카오TV 동영상 URL로 자동 적용
홍보 문구 `message.title`	텍스트
버튼1 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
버튼2 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
쿠폰 `message.couponBook`	쿠폰명: 텍스트 랜딩: 랜딩

와이드 이미지(WIDE_MESSAGE)

구성 요소 및 필드 경로	사용 가능 변수
홍보 영역 `message.items.imageUrl` `message.items.videoUrl`	이미지 URL: 미디어 중 [이미지 URL] 만 사용 가능 동영상 URL: 미디어 중 [동영상 URL] 만 사용 가능 랜딩: 이미지 적용 시 랜딩 사용 가능, 동영상 적용 시 카카오TV 동영상 URL로 자동 적용
홍보 문구 `message.title`	텍스트
버튼1 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
버튼2 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
쿠폰 `message.couponBook`	쿠폰명: 텍스트 랜딩: 랜딩

와이드 리스트(WIDE_LIST_MESSAGE)

구성 요소 및 필드 경로	사용 가능 변수
아이템 홍보 영역 `message.items.imageUrl` `message.items.videoUrl`	이미지 URL: 미디어 중 이미지 URL 동영상 URL: 미디어 중 동영상 URL 랜딩: 이미지 적용 시 랜딩 사용 가능, 동영상 적용 시 카카오TV 동영상 URL로 자동 적용
아이템 홍보 문구 `message.items.title`	텍스트
버튼1 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
버튼2 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
쿠폰 `message.couponBook`	쿠폰명: 텍스트 랜딩: 랜딩

캐러셀 커머스(CAROUSEL_COMMERCE_MESSAGE)

인트로

구성 요소 및 필드 경로	사용 가능 변수
홍보 이미지 `message.introCarousel.imageUrl`	이미지 URL: 미디어 중 이미지 URL 랜딩: 랜딩
홍보 문구 `message.introCarousel.description`	텍스트

캐러셀

구성 요소 및 필드 경로	사용 가능 변수
타이틀 `message.carousels.title`	텍스트
홍보 이미지 `message.carousels.imageUrl`	이미지 URL: 미디어 중 [이미지 URL] 만 사용 가능 랜딩: 랜딩
홍보 문구 `message.carousels.description`	텍스트
가격 정보 `message.carousels.priceAmount`	가격 중 [상품 정상 가격] 만 사용 가능
할인 가격 정보 `message.carousels.discountedPriceAmount`	가격 중 [상품 할인 가격] 만 사용 가능
버튼1 `message.carousels`	버튼명: `구매하기`로 고정 랜딩: 랜딩
버튼2 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩

캐러셀 피드(CAROUSEL_FEED_MESSAGE)

구성 요소 및 필드 경로	사용 가능 변수
타이틀 `message.carousels.title`	텍스트
홍보 이미지 `message.carousels.imageUrl`	이미지 URL: 미디어 중 [이미지 URL] 만 사용 가능 랜딩: 랜딩
홍보 문구 `message.carousels.description`	텍스트
버튼1 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
버튼2 `message.buttons`	버튼명: 텍스트 랜딩: 랜딩
쿠폰 `message.couponBook`	버튼명: 텍스트 랜딩: 랜딩

변수 유형 목록

텍스트

변수명	필드명	타입	변수 패턴	최대 개수	최대 길이
날짜	`date`	`String`	`${date1}` ~ `${date4}`	4	20
사이트명	`site_name`	`String`	`${site_name1}`	1	30
브랜드명	`brand_name`	`String`	`${brand_name1}`	1	30
고객 이름	`user_name`	`String`	`${user_name1}`	1	20
고객 ID	`user_id`	`String`	`${user_id1}`	1	20
고객 등급	`user_rating`	`String`	`${user_rating1}`	1	20
적립금	`available_point`	`Integer`	`${available_point1}`	1	10
쿠폰 개수	`available_coupon`	`Integer`	`${available_coupon1}`	1	10
상품 ID	`product_id`	`String`	`${product_id1}` ~ `${product_id7}`	7	50
상품명	`product_name`	`String`	`${product_name1}` ~ `${product_name7}`	7	25
할인율	`discount_percent`	`Integer`	`${discount_percent1}` ~ `${discount_percent7}`	7	2

가격

변수명	필드명	타입	변수 패턴	최대 개수	최대 길이
상품 정상 가격	`price`	`Integer`	`${price1}` ~ `${price7}`	7	8
상품 할인 가격	`sale_price`	`Integer`	`${sale_price1}` ~ `${sale_price7}`	7	8
할인 금액	`discount_amount`	`Integer`	`${discount_amount1}` ~ `${discount_amount7}`	7	8

미디어

변수명	필드명	타입	변수 패턴	최대 개수	최대 길이
이미지 URL	`image_url`	`String`	`${image_url1}` ~ `${image_url7}`	7	1000
동영상 URL	`video_url`	`String`	`${video_url1}` ~ `${video_url4}`	4	1000

랜딩

변수명	필드명	타입	변수 패턴	최대 개수	최대 길이
모바일 URL	`mobile_url`	`String`	`${mobile_url1}` ~ `${mobile_url13}`	13	1000
PC URL	`pc_url`	`String`	`${pc_url1}` ~ `${pc_url13}`	13	1000

인코딩

URL에 UTF-8 코드로 인코딩(Encoding)되지 않은 특수문자나 한글이 포함될 경우, iOS 기기의 카카오톡 인앱브라우저에서 광고가 정상 랜딩되지 않을 수 있습니다. 아래는 랜딩 오류가 발생할 수 있는 특수문자의 예시입니다.

%
|
“

또한 파라미터 및 매크로 치환이 필요한 딥링크(Deeplink) 형식의 URL은 공식 지원하지 않습니다.

개인화 메시지광고 저장

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal`	비즈니스 토큰

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

카카오톡 채널에서 발송될 개인화 메시지광고 내용을 저장합니다.

메시지 유형(type)에 따라 파라미터의 사용 가능 여부와 필수 여부가 다릅니다. 관련된 자세한 내용은 메시지 유형별 구성 요소를 참고합니다.

비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답은 생성된 메시지의 상세 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
channel-profile-id	카카오톡 채널 프로필 ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	요청 데이터 타입 `Content-Type: application/json`	O

본문

이름	타입	설명	필수
name	`String`	메시지 이름 최대 50자	X
ageVerification	`Boolean`	연령인증 필요 메시지 여부 `true`: 연령인증 필요 메시지 `false`: 일반 메시지(기본값)	X
message	`Message`	생성할 메시지 정보	O

응답

본문

이름	타입	설명
-	`ResponseMessage`	메시지 정보

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "개인화_메시지광고_테스트_베이직_텍스트",
    "ageVerification": false,
    "message": {
        "type": "BASIC_TEXT_MESSAGE",
        "title": "홍보문구",
        "adFlag": false,
        "items": [
            {
                "imageUrl": "${image_url1}"
            }
        ],
        "buttons": [
            {
                "title": "버튼 1 버튼명",
                "pcLandingUrl": "${pc_url1}",
                "mobileLandingUrl": "${mobile_url1}"
            },
            {
                "title": "버튼 2 버튼명",
                "pcLandingUrl": "https://daum.net/1",
                "mobileLandingUrl": "https://daum.net/1"
            }
        ],
        "couponBook": {
            "couponBookTitleType": "UPGRADE",
            "couponBookTitle": "쿠폰 타이틀",
            "title": "쿠폰 상세 설명",
            "pcLandingUrl": "https://daum.net",
            "mobileLandingUrl": "https://daum.net"
        }
    }
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1195203776475586560",
  "name": "개인화_메시지광고_테스트_베이직_텍스트",
  "type": "BASIC_TEXT_MESSAGE",
  "title": "홍보문구",
  "items": [
    {
      "imageUrl": "${image_url1}"
    }
  ],
  "buttons": [
    {
      "title": "버튼 1 버튼명",
      "pcLandingUrl": "${pc_url1}",
      "mobileLandingUrl": "${mobile_url1}"
    },
    {
      "title": "버튼 2 버튼명",
      "pcLandingUrl": "https://daum.net/1",
      "mobileLandingUrl": "https://daum.net/1"
    }
  ],
  "couponBook": {
    "title": "쿠폰 상세 설명",
    "pcLandingUrl": "https://daum.net",
    "mobileLandingUrl": "https://daum.net",
    "couponBookTitle": "쿠폰 타이틀",
    "couponBookTitleType": "UPGRADE"
  },
  "ageVerification": false,
  "adFlag": false
}

개인화 메시지 수정

기본 정보

메서드	URL	인증 방식
`PATCH`	`https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/message`	비즈니스 토큰

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

카카오톡 채널에서 발송될 개인화 메시지광고 내용을 수정합니다.

메시지 수정 정책은 아래와 같습니다.

기존의 메시지와 동일한 포맷이어야 합니다. 이름을 제외한 다른 파라미터는 무시됩니다.
메시지 집행 가이드와 맞지 않는 이미지와 문구는 사용할 수 없습니다.

메시지 유형(type)에 따라 파라미터의 사용 가능 여부와 필수 여부가 다릅니다. 관련된 자세한 내용은 메시지 유형별 구성 요소를 참고합니다.

비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 PATCH로 요청합니다. 요청 성공 시 응답은 수정된 메시지의 상세 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
channel-profile-id	카카오톡 채널 프로필 ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	요청 데이터 타입 `Content-Type: application/json`	O

경로 변수

이름	타입	설명	필수
MESSAGE_AD_ID	`String`	메시지광고 번호(`messageAdId`)	O

본문

이름	타입	설명	필수
name	`String`	메시지 이름 최대 50자	X
ageVerification	`Boolean`	연령인증 필요 메시지 여부 `true`: 연령인증 필요 메시지 `false`: 일반 메시지 생략 시 `false`로 자동 설정	X
message	`Message`	생성할 메시지 정보	O

응답

본문

이름	타입	설명
-	`ResponseMessage`	메시지 정보

예제

요청

curl -X PATCH "https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "개인화_메시지광고_테스트_베이직_텍스트",
    "ageVerification": false,
    "message": {
        "type": "BASIC_TEXT_MESSAGE",
        "title": "홍보문구 변경",
        "adFlag": false,
        "items": [
            {
                "imageUrl": "${image_url1}"
            }
        ],
        "buttons": [
            {
                "title": "버튼 1 버튼명",
                "pcLandingUrl": "${pc_url1}",
                "mobileLandingUrl": "${mobile_url1}"
            },
            {
                "title": "버튼 2 버튼명",
                "pcLandingUrl": "https://daum.net/1",
                "mobileLandingUrl": "https://daum.net/1"
            }
        ]
    }
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1195203776475586560",
  "name": "개인화_메시지광고_테스트_베이직_텍스트",
  "type": "BASIC_TEXT_MESSAGE",
  "title": "홍보문구 변경",
  "items": [
    {
      "imageUrl": "${image_url1}"
    }
  ],
  "buttons": [
    {
      "title": "버튼 1 버튼명",
      "pcLandingUrl": "${pc_url1}",
      "mobileLandingUrl": "${mobile_url1}"
    },
    {
      "title": "버튼 2 버튼명",
      "pcLandingUrl": "https://daum.net/1",
      "mobileLandingUrl": "https://daum.net/1"
    }
  ],
  "ageVerification": false,
  "adFlag": false
}

개인화 메시지광고 테스트 발송

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/send-test`	비즈니스 토큰

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

개인화 메시지광고의 테스트 발송을 요청합니다.

발송 시 홍보문구 영역에 [테스트 발송]이 추가되어 발송됩니다. 친구 관계인 전화번호 대상으로만 발송되며 사용자 계정, 광고계정마다 1분에 1회씩 테스트 발송이 가능합니다.

비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
channel-profile-id	카카오톡 채널 프로필 ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	요청 데이터 타입 `Content-Type: application/json`	O

경로 변수

이름	타입	설명	필수
MESSAGE_AD_ID	`String`	메시지광고 번호(`messageAdId`)	O

본문

이름	타입	설명	필수
phoneNumber	`String`	발송 대상 전화번호, `010-1234-5678` 형식	O
variables	`JSON`	메시지 템플릿 사용 변수의 키-값 쌍을 가지는 객체	O

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/send-test" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "phoneNumber": "010-1234-5678",
        "variables": {
           "image_url1": "https://partner.com/img/message/001.jpg",
           "user_name1": "테스트유저"
        }
    }'

응답

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

개인화 메시지광고 한 건 발송 요청

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/send-single`	비즈니스 토큰

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

개인화 메시지광고 한 건의 발송을 요청합니다.

한 번에 한 사용자에게만 발송 요청할 수 있으며, 동기 방식으로 처리되어 해당 요청이 완료될 때까지 다른 발송 요청을 할 수 없습니다.

비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답은 발송 결과 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
channel-profile-id	카카오톡 채널 프로필 ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	요청 데이터 타입 `Content-Type: application/json`	O

경로 변수

이름	타입	설명	필수
MESSAGE_AD_ID	`String`	메시지광고 번호(`messageAdId`)	O

본문

이름	타입	설명	필수
requestId	`String`	메시지광고 발송 요청 ID, 개인화 메시지광고 발송 요청을 구분하기 위한 고유값으로 아래 규칙에 맞춰 생성 후 전달 필요 `yyyyMMdd-${messageAdId}-${uniqueId_for_request}` 형식, `uniqueId_for_request`는 9자리 이하의 영문 또는 숫자	O
receiver	`PersonalMessageSendRequest`	발송 요청 메시지광고 정보	O

PersonalMessageSendRequest

이름	타입	설명	필수
receiverType	`Enum`	발송 유형 `APP_USER_ID`: `channel-profile-id`에 연결된 앱의 회원번호 `PHONE_NUMBER`: 전화번호	O
receiverKey	`String`	발송 대상 식별자 유저식별자 혹은 전화번호	O
variables	`JSON`	메시지 템플릿 사용 변수의 키-값 쌍을 가지는 객체	O

응답

본문

이름	타입	설명
requestId	`String`	메시지광고 발송 요청 ID, 메시지광고 발송 상태 조회 시 사용
receiverType	`Enum`	발송 유형 `APP_USER_ID`: `channel-profile-id`에 연결된 앱의 회원번호 `PHONE_NUMBER`: 전화번호
receiverKey	`String`	발송 대상 식별자 유저식별자 혹은 전화번호
status	`String`	발송 상태, 발송 성공 시 `SUCCEEDED` 전달, 실패 시 에러 코드와 에러 메시지 전달
sendAt	`String`	발송 일시, `yyyy-MM-dd HH:mm:ss` 형식

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/send-single" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "20240115-msg-ad-1196300604236693504-unique1",
    "receiver": {
        "receiverType": "PHONE_NUMBER",
        "receiverKey": "010-1234-5678",
        "variables": {
            "image_url1": "https://partner.com/img/message/001.jpg"
        }
    }
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "requestId": "20240115-msg-ad-1196300604236693504-unique1",
  "receiverType": "PHONE_NUMBER",
  "receiverKey": "821012347936",
  "status": "SUCCEEDED",
  "sendAt": "2024-01-15 13:00:36"
}

개인화 메시지광고 여러 건 발송 요청

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/send-multi`	비즈니스 토큰

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

개인화 메시지광고 여러 건의 발송을 요청합니다.

한 번에 최대 100명의 사용자에게 발송 요청할 수 있으며, 비동기 방식으로 처리되어 요청 결과는 개인화 메시지광고 발송 상태 조회 API로 확인해야 합니다.

비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답은 메시지광고 발송 요청 ID를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
channel-profile-id	카카오톡 채널 프로필 ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	요청 데이터 타입 `Content-Type: application/json`	O

경로 변수

이름	타입	설명	필수
MESSAGE_AD_ID	`String`	메시지광고 번호(`messageAdId`)	O

본문

이름	타입	설명	필수
requestId	`String`	메시지광고 발송 요청 ID, 개인화 메시지광고 발송 요청을 구분하기 위한 고유값으로 아래 규칙에 맞춰 생성 후 전달 필요 `yyyyMMdd-${messageAdId}-${uniqueId_for_request}` 형식, `uniqueId_for_request`는 9자리 이하의 영문 또는 숫자	O
receiver	`PersonalMessageSendRequest[]`	발송 요청 메시지광고 정보(최소: 2개, 최대: 100개)	O

PersonalMessageSendRequest

이름	타입	설명	필수
receiverType	`Enum`	발송 유형 `APP_USER_ID`: `channel-profile-id`에 연결된 앱의 회원번호 `PHONE_NUMBER`: 전화번호	O
receiverKey	`String`	발송 대상 식별자 유저식별자 혹은 전화번호	O
variables	`JSON`	메시지 템플릿 사용 변수의 키-값 쌍을 가지는 객체	O

응답

본문

이름	타입	설명
requestId	`String`	메시지광고 발송 요청 ID, 메시지광고 발송 상태 조회 시 사용

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/send-multi" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "20240115-msg-ad-1196300604236693504-unique2",
    "receivers": [
        {
            "receiverType": "PHONE_NUMBER",
            "receiverKey": "010-1234-5678",
            "variables": {
                "image_url1": "https://partner.com/img/message/001.jpg",
                "user_name1": "테스트유저1"
            }
        },
        {
            "receiverType": "PHONE_NUMBER",
            "receiverKey": "010-4321-4321",
            "variables": {
                "image_url1": "https://partner.com/img/message/002.jpg",
                "user_name1": "테스트유저2"
            }
        }
    ]
 }'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "requestId": "20240115-msg-ad-1196300604236693504-unique2"
}

개인화 메시지광고 발송 상태 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/status/${REQUEST_ID}`	비즈니스 토큰

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

개인화 메시지광고 발송 요청에 대한 결과를 조회합니다.

발송 요청으로부터 90일 이내에만 결과만 조회 가능합니다.

비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 메시지광고 발송 요청 ID를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
channel-profile-id	카카오톡 채널 프로필 ID `channel-profile-id: ${CHANNEL_PROFILE_ID}`	O
Content-Type	요청 데이터 타입 `Content-Type: application/json`	O

경로 변수

이름	타입	설명	필수
MESSAGE_AD_ID	`String`	메시지광고 번호(`messageAdId`)	O
REQUEST_ID	`String`	메시지광고 발송 요청 ID(`requestId`)	O

응답

본문

이름	타입	설명
completed	`Boolean`	발송 완료 여부 `true`: 모든 발송 완료 `false`: 발송 미완료
results	`PersonalMessageResult`	발송 시도 결과, `completed`값이 `false`인 경우 빈 배열(`[]`)로 응답

PersonalMessageResult

이름	타입	설명
receiverType	`Enum`	발송 유형 `APP_USER_ID`: `channel-profile-id`에 연결된 앱의 회원번호 `PHONE_NUMBER`: 전화번호
receiverKey	`String`	발송 대상 식별자 유저식별자 혹은 전화번호
status	`Enum`	발송 결과 `SUCCEEDED`: 발송 성공 `FAILED`: 발송 실패
statusReason	`String`	발송 결과에 대한 상세 원인
sendAt	`String`	발송 일시, `yyyy-MM-dd HH:mm:ss` 형식

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ads/personal/${MESSAGE_AD_ID}/status/${REQUEST_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "channel-profile-id: ${CHANNEL_PROFILE_ID}"

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "completed": true,
  "results": [
    {
      "receiverType": "PHONE_NUMBER",
      "receiverKey": "821012345678",
      "status": "SUCCEEDED",
      "statusReason": "발송 결과 상세 원인",
      "sendAt": "2023-07-31 16:00:01"
    }
  ]
}

공통 파라미터

Message

메시지 유형(type)별 필수 파라미터 정보는 메시지 유형별 구성 요소 참고
파라미터별 변수 사용 관련 정보는 개인화 메시지 유형별 사용 가능 변수 참고

이름	타입	설명
type	`Enum`	메시지 유형(지정 필수) `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스형 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드형
title	`String`	메시지 홍보 문구
items	`Item[]`	아이템 정보
buttons	`Button[]`	버튼 정보
couponBook	`CouponBook[]`	쿠폰 정보
introCarousel	`IntroCarousel`	인트로 정보
carousels	`Carousel[]`	캐러셀 정보
adFlag	`Boolean`	광고성 메시지 `true`: 광고성 메시지 `false`: 정보성 메시지

Item

이름	타입	설명
imageUrl	`String`	아이템 이미지 URL, 메시지 내 포함할 홍보 이미지 URL
videoUrl	`String`	아이템 동영상 URL, 메시지 내 포함할 홍보 카카오TV 동영상 URL
title	`String`	아이템 홍보 문구
pcLandingUrl	`String`	아이템 PC 랜딩 URL, 사용 시 PC 카카오톡에서 별도의 URL로 랜딩 `http://` 또는 `https://` 형식의 접속 가능한 URL 입력
mobileLandingUrl	`String`	아이템 모바일 랜딩 URL `http://` 또는 `https://` 형식의 접속 가능한 URL 입력

Button

이름	타입	설명
title	`String`	버튼명
pcLandingUrl	`String`	버튼 PC 랜딩 URL, 사용 시 PC 카카오톡에서 별도의 URL로 랜딩 `http://` 또는 `https://` 형식의 접속 가능한 URL 필요
mobileLandingUrl	`String`	버튼 모바일 랜딩 URL `http://` 또는 `https://` 형식의 접속 가능한 URL 필요

CouponBook

이름	타입	설명
couponBookTitleType	`Enum`	쿠폰 유형 `DISCOUNT_PRICE`: 할인금액 `DISCOUNT_RATE`: 할인율 `FREE_SHIPPING`: 배송비 할인 `FREE_GIFT`: 무료 증정 `UPGRADE`: 업그레이드
couponBookTitle	`String`	쿠폰 타이틀, 쿠폰 유형(`couponBookTitleType`)값에 따라 아래 값 입력 가능 `DISCOUNT_PRICE`: 8자리 이하 숫자 `DISCOUNT_RATE`: 2자리 이하 숫자 `FREE_SHIPPING`: 입력 불가 `FREE_GIFT`, `UPGRADE`: 문자열(최대: 7자)
title	`String`	쿠폰 상세 설명(최대: 12자)
pcLandingUrl	`String`	쿠폰 PC 랜딩 URL, 사용 시 PC 카카오톡에서 별도의 URL로 랜딩 `http://` 또는 `https://` 형식의 접속 가능한 URL 필요
mobileLandingUrl	`String`	쿠폰 모바일 랜딩 URL `http://` 또는 `https://` 형식의 접속 가능한 URL 필요

IntroCarousel

이름	타입	설명
title	`String`	인트로 타이틀(최대: 25자)
description	`String`	인트로 홍보 문구(최대: 50자)
imageUrl	`String`	인트로 홍보 영역 이미지 URL
pcLandingUrl	`String`	인트로 PC 랜딩 URL, 사용 시 PC 카카오톡에서 별도의 URL로 랜딩 `http://` 또는 `https://` 형식의 접속 가능한 URL 필요
mobileLandingUrl	`String`	인트로 모바일 랜딩 URL `http://` 또는 `https://` 형식의 접속 가능한 URL 필요

Carousel

이름	타입	설명
title	`String`	캐러셀 타이틀
description	`String`	캐러셀 홍보 문구
imageUrl	`String`	캐러셀 홍보 영역 이미지 URL
pcLandingUrl	`String`	캐러셀 PC 랜딩 URL, 사용 시 PC 카카오톡에서 별도의 URL로 랜딩 `http://` 또는 `https://` 형식의 접속 가능한 URL 필요
mobileLandingUrl	`String`	캐러셀 모바일 랜딩 URL `http://` 또는 `https://` 형식의 접속 가능한 URL 필요
buttons	`Button[]`	캐러셀 버튼 정보
priceAmount	`Integer`	캐러셀 가격 정보
priceCurrencyCode	`Enum: CurrencyCode`	캐러셀 통화 정보
discountedPriceAmount	`Integer`	캐러셀 할인 가격 정보, `priceAmount` 보다 1% 이상 작은 값 필요

공통 응답

ResponseMessage

이름	타입	설명
messageAdId	`String`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
name	`String`	메시지 이름(최대: 50자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값
type	`Enum`	메시지 유형 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스형 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드형
title	`String`	메시지 홍보 문구
items	`Item[]`	아이템 정보
buttons	`Button[]`	버튼 정보
couponBook	`CouponBook[]`	쿠폰 정보
introCarousel	`IntroCarousel`	인트로 정보
carousels	`Carousel[]`	캐러셀 정보
ageVerification	`Boolean`	연령인증 메시지 여부 `true`: 연령인증 메시지 `false`: 일반 메시지
adFlag	`Boolean`	광고성 메시지 `true`: 광고성 메시지 `false`: 정보성 메시지

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

쉬운 메시지광고: 개인화 메시지광고 운영

시작하기 전에

발송 가능 메시지 유형

개인화 메시지 유형별 구성 요소

기본 텍스트(BASIC_TEXT_MESSAGE)

와이드 이미지(WIDE_MESSAGE)

와이드 리스트(WIDE_LIST_MESSAGE)

캐러셀 커머스(CAROUSEL_COMMERCE_MESSAGE)

인트로

캐러셀

캐러셀 피드(CAROUSEL_FEED_MESSAGE)

홍보 영역 공통 규격

개인화 메시지 유형별 사용 가능 변수

기본 텍스트(BASIC_TEXT_MESSAGE)

와이드 이미지(WIDE_MESSAGE)

와이드 리스트(WIDE_LIST_MESSAGE)

캐러셀 커머스(CAROUSEL_COMMERCE_MESSAGE)

인트로

캐러셀

캐러셀 피드(CAROUSEL_FEED_MESSAGE)

변수 유형 목록

텍스트

가격

미디어

랜딩

인코딩

개인화 메시지광고 저장

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

개인화 메시지 수정

기본 정보

요청

헤더

경로 변수

본문

응답

본문

예제

요청

응답

개인화 메시지광고 테스트 발송

기본 정보

요청

헤더

경로 변수

본문

예제

요청

응답

개인화 메시지광고 한 건 발송 요청

기본 정보

요청

헤더

경로 변수

본문

PersonalMessageSendRequest

응답

본문

예제

요청

응답

개인화 메시지광고 여러 건 발송 요청

기본 정보