카카오모먼트

메시지광고 운영

이 문서는 카카오모먼트 메시지광고의 메시지광고 운영 API 사용 방법을 안내합니다.

시작하기 전에

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

발송 가능 메시지 유형

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

이름	메시지 유형
기본 텍스트	`BASIC_TEXT_MESSAGE`
와이드 이미지	`WIDE_MESSAGE`
와이드 리스트	`WIDE_LIST_MESSAGE`
캐러셀 커머스	`CAROUSEL_COMMERCE_MESSAGE`
캐러셀 피드	`CAROUSEL_FEED_MESSAGE`
프리미엄 동영상	`PREMIUM_VIDEO_MESSAGE`
카탈로그	`CATALOG_MESSAGE`
스포트라이트	`SPOTLIGHT_MESSAGE`

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

메시지 유형별 구성 요소

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

기본 텍스트(BASIC_TEXT_MESSAGE)

구성 요소 및 필드 경로	규격	필수
홍보 영역 `message.items.imageUrl`	홍보 영역 공통 규격을 준수한 이미지 적용 가능 랜딩: 버튼1 요소 랜딩 URL로 연결(별도 설정 불가)	X
타이틀 `message.messageTitle`	글자 수: 최대 16자 링크 입력 불가 개행 불가	X
홍보 문구 `message.description`	홍보 영역 요소 포함 여부와 관계없이 최대 1,300자, 링크 입력 불가 개행: 최대 99개 랜딩: 사용 불가	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
버튼2 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X
공유 설정 `message.shareFlag`	공유하기 사용 여부 `true`: 공유하기 사용 `false`: 공유하기 사용 안함 사용자 지정 버튼1, 버튼2와 별도 적용 `ageVerification`(연령인증 필요 메시지 여부) 값이 `true`인 경우 사용 불가	X

와이드 이미지(WIDE_MESSAGE)

구성 요소 및 필드 경로	규격	필수
홍보 영역 `message.items.imageUrl`	홍보 영역 공통 규격을 준수한 이미지 적용 가능 랜딩: 등록한 아이템 랜딩 URL로 연결	O
타이틀 `message.messageTitle`	글자 수: 최대 20자 링크 입력 불가 개행 불가	X
홍보 문구 `message.description`	글자 수: 최대 76자, 링크 입력 불가 개행: 최대 5개 랜딩: 등록한 아이템 랜딩 URL로 연결	O
소재 랜딩 `message.items.landing`	홍보 영역 클릭 시 연결되는 랜딩 Landing 등록 가능	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL 사용자 지정 버튼: 최대 1개 등록 가능	X
버튼2 `message.shareFlag`	공유하기(`message.shareFlag`) 설정 시 `공유하기` 버튼으로 동작, 버튼명과 랜딩 설정 불가	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X

와이드 리스트(WIDE_LIST_MESSAGE)

구성 요소 및 필드 경로	규격	필수
홍보 영역 `message.items.imageUrl`	홍보 영역 공통 규격을 준수한 이미지 적용 가능 랜딩: 등록한 아이템 랜딩 URL로 연결 필수 여부: 리스트1~3 필수, 리스트4~5 선택	X
타이틀 `message.messageTitle`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가 랜딩: 등록한 아이템 랜딩 URL로 연결	O
아이템 홍보 문구 `message.items.description`	리스트1 글자 수: 최대 25자, 링크 입력 불가, 개행: 최대 1개 리스트2~5 글자 수: 최대 30자, 링크 입력 불가, 개행: 최대 1개 랜딩: 등록한 아이템 랜딩 URL로 연결 필수 여부: 리스트2~3 필수, 리스트1과 리스트4~5 선택	X
소재 랜딩 `message.items.landing`	홍보 영역 클릭 시 연결되는 랜딩 Landing 등록 가능	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
버튼2 `message.shareFlag`	공유하기(`message.shareFlag`) 설정 시 `공유하기` 버튼으로 동작	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X

캐러셀 커머스(CAROUSEL_COMMERCE_MESSAGE)

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

인트로

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

캐러셀

구성 요소 및 필드 경로	규격	필수
타이틀 `message.carousels.messageTitle`	글자 수: 최대 25자, 링크 입력 불가, 개행 불가	O
홍보 이미지 `message.carousels.imageUrl`	홍보 영역 공통 규격을 준수한 이미지만 적용 가능 권장 크기: 800x400 픽셀(2:1 비율), 800x800 픽셀(1:1 비율), 800x600 픽셀(4:3 비율) 랜딩: 버튼1 랜딩 URL로 연결	O
캐러셀 랜딩 URL `message.carousels.landing`	버튼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.shareFlag`	공유하기(`message.shareFlag`) 설정 시 캐러셀(1~6) 전체가 `공유하기` 버튼으로 동작, 버튼명과 랜딩 설정 불가	X
더보기 `message.moreButton`	등록한 랜딩 URL로 연결	X

캐러셀 피드(CAROUSEL_FEED_MESSAGE)

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

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

프리미엄 동영상(PREMIUM_VIDEO_MESSAGE)

구성 요소 및 필드 경로	규격
홍보 동영상 `message.items.video.url`	사용자가 등록한 홍보 동영상 URL
홍보 동영상 자동 썸네일 `message.items.video.autoThumbnailUrl`	자동으로 생성된 홍보 동영상 썸네일 업로드 썸네일이 없는 경우 썸네일 설정됨
홍보 동영상 업로드 썸네일 `message.items.video.uploadThumbnailUrl`	사용자가 등록한 홍보 동영상 업로드 썸네일
타이틀 `message.messageTitle`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가
홍보 문구 `message.description`	글자 수: 최대 76자, 링크 입력 불가, 개행 최대 5개
버튼 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL

* 프리미엄 동영상 생성은 불가하나, 카카오비즈니스의 [카카오모먼트] > [메시지] > [메시지 만들기]에서 생성한 프리미엄 동영상 조회는 가능합니다.

카탈로그(CATALOG_MESSAGE)

아이템1~3 필수, 아이템4~7은 선택

구성 요소 및 필드 경로	규격	필수
타이틀 `message.messageTitle`	글자 수: 최대 36자, 링크 입력 불가, 개행 불가	O
홍보 문구 `message.description`	글자 수: 최대 36자, 링크 입력 불가 개행: 최대 1개	X
아이템 홍보 영역 `message.items.imageUrl`	홍보 영역 공통 규격을 준수한 이미지만 적용 가능 권장 크기: 800x400 픽셀(2:1 비율), 800x600 픽셀(4:3 비율) 랜딩: 등록한 아이템 랜딩 URL로 연결 필수 여부: 아이템1~3 필수, 아이템4~7 선택	X
아이템 타이틀 `message.items.messageTitle`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가 필수 여부: 아이템1~3 필수, 아이템4~7 선택	X
아이템 홍보 문구 `message.items.description`	카탈로그 아이템 콘텐츠 유형(CONTENTS)에서만 사용 가능한 필드 글자 수: 최대 22자, 링크 입력 불가, 개행 불가 랜딩: 버튼1 랜딩 URL로 연결 필수 여부: 아이템1~3 필수, 아이템4~7 선택	X
아이템 가격 통화코드 `message.items.priceCurrencyCode`	가격 정보의 통화 단위 설정 원화(원), 달러($), 엔화(￥), 유로(€) 중 하나로 적용 가능	O
아이템 가격 `message.items.priceAmount`	카탈로그 아이템 할인율 강조 유형(DISCOUNT_RATE_HIGHLIGHT), 가격 강조 유형(PRICE_HIGHLIGHT)에서만 사용 가능한 필드 통화 정보가 원화(원) 또는 엔화(￥)인 경우 8자리 이하 정수(0~99999999)만 입력 가능 통화 정보가 달러($) 또는 유로(€)인 경우 8자리 이하 정수 또는 8자리 이하 정수와 소수점 2자리까지 포함한 수(0~99999999.99) 입력 가능	O
아이템 가격명 `message.items.priceName`	카탈로그 아이템 할인율 강조 유형(DISCOUNT_RATE_HIGHLIGHT), 가격 강조 유형(PRICE_HIGHLIGHT)에서만 사용 가능한 필드 글자 수: 최대 4자, 링크 입력 불가, 개행 불가	X
아이템 할인 가격 `message.items.discountedPriceAmount`	카탈로그 아이템 할인율 강조 유형(DISCOUNT_RATE_HIGHLIGHT), 가격 강조 유형(PRICE_HIGHLIGHT)에서만 사용 가능한 필드 가격 정보값 미만의 1% 이상 차이나는 값 입력 필수 할인율: 할인 가격 정보 입력 시 자동 계산 및 소수점 이하 버림 후 적용(1%~100%)	X
아이템 할인 가격명 `message.items.discountedPriceName`	카탈로그 아이템 할인율 강조 유형(DISCOUNT_RATE_HIGHLIGHT), 가격 강조 유형(PRICE_HIGHLIGHT)에서만 사용 가능한 필드 글자 수: 최대 5자, 링크 입력 불가, 개행 불가 강조 가격 입력 시 '강조 가격명', '일반 가격' 입력 필수	X
소재 랜딩 `message.items.landing`	카탈로그 아이템 클릭 시 연결되는 랜딩 Landing 등록 가능	O
버튼1 `message.buttons`	버튼명: 띄어쓰기 포함 최대 8자 랜딩: 등록한 버튼 랜딩 URL로 연결 해당 요소 포함 시 필수: 버튼명, 버튼 모바일 랜딩 URL	X
쿠폰 `message.couponBook`	랜딩: 등록한 쿠폰 랜딩 URL로 연결 해당 요소 포함 시 필수: 쿠폰 유형, 쿠폰 타이틀, 쿠폰 상세 설명, 쿠폰 모바일 랜딩 URL	X

스포트라이트(SPOTLIGHT_MESSAGE)

구성 요소 및 필드 경로	규격	필수
타이틀 `message.messageTitle`	글자 수: 최대 20자, 링크 입력 불가, 개행 불가	O
홍보 문구 `message.description`	글자 수: 최대 45자, 링크 입력 불가 개행: 최대 1개	O
버튼 제목 `message.buttonTitle`	글자 수: 최대 8자	O
랜딩 URL `message.landingUrl`	앱링크 사용 불가 카카오톡 내 서비스로의 이동 링크 사용 불가	O
아이템 홍보 영역 `message.items.imageUrl`	홍보 영역 공통 규격을 준수한 이미지만 적용 가능 권장 크기: 800x400 픽셀(2:1 비율), 800x600 픽셀(4:3 비율) 랜딩: `message.landingUrl`에 등록한 URL로 연결 필수 여부: 선택, 최대 1개 등록 가능	X

홍보 영역 공통 규격

이미지
- 포맷: JPG, JPEG, PNG
- 크기: 가로 80 픽셀 초과(권장: 800x400, 800x800, 800x600 픽셀)
- 용량: 10MB 이하
- 비율: 가로:세로 비율 1:2.5 미만(권장: 2:1, 1:1, 4:3)

인코딩

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

%
|
“

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

메시지광고 저장

기본 정보

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

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

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

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

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

요청

헤더

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

본문

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

응답

본문

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

예제

요청

기본텍스트, 와이드 이미지, 와이드 리스트 아이템에서 카카오톡 채널 동영상을 사용하는 경우, imageUrl 대신 video.mediaId 만 지정해서 요청합니다. (참고: 카카오톡 채널 동영상 요청 시 본문 구성)

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "메시지광고_테스트_베이직_텍스트",
  "ageVerification": false,
  "message": {
    "type": "BASIC_TEXT_MESSAGE",
    "description": "홍보문구",
    "shareFlag": true,
    "adFlag": true,
    "items": [
      {
        "imageUrl": "https://partner.com/img/message/001.jpg"
      }
    ],
    "buttons": [
      {
        "title": "버튼 1 버튼명",
        "pcLandingUrl": "https://daum.net/1",
        "mobileLandingUrl": "https://daum.net/1"
      },
      {
        "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"
    }
  }
}'

요청: 카카오톡 채널 동영상 요청 시 본문 구성

{
  "name": "메시지광고_테스트_와이드이미지_동영상첨부",
  "ageVerification": false,
  "message": {
    "type": "WIDE_MESSAGE",
    "messageTitle": "와이드이미지 타이틀",
    "description": "와이드이미지 홍보문구",
    "adFlag": true,
    "items": [
      {
        "video": {
          "mediaId": 408
        }
      }
    ],
    "buttons": [
      {
        "title": "버튼1",
        "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-1402922220759433217",
  "name": "메시지광고_테스트_베이직_텍스트",
  "type": "BASIC_TEXT_MESSAGE",
  "description": "홍보문구",
  "items": [
    {
      "imageUrl": "https://partner.com/img/message/001.jpg"
    }
  ],
  "buttons": [
    {
      "title": "버튼 1 버튼명",
      "pcLandingUrl": "https://daum.net/1",
      "mobileLandingUrl": "https://daum.net/1"
    },
    {
      "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": true,
  "shareFlag": true
}

메시지 수정

기본 정보

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

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

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

사용 정책

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

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

메시지 유형별 파라미터 조건은 메시지 유형별 구성 요소를 참고합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	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`	메시지 이름(최대: 150자)	X
ageVerification	`Boolean`	연령인증 필요 메시지 여부 `true`: 연령인증 필요 메시지 `false`: 일반 메시지 중요: 발송 예약 등록 시 기존 값과 동일하게 지정	O
message	`Message`	생성할 메시지 정보	O

응답

본문

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

예제

요청

curl -X PATCH "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "메시지광고_테스트_베이직_텍스트",
    "ageVerification": false,
    "message": {
        "type": "BASIC_TEXT_MESSAGE",
        "description": "홍보문구 변경",
        "shareFlag": true,
        "adFlag": false,
        "items": [
            {
                "imageUrl": "https://partner.com/img/message/001.jpg"
            }
        ],
        "buttons": [
            {
                "title": "버튼 1 버튼명",
                "pcLandingUrl": "https://daum.net/1",
                "mobileLandingUrl": "https://daum.net/1"
            },
            {
                "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-1195179794616258561",
  "name": "메시지광고_테스트_베이직_텍스트",
  "type": "BASIC_TEXT_MESSAGE",
  "description": "홍보문구 변경",
  "items": [
    {
      "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/3912ceec1584f2ec1ccf8fad73145254.jpg"
    }
  ],
  "buttons": [
    {
      "title": "버튼 1 버튼명",
      "pcLandingUrl": "https://daum.net/1",
      "mobileLandingUrl": "https://daum.net/1"
    },
    {
      "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,
  "shareFlag": true
}

메시지광고 테스트 발송

기본 정보

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

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

메시지를 테스트 발송합니다.

사용 조건

친구 관계인 전화번호에만 발송 가능
발송 시 홍보문구 영역에 [테스트 발송] 문구 추가

요청 수 제한

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

요청

헤더

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

본문

이름	타입	설명	필수
phoneNumbers	`String[]`	발송 대상 전화번호, `010-1234-5678` 형식	O

응답

응답 본문 없음

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/send-test" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "phoneNumbers": ["014-0042-4549"]
    }'

응답

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

메시지광고 발송 예약

기본 정보

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

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

메시지 발송 시작 시간과 발송 대상을 설정합니다.

발송 시간 조건

발송 시작 시간은 예약 일시 기준 5분 후부터 1분 단위로 설정 가능. 단, 시작 일시를 1시간 이내로 설정하면 모수 규모에 따라 모수 생성 완료까지 발송 지연 가능
발송 시작 일시는 08:00부터 20:50까지 설정 가능. 20시 55분 이후 발송되지 않은 메시지는 익일 오전 8시 이후 발송

발송 비용

논타겟: 타게팅 정보를 설정하지 않은 메시지, 15원
타겟: 타게팅 정보를 설정한 메시지, 20원. 단, 지역 타입 Domestic(국내) 또는 디바이스만 설정한 경우 15원

요청

헤더

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

본문

이름	타입	설명	필수
targeting	`Targeting`	타게팅 성별, 연령, 지역 타게팅 설정 가능	O
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식 중요: `immediateSend`(즉시 발송 여부)가 `false`(예약 발송)인 경우 필수, `true`(즉시 발송)인 경우 전달 불가	X
immediateSend	`Boolean`	즉시 발송 여부 `true`: 즉시 발송 `false`: 예약 발송	X
pushAlarm	`Boolean`	푸시 알림 발송 여부 `true`: 푸시 알림 발송 `false`: 푸시 알림 미발송	X
trackId	`String`	전환 추적 설정, 메시지 전환 지표 제공을 위한 픽셀&SDK 설정	X
sendRate	`Integer`	분산발송 여부 분산발송을 하지 않으려면 0 설정 분산발송 하려면 분산 주기 건수 입력: 100, 500, 1000, 1500, 2000	X

Targeting

이름	타입	설명	필수
type	`Enum`	타게팅 타입 종류 `WHOLE`: 전체 친구 `SMART`: 추천 친구 `DIRECT`: 직접 설정	O
devices	`Enum: DeviceType[]`	디바이스 선택 유형 `ANDROID`: 안드로이드 `IOS`: iOS	X
demographics	`Demographics`	성별, 연령, 지역 정보	X
customs	`CustomTargeting[]`	맞춤타겟 지정	X
friendPeriod	`FriendPeriod`	친구기간 설정 설정한 기간 동안 채널 친구가 된 사용자에게만 발송	X
interests	`UfoInterest[]`	맞춤타겟 > 카카오 데이터 > 카테고리 > 관심사 맞춤타겟 카테고리 타입 조회 참고 참고: 조회만 가능	X
businessTypes	`UfoBusinessType[]`	맞춤타겟 > 카카오 데이터 > 카테고리 > 업종 맞춤타겟 카테고리 타입 조회 참고 참고: 조회만 가능	X

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
targeting	`Targeting`	타게팅 정보
price	`Long`	발송 단가(단위: 원) `15`: 타게팅 미적용 `20`: 타게팅 적용
contractCount	`Long`	구매발송수, 메시지광고 발송 예약 건 수
totalBudget	`Long`	구매 금액, 메시지광고 발송 예약 총 금액
totalBudgetWithVAT	`Double`	VAT 포함 구매 금액, `totalBudget`에 VAT를 포함한 금액 소수점 한 자리 숫자(예: `165.0`)
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식
immediateSend	`Boolean`	즉시 발송 여부 `true`: 즉시 발송 `false`: 예약 발송
pushAlarm	`Boolean`	푸시 알림 발송 여부 `true`: 푸시 알림 발송 `false`: 푸시 알림 미발송
trackId	`String`	전환 추적 설정, 메시지 전환 지표 제공을 위한 픽셀&SDK 설정
sendRate	`Integer`	분산발송 여부 분산발송을 하지 않으려면 0 설정 분산발송 하려면 분산 주기 건수 입력: 100, 500, 1000, 1500, 2000

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "targeting": {
            "type": "DIRECT",
            "friendPeriod": {
                "startDate": "2023-01-02",
                "endDate": "2025-06-27"
            },
            "customs": [
                {
                    "type": "SYNCAPP",
                    "referenceId": 192594,
                    "inclusionType": "EXCLUDE"
                },
                {
                    "type": "PLUSFRIEND",
                    "referenceId": 54746,
                    "inclusionType": "EXCLUDE"
                },
                {
                    "type": "COHORT",
                    "referenceId": 101407,
                    "inclusionType": "INCLUDE"
                },
                {
                    "type": "PLUSFRIENDGROUP",
                    "referenceId": 3302,
                    "inclusionType": "INCLUDE"
                },
                {
                    "type": "CUSTOMERDATA",
                    "referenceId": "101407",
                    "inclusionType": "INCLUDE",
                    "name": "고객데이터이름"
                }
            ]
        },
        "immediateSend": true,
        "pushAlarm": true,
        "trackId": "1498114409013397398"
    }'

응답: 타겟

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1389380653606703104",
  "targeting": {
    "type": "DIRECT",
    "devices": [],
    "businessTypes": [],
    "interests": [],
    "demographics": {
      "genders": [],
      "ages": [],
      "locationType": "ALL",
      "depth1Locations": [],
      "depth2Locations": [],
      "depth3Locations": []
    },
    "friendPeriod": {
      "startDate": "2023-01-02",
      "endDate": "2025-06-27"
    },
    "customs": [
      {
        "type": "PLUSFRIENDGROUP",
        "referenceId": "3302",
        "inclusionType": "INCLUDE",
        "name": "123"
      },
      {
        "type": "SYNCAPP",
        "referenceId": "192594",
        "inclusionType": "EXCLUDE",
        "name": "테스트 채널 1"
      },
      {
        "type": "COHORT",
        "referenceId": "101407",
        "inclusionType": "INCLUDE",
        "name": "반응고객"
      },
      {
        "type": "PLUSFRIEND",
        "referenceId": "54746",
        "inclusionType": "EXCLUDE",
        "name": "테스트 채널2"
      },
      {
        "type": "CUSTOMERDATA",
        "referenceId": "101407",
        "inclusionType": "INCLUDE",
        "name": "고객데이터이름"
      }
    ]
  },
  "price": 20,
  "contractCount": 10,
  "totalBudget": 200,
  "totalBudgetWithVAT": 220.0,
  "date": "2025-07-01 08:07",
  "trackId": "1498114409013397398",
  "sendRate": 0,
  "pushAlarm": true,
  "immediateSend": true
}

응답: 논타겟

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "30",
  "targeting": {
    "type": "DIRECT",
    "devices": ["IOS", "ANDROID"],
    "demographics": {
      "genders": [],
      "ages": [],
      "locationType": "ALL",
      "depth1Locations": [],
      "depth2Locations": [],
      "depth3Locations": []
    }
  },
  "price": 15,
  "contractCount": 10,
  "totalBudget": 150,
  "totalBudgetWithVAT": 165.0,
  "date": "2023-10-11 17:00"
}

메시지광고 발송 예약 조회

기본 정보

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

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

메시지광고 발송 예약 상세 정보를 반환합니다.

요청

헤더

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

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호 최초 생성 시 부여된 메시지 식별용 번호
targeting	`Targeting`	타게팅 성별, 연령, 지역 타게팅 설정 가능
price	`Long`	발송 단가(단위: 원) `15`: 타게팅 미적용 `20`: 타게팅 적용
contractCount	`Long`	구매발송수, 메시지광고 발송 예약 건 수
totalBudget	`Long`	구매 금액, 메시지광고 발송 예약 총 금액
totalBudgetWithVAT	`Double`	VAT 포함 구매 금액, `totalBudget`에 VAT를 포함한 금액 소수점 한 자리 숫자(예: `165.0`)
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식
immediateSend	`Boolean`	즉시 발송 여부 `true`: 즉시 발송 `false`: 예약 발송
pushAlarm	`Boolean`	푸시 알림 발송 여부 `true`: 푸시 알림 발송 `false`: 푸시 알림 미발송
trackId	`String`	전환 추적 설정, 메시지 전환 지표 제공을 위한 픽셀&SDK 설정
sendRate	`Integer`	분산발송 여부 분산발송을 하지 않으려면 0 설정 분산발송 하려면 분산 주기 건수 입력: 100, 500, 1000, 1500, 2000

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json"

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1389380653606703104",
  "targeting": {
    "type": "DIRECT",
    "devices": [],
    "businessTypes": [],
    "interests": [],
    "demographics": {
      "genders": [],
      "ages": [],
      "locationType": "ALL",
      "depth1Locations": [],
      "depth2Locations": [],
      "depth3Locations": []
    },
    "friendPeriod": {
      "startDate": "2023-01-02",
      "endDate": "2025-06-27"
    },
    "customs": [
      {
        "type": "PLUSFRIENDGROUP",
        "referenceId": "3302",
        "inclusionType": "INCLUDE",
        "name": "123"
      },
      {
        "type": "SYNCAPP",
        "referenceId": "192594",
        "inclusionType": "EXCLUDE",
        "name": "테스트 채널 1"
      },
      {
        "type": "COHORT",
        "referenceId": "101407",
        "inclusionType": "INCLUDE",
        "name": "반응고객"
      },
      {
        "type": "PLUSFRIEND",
        "referenceId": "54746",
        "inclusionType": "EXCLUDE",
        "name": "테스트 채널2"
      },
      {
        "type": "CUSTOMERDATA",
        "referenceId": "54746",
        "inclusionType": "EXCLUDE",
        "name": "고객데이터이름"
      }
    ]
  },
  "price": 20,
  "contractCount": 10,
  "totalBudget": 200,
  "totalBudgetWithVAT": 220.0,
  "date": "2025-07-01 08:07",
  "trackId": "1498114409013397398",
  "sendRate": 0,
  "pushAlarm": true,
  "immediateSend": true
}

메시지광고 발송 예약 수정

기본 정보

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

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

메시지 발송 시작 시간과 발송 대상을 수정합니다.

발송 예약 수정은 발송 시작 시간 5분 전까지 가능합니다.

요청

헤더

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

본문

이름	타입	설명	필수
targeting	`Targeting`	타게팅 성별, 연령, 지역 타게팅 설정 가능	O
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식 중요: `immediateSend`(즉시 발송 여부)가 `false`(예약 발송)인 경우 필수, `true`(즉시 발송)인 경우 전달 불가	X
immediateSend	`Boolean`	즉시 발송 여부 `true`: 즉시 발송 `false`: 예약 발송(기본값)	X
pushAlarm	`Boolean`	푸시 알림 발송 여부 `true`: 푸시 알림 발송(기본값) `false`: 푸시 알림 미발송	X
trackId	`String`	전환 추적 설정, 메시지 전환 지표 제공을 위한 픽셀&SDK 설정 생략 시 설정하지 않음	X
sendRate	`Integer`	분산발송 여부(기본값: `0`) 분산발송을 하지 않으려면 0 설정 분산발송 하려면 분산 주기 건수 입력: 100, 500, 1000, 1500, 2000	X

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호 최초 생성 시 부여된 메시지 식별용 번호
targeting	`Targeting`	타게팅 성별, 연령, 지역 타게팅 설정 가능
price	`Long`	발송 단가(단위: 원) `15`: 타게팅 미적용 `20`: 타게팅 적용
contractCount	`Long`	구매발송수, 메시지광고 발송 예약 건 수
totalBudget	`Long`	구매 금액, 메시지광고 발송 예약 총 금액
totalBudgetWithVAT	`Double`	VAT 포함 구매 금액, `totalBudget`에 VAT를 포함한 금액 소수점 한 자리 숫자(예: `165.0`)
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식
immediateSend	`Boolean`	즉시 발송 여부 `true`: 즉시 발송 `false`: 예약 발송
pushAlarm	`Boolean`	푸시 알림 발송 여부 `true`: 푸시 알림 발송 `false`: 푸시 알림 미발송
trackId	`String`	전환 추적 설정, 메시지 전환 지표 제공을 위한 픽셀&SDK 설정
sendRate	`Integer`	분산발송 여부 분산발송을 하지 않으려면 0 설정 분산발송 하려면 분산 주기 건수 입력: 100, 500, 1000, 1500, 2000

예제

요청

curl -X PATCH "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "targeting": {
            "type": "DIRECT",
            "friendPeriod": {
                "startDate": "2023-01-02",
                "endDate": "2025-06-27"
            },
            "customs": [
                {
                    "type": "SYNCAPP",
                    "referenceId": 192594,
                    "inclusionType": "EXCLUDE"
                },
                {
                    "type": "PLUSFRIEND",
                    "referenceId": 54746,
                    "inclusionType": "EXCLUDE"
                },
                {
                    "type": "COHORT",
                    "referenceId": 101407,
                    "inclusionType": "INCLUDE"
                },
                {
                    "type": "PLUSFRIENDGROUP",
                    "referenceId": 3302,
                    "inclusionType": "INCLUDE"
                },
                {
                    "type": "CUSTOMERDATA",
                    "referenceId": "54746",
                    "inclusionType": "EXCLUDE",
                    "name": "고객데이터이름"
                }
            ]
        },
        "immediateSend": true,
        "pushAlarm": true,
        "trackId": "1498114409013397398"
    }'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1389380653606703104",
  "targeting": {
    "type": "DIRECT",
    "devices": [],
    "businessTypes": [],
    "interests": [],
    "demographics": {
      "genders": [],
      "ages": [],
      "locationType": "ALL",
      "depth1Locations": [],
      "depth2Locations": [],
      "depth3Locations": []
    },
    "friendPeriod": {
      "startDate": "2023-01-02",
      "endDate": "2025-06-27"
    },
    "customs": [
      {
        "type": "PLUSFRIENDGROUP",
        "referenceId": "3302",
        "inclusionType": "INCLUDE",
        "name": "123"
      },
      {
        "type": "SYNCAPP",
        "referenceId": "192594",
        "inclusionType": "EXCLUDE",
        "name": "테스트 채널 1"
      },
      {
        "type": "COHORT",
        "referenceId": "101407",
        "inclusionType": "INCLUDE",
        "name": "반응고객"
      },
      {
        "type": "PLUSFRIEND",
        "referenceId": "54746",
        "inclusionType": "EXCLUDE",
        "name": "테스트 채널2"
      },
      {
        "type": "CUSTOMERDATA",
        "referenceId": "54746",
        "inclusionType": "EXCLUDE",
        "name": "고객데이터이름"
      }
    ]
  },
  "price": 20,
  "contractCount": 10,
  "totalBudget": 200,
  "totalBudgetWithVAT": 220.0,
  "date": "2025-07-01 08:07",
  "trackId": "1498114409013397398",
  "sendRate": 0,
  "pushAlarm": true,
  "immediateSend": true
}

타게팅 지역 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/sending-reservation/location`	비즈니스 토큰

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

메시지광고 발송 예약 시 지역 설정에 활용할 상세 정보를 반환합니다.

전체 목록은 행정구역 타입 정보 CSV 파일(다운로드)을 참고합니다.

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
codes	`String`	지역 코드 쉼표(,)로 구분된 문자열로 여러 개의 지역 코드 지정 가능 (예: `A7000A001,Q20000025`)	X

응답

본문

이름	타입	설명
id	`String`	시/도별 값
name	`String`	시/도별 값의 `depth1Name`
children	`Children[]`	하위 지역 데이터 쿼리 파라미터 `codes` 사용 시 미제공
deprecated	`Boolean`	지역 정보의 삭제 여부, `true`인 경우 삭제된 지역이며 쿼리 파라미터에 `codes`를 포함한 경우에만 응답에 포함

Children

이름	타입	설명
id	`String`	지역 값
name	`String`	지역 이름
children	`Children[]`	하위 지역 데이터
deprecated	`Boolean`	지역 정보의 삭제 여부, `true`인 경우 삭제된 지역이며 쿼리 파라미터에 `codes`를 포함한 경우에만 응답에 포함

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/sending-reservation/location" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json"

요청: 지역 코드 지정

curl -v -G "https://apis.moment.kakao.com/openapi/message/v2/message-ads/sending-reservation/location" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d "codes=A7000A001,Q20000025"

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "id": "A",
  "name": "강원특별자치도",
  "children": [
    {
      "id": "A7000",
      "name": "강릉시",
      "children": [
        {
          "id": "A7000A001",
          "name": "강남동"
        }
      ]
    }
    // ...
  ]
  // ...
}

응답: 지역 코드 지정

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
[
  {
    "id": "A7000A001",
    "name": "강원특별자치도 강릉시 강남동",
    "deprecated": true
  },
  {
    "id": "Q20000025",
    "name": "세종특별자치시 세종시 해밀동",
    "deprecated": false
  }
]

타게팅 모수 및 단가 조회

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation/targeting-price`	비즈니스 토큰

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

발송 가능한 모수 및 단가를 반환합니다.

이 API는 기존 messageAdId의 설정 값을 반영하거나 기존 발송 예약에 영향을 주지 않으며, 요청에 포함된 타게팅 조건만으로 모수와 단가를 계산해 반환합니다.

요청

헤더

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

본문

이름	타입	설명	필수
targeting	`Targeting`	타게팅	O

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
price	`Long`	발송 단가(단위: 원) `15`: 타게팅 미적용 `20`: 타게팅 적용
contractCount	`Long`	구매발송수, 메시지광고 발송 예약 건 수
totalBudget	`Long`	구매 금액, 메시지광고 발송 예약 총 금액
totalBudgetWithVAT	`Double`	VAT 포함 구매 금액, `totalBudget`에 VAT를 포함한 금액 소수점 한 자리 숫자(예: `165.0`)

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/sending-reservation/targeting-price" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "targeting": {
            "type": "WHOLE"
        }
    }'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1164046062704201728",
  "price": 15,
  "contractCount": 2,
  "totalBudget": 30,
  "totalBudgetWithVAT": 33.0
}

메시지 최적화

메시지 최적화 기능을 사용해 메시지를 등록하는 경우의 사용 방법을 안내합니다.

최적화 메시지광고 저장

기본 정보

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

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

카카오톡 채널에서 발송할 최적화 메시지광고의 소재 목록을 저장합니다.

참고 사항

저장한 메시지광고는 임시저장 상태이며, 발송하려면 최적화 메시지광고 발송 예약 API로 발송 예약을 생성해야 합니다.
소재마다 메시지 유형과 내용을 설정합니다. 메시지 유형별 구성 요소의 필드 경로에서 message는 messages의 각 항목에 대응합니다.
연령인증 여부는 메시지광고 단위로 설정하며, 모든 소재에 공통으로 적용됩니다.

요청

헤더

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

본문

이름	타입	설명	필수
name	`String`	메시지 이름(최대: 150자) 생략 시 또는 빈 값 전달 시 자동 생성	X
ageVerification	`Boolean`	연령인증 필요 메시지 여부 `true`: 연령인증 필요 메시지 `false`: 일반 메시지(기본값)	X
messages	`Message[]`	생성할 소재 정보 목록(최소: 2개, 최대: 5개) 메시지 유형별 파라미터와 규격은 메시지 유형별 구성 요소 참고	O

응답

본문

이름	타입	설명
-	`ResponseMultiMessage`	생성한 최적화 메시지 정보

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "최적화 메시지",
  "ageVerification": false,
  "messages": [
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "이번 주 새로운 상품을 확인해 보세요.",
      "adFlag": true,
      "shareFlag": false
    },
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "지금 준비한 특별한 혜택을 만나 보세요.",
      "adFlag": true,
      "shareFlag": false
    }
  ]
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-example",
  "name": "최적화 메시지",
  "messageAdType": "MULTI_BROADCAST",
  "ageVerification": false,
  "messages": [
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "이번 주 새로운 상품을 확인해 보세요.",
      "adFlag": true,
      "shareFlag": false,
      "items": [],
      "buttons": []
    },
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "지금 준비한 특별한 혜택을 만나 보세요.",
      "adFlag": true,
      "shareFlag": false,
      "items": [],
      "buttons": []
    }
  ]
}

최적화 메시지광고 수정

기본 정보

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

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

최적화 메시지광고의 이름과 소재 내용을 수정합니다.

참고 사항

소재 개수는 생성한 뒤에는 변경할 수 없으며, 임시저장 상태에서도 같습니다.
발송을 등록한 뒤에는 각 위치에 있는 소재의 메시지 유형과 연령인증 여부를 변경할 수 없습니다.
임시저장, 발송예정, 발송중지 상태에서 수정할 수 있으며, 발송 등록 여부와 수정 가능 시간 등 상태별 조건을 함께 충족해야 합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	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`	메시지 이름(최대: 150자) 생략 시 또는 빈 값 전달 시 기존 값 유지	X
ageVerification	`Boolean`	연령인증 필요 메시지 여부 `true`: 연령인증 필요 메시지 `false`: 일반 메시지 중요: 기존 값을 유지하는 경우에도 전달	O
messages	`Message[]`	수정할 소재 정보 전체 목록 중요: 기존 소재 개수와 같은 수로 전달, 각 항목은 같은 순서의 기존 소재에 대응	O

응답

본문

이름	타입	설명
-	`ResponseMultiMessage`	수정한 최적화 메시지 정보

예제

요청

curl -X PATCH "https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/${MESSAGE_AD_ID}/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "최적화 메시지 수정",
  "ageVerification": false,
  "messages": [
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "이번 주 새로운 상품을 확인해 보세요.",
      "adFlag": true,
      "shareFlag": false
    },
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "지금 준비한 특별한 혜택을 만나 보세요.",
      "adFlag": true,
      "shareFlag": false
    }
  ]
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-example",
  "name": "최적화 메시지 수정",
  "messageAdType": "MULTI_BROADCAST",
  "ageVerification": false,
  "messages": [
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "이번 주 새로운 상품을 확인해 보세요.",
      "adFlag": true,
      "shareFlag": false,
      "items": [],
      "buttons": []
    },
    {
      "type": "BASIC_TEXT_MESSAGE",
      "description": "지금 준비한 특별한 혜택을 만나 보세요.",
      "adFlag": true,
      "shareFlag": false,
      "items": [],
      "buttons": []
    }
  ]
}

최적화 메시지광고 테스트 발송

기본 정보

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

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

최적화 메시지광고에 등록된 소재 중 하나를 선택해 테스트 발송합니다.

참고 사항

전체 소재를 한 번에 발송하지 않습니다.
요청에 성공해도 실제 수신을 보장하지 않습니다.
이 API는 사용자 계정과 광고계정마다 30초에 한 번 요청할 수 있습니다.
메시지광고 테스트 발송 API의 사용 조건을 함께 참고합니다.

요청

헤더

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

본문

이름	타입	설명	필수
messageIndex	`Integer`	저장, 수정 요청의 `messages` 배열에서 테스트 발송할 소재의 위치(최소: `0`) (예: `0`은 첫 번째 소재, `1`은 두 번째 소재) 중요: `messages`의 항목 수보다 작은 값 전달	O
phoneNumbers	`String[]`	발송 대상 전화번호 목록(예: `["010-0000-0000"]`) 중요: 빈 배열과 빈 문자열 전달 불가	O

응답

응답 본문 없음

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/${MESSAGE_AD_ID}/send-test" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "messageIndex": 1,
  "phoneNumbers": [
    "010-0000-0000"
  ]
}'

응답

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

최적화 메시지광고 발송 예약

기본 정보

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

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

최적화 메시지광고의 발송 시작 시간과 발송 대상, 최적화 방식을 설정합니다.

참고 사항

targeting.type에는 OPTIMIZATION_WHOLE 또는 OPTIMIZATION_DIRECT를 지정합니다.
발송 시작 시간은 08:00부터 20:50까지의 범위에서, 현재 시각 기준 5분 후부터 30일 이내로 설정할 수 있습니다.
즉시 발송을 요청하면 현재 시각의 5분 후를 발송 시작 일시로 설정하며, 발송 가능 시간 조건을 적용합니다.
구매발송수와 구매 금액은 요청한 타게팅 조건과 최적화 메시지광고 단가를 기준으로 계산합니다.

요청

헤더

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

본문

이름	타입	설명	필수
targeting	`OptimizationTargeting`	발송 대상 및 메시지 최적화 설정	O
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식 중요: `immediateSend`(즉시 발송 여부)가 `false`(예약 발송)이거나 생략한 경우 필수, `true`(즉시 발송)인 경우 전달 불가	X
immediateSend	`Boolean`	즉시 발송 여부 `true`: 즉시 발송 `false`: 예약 발송(기본값)	X
pushAlarm	`Boolean`	푸시 알림 발송 여부 `true`: 푸시 알림 발송(기본값) `false`: 푸시 알림 미발송	X
trackId	`String`	전환 추적을 위한 픽셀 & SDK ID	X
sendRate	`Integer`	분산발송 설정 `0`: 분산발송 미사용(기본값) `100`: 주기당 100건씩 분산발송 `500`: 주기당 500건씩 분산발송 `1000`: 주기당 1,000건씩 분산발송 `1500`: 주기당 1,500건씩 분산발송 `2000`: 주기당 2,000건씩 분산발송	X

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호
targeting	`OptimizationTargeting`	타게팅 및 최적화 설정 정보
price	`Long`	발송 단가(단위: 원) 최적화 메시지광고의 단가 적용
contractCount	`Long`	구매발송수
totalBudget	`Long`	구매 금액(단위: 원)
totalBudgetWithVAT	`Double`	VAT 포함 구매 금액(단위: 원)
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식
startedDate	`String`	실제 발송 시작 일시, `yyyy-MM-dd HH:mm` 형식 제공 조건: 발송을 시작한 경우
trackId	`String`	전환 추적을 위한 픽셀 & SDK ID 제공 조건: `trackId`를 설정한 경우
sendRate	`Integer`	분산발송 설정값
pushAlarm	`Boolean`	푸시 알림 발송 여부
immediateSend	`Boolean`	즉시 발송 여부

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/${MESSAGE_AD_ID}/sending-reservation" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "targeting": {
    "type": "OPTIMIZATION_WHOLE",
    "optimizationTarget": {
      "type": "AI_CUSTOM"
    }
  },
  "date": "2026-10-16 10:00",
  "immediateSend": false,
  "pushAlarm": true,
  "sendRate": 0
}'

요청: 즉시 발송

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/${MESSAGE_AD_ID}/sending-reservation" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "targeting": {
    "type": "OPTIMIZATION_WHOLE",
    "optimizationTarget": {
      "type": "AI_CUSTOM"
    }
  },
  "immediateSend": true,
  "pushAlarm": true,
  "sendRate": 0
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-example",
  "targeting": {
    "type": "OPTIMIZATION_WHOLE",
    "optimizationTarget": {
      "type": "AI_CUSTOM",
      "sendRatios": []
    },
    "devices": [],
    "businessTypes": [],
    "interests": [],
    "customs": []
  },
  "price": 20,
  "contractCount": 10000,
  "totalBudget": 200000,
  "totalBudgetWithVAT": 220000.0,
  "date": "2026-10-16 10:00",
  "sendRate": 0,
  "pushAlarm": true,
  "immediateSend": false
}

최적화 메시지광고 발송 예약 수정

기본 정보

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

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

최적화 메시지광고의 발송 시간과 타게팅, 메시지 최적화 설정을 수정합니다.

참고 사항

발송 시작 시간 5분 전까지 수정할 수 있습니다. 발송중, 발송종료 상태이거나 발송을 시작한 뒤 중지한 예약은 수정할 수 없습니다.
targeting에는 수정할 전체 설정을 전달합니다. 선택 파라미터를 생략해도 기존 값이 유지되지 않으므로, 유지할 설정도 함께 전달해야 합니다.
date와 immediateSend의 설정 조건은 최적화 메시지광고 발송 예약 API와 같습니다.
RATIO 방식의 sendRatios는 기존 messages 순서에 맞춰 전달합니다.

요청

헤더

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

본문

이름	타입	설명	필수
targeting	`OptimizationTargeting`	발송 대상 및 메시지 최적화 설정	O
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식 중요: `immediateSend`(즉시 발송 여부)가 `false`(예약 발송)이거나 생략한 경우 필수, `true`(즉시 발송)인 경우 전달 불가	X
immediateSend	`Boolean`	즉시 발송 여부 `true`: 즉시 발송 `false`: 예약 발송(기본값)	X
pushAlarm	`Boolean`	푸시 알림 발송 여부 `true`: 푸시 알림 발송(기본값) `false`: 푸시 알림 미발송	X
trackId	`String`	전환 추적을 위한 픽셀 & SDK ID	X
sendRate	`Integer`	분산발송 설정 `0`: 분산발송 미사용(기본값) `100`: 주기당 100건씩 분산발송 `500`: 주기당 500건씩 분산발송 `1000`: 주기당 1,000건씩 분산발송 `1500`: 주기당 1,500건씩 분산발송 `2000`: 주기당 2,000건씩 분산발송	X

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호
targeting	`OptimizationTargeting`	타게팅 및 최적화 설정 정보
price	`Long`	발송 단가(단위: 원) 최적화 메시지광고의 단가 적용
contractCount	`Long`	구매발송수
totalBudget	`Long`	구매 금액(단위: 원)
totalBudgetWithVAT	`Double`	VAT 포함 구매 금액(단위: 원)
date	`String`	발송 시작 일시, `yyyy-MM-dd HH:mm` 형식
startedDate	`String`	실제 발송 시작 일시, `yyyy-MM-dd HH:mm` 형식 제공 조건: 발송을 시작한 경우
trackId	`String`	전환 추적을 위한 픽셀 & SDK ID 제공 조건: `trackId`를 설정한 경우
sendRate	`Integer`	분산발송 설정값
pushAlarm	`Boolean`	푸시 알림 발송 여부
immediateSend	`Boolean`	즉시 발송 여부

예제

요청

curl -X PATCH "https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/${MESSAGE_AD_ID}/sending-reservation" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "targeting": {
    "type": "OPTIMIZATION_DIRECT",
    "optimizationTarget": {
      "type": "RATIO",
      "sendRatios": [
        60,
        40
      ]
    },
    "devices": [
      "ANDROID"
    ]
  },
  "date": "2026-10-16 11:00",
  "immediateSend": false,
  "pushAlarm": true,
  "sendRate": 0
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-example",
  "targeting": {
    "type": "OPTIMIZATION_DIRECT",
    "optimizationTarget": {
      "type": "RATIO",
      "sendRatios": [60, 40]
    },
    "devices": ["ANDROID"],
    "businessTypes": [],
    "interests": [],
    "customs": []
  },
  "price": 20,
  "contractCount": 10000,
  "totalBudget": 200000,
  "totalBudgetWithVAT": 220000.0,
  "date": "2026-10-16 11:00",
  "sendRate": 0,
  "pushAlarm": true,
  "immediateSend": false
}

최적화 메시지광고 모수 및 단가 조회

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/${MESSAGE_AD_ID}/sending-reservation/targeting-price`	비즈니스 토큰

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

최적화 메시지광고의 발송 가능한 모수와 단가, 예상 구매 금액을 조회합니다.

참고 사항

요청한 타게팅 조건으로 계산하며, 기존 발송 예약을 변경하지 않습니다.
경로 변수에는 최적화 메시지광고의 messageAdId를 전달합니다.
targeting은 최적화 메시지광고 발송 예약 API와 같은 요청 타입을 사용하며, optimizationTarget의 방식과 sendRatios의 형식 조건도 적용합니다.
조회 결과는 조회 시점의 조건으로 계산하며, 발송 예약 시 다시 검증합니다.

요청

헤더

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

본문

이름	타입	설명	필수
targeting	`OptimizationTargeting`	모수와 단가를 조회할 타게팅 및 최적화 설정	O

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호
price	`Long`	발송 단가(단위: 원) 최적화 메시지광고의 단가 적용
contractCount	`Long`	요청한 타게팅 조건으로 산출한 구매발송수
channelFriendCount	`Long`	카카오톡 채널 친구 수
totalBudget	`Long`	구매 금액(단위: 원)
totalBudgetWithVAT	`Double`	VAT 포함 구매 금액(단위: 원)

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/optimization/${MESSAGE_AD_ID}/sending-reservation/targeting-price" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "targeting": {
    "type": "OPTIMIZATION_DIRECT",
    "optimizationTarget": {
      "type": "RATIO",
      "sendRatios": [
        60,
        40
      ]
    },
    "devices": [
      "ANDROID"
    ]
  }
}'

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-example",
  "price": 20,
  "contractCount": 10000,
  "channelFriendCount": 15000,
  "totalBudget": 200000,
  "totalBudgetWithVAT": 220000.0
}

메시지광고 종료

기본 정보

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

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

메시지광고를 종료합니다.

발송 중인 메시지는 발송 중단되고, 발송 예정 메시지는 발송 취소됩니다.

요청

헤더

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

응답

응답 본문 없음

예제

요청

curl -X PUT "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/finish" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json"

응답

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

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

메시지광고 운영

시작하기 전에

발송 가능 메시지 유형

메시지 유형별 구성 요소

기본 텍스트(BASIC_TEXT_MESSAGE)

와이드 이미지(WIDE_MESSAGE)

와이드 리스트(WIDE_LIST_MESSAGE)

캐러셀 커머스(CAROUSEL_COMMERCE_MESSAGE)

인트로

캐러셀

캐러셀 피드(CAROUSEL_FEED_MESSAGE)

프리미엄 동영상(PREMIUM_VIDEO_MESSAGE)

카탈로그(CATALOG_MESSAGE)

스포트라이트(SPOTLIGHT_MESSAGE)

홍보 영역 공통 규격

인코딩

메시지광고 저장

기본 정보

요청

헤더

본문

응답

본문

예제

요청

요청: 카카오톡 채널 동영상 요청 시 본문 구성

응답

메시지 수정

기본 정보

사용 정책

요청

헤더

경로 변수

본문

응답

본문

예제

요청

응답

메시지광고 테스트 발송

기본 정보

사용 조건

요청 수 제한

요청

헤더

경로 변수

본문

응답

예제

요청

응답

메시지광고 발송 예약

기본 정보

발송 시간 조건

발송 비용

요청

헤더

경로 변수

본문

Targeting

응답

본문

예제

요청

응답: 타겟

응답: 논타겟

메시지광고 발송 예약 조회

기본 정보

요청