카카오모먼트

메시지광고 관리

이 문서는 카카오모먼트 메시지광고의 메시지광고 관리 API 사용 방법을 안내합니다. 메시지광고 관리 API는 메시지광고 운영에 필요한 공통 관리 기능을 제공합니다.

카카오톡 채널x도달 캠페인 하위 메시지 소재는 광고 생성: 메시지 소재에서, 개인화 메시지 x 도달 캠페인 하위 메시지 소재는 광고 생성: 개인화 메시지 소재에서 확인할 수 있습니다.

메시지광고 목록 조회

기본 정보

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

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

카카오톡 채널 하위에 생성된 메시지광고 목록을 조회합니다.

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

요청

헤더

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

쿼리 파라미터

이름	타입	설명	필수
page	`Integer`	페이지 번호 0번부터 시작	X
limit	`Integer`	페이지 사이즈	X
from	`String`	지표 조회 기간 시작일(기본값: 조회 당일 기준 2년 전) `yyyy-MM-dd` 형식	X
to	`String`	지표 조회 기간 종료일(기본값: 조회 당일) `yyyy-MM-dd` 형식	X

본문

이름	타입	설명	필수
filter	`Filter`	리스트 조회 필터	X

Filter

이름	타입	설명	필수
messageAdType	`String`	메시지광고 타입 `BROADCAST`: 메시지광고	X
messageAdIds	`String[]`	메시지광고 번호(최초 생성 시 부여된 메시지 식별용 번호) 목록	X
statuses	`String[]`	메시지 상태 `DRAFT`: 임시저장 `READY`: 발송전 `SENDING`: 발송중 `FINISHED`: 발송완료 `ADMIN_STOP`: 관리자정지 `DEL`: 삭제	X
messageTypes	`String[]`	메시지 유형 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드 `PREMIUM_VIDEO_MESSAGE`: 프리미엄 동영상 `CATALOG_MESSAGE`: 카탈로그	X
start	`String`	발송 시간 시작일,`YYYY-MM-DD` 형식 중요: `end` 포함 시 필수	X
end	`String`	발송 시간 종료일, `YYYY-MM-DD` 형식 종료일은 시작일부터 조회일 당일까지 설정 가능 중요: `start` 포함 시 필수	X
searchKeyword	`String`	메시지 이름 검색어 메시지 이름에 검색어가 포함된 검색 결과를 응답(`like` 검색)	X

응답

본문

이름	타입	설명
content	`Content[]`	메시지광고 목록
totalPages	`Long`	총 페이지 수, 조회 시 응답될 총 페이지 수
totalElements	`Long`	전체 응답가능한 메시지광고 수
first	`Boolean`	첫 페이지 여부, 아래 중 하나 `true`: 첫 페이지 `false`: 첫 페이지가 아님
last	`Boolean`	마지막 페이지 여부, 아래 중 하나 `true`: 마지막 페이지 `false`: 마지막 페이지가 아님
size	`Integer`	페이지 크기, 페이지당 메시지광고 수
number	`Integer`	페이지 번호
numberOfElements	`Integer`	현재 페이지에 포함된 메시지광고 수

Content

이름	타입	설명
messageAdId	`String`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
messageAdType	`String`	메시지광고 타입 `BROADCAST`: 메시지광고
message	`SimpleMessage`	메시지 간편 정보
name	`String`	메시지 이름(최대: 50자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값
status	`String`	메시지 상태, 아래 중 하나 `DRAFT`: 임시저장 `READY`: 발송전 `SENDING`: 발송중 `FINISHED`: 발송완료 `ADMIN_STOP`: 관리자정지 `DEL`: 삭제
sendingReservation	`SendingReservation`	메시지 발송예약 정보
metrics	`Metrics`	메시지 요약 보고서
createdDate	`String`	메시지광고 생성일, `yyyy-MM-dd HH:mm:ss` 형식
lastModifiedDate	`String`	메시지광고 마지막 수정일, `yyyy-MM-dd HH:mm:ss` 형식

SimpleMessage

이름 타입 설명

type

이름	타입	설명
type	`String`	메시지 유형, 아래 중 하나 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스형 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드형 `PREMIUM_VIDEO_MESSAGE`: 프리미엄 동영상 `CATALOG_MESSAGE`: 카탈로그
mainImageUrl	`String`	메시지 이미지 기본 텍스트(이미지 미등록) `NULL`로 응답 기본 텍스트, 와이드 이미지, 와이드리스트 `message.items.imageurl` 응답 캐러셀 커머스, 캐러셀 피드 캐러셀 커머스, 인트로 캐러셀이 있는 경우: `introcarousel.imageurl` 응답 인트로 캐러셀이 없는 경우: 1번 캐러셀의 `message.carousel.imageurl` 응답 카탈로그 1번 카탈로그의 아이템의 이미지 (`items[0].imageUrl` 응답)
mainTitle	`String`	메시지 대표 텍스트 기본 텍스트, 와이드 이미지, 와이드리스트, 카탈로그 `message.title`(최대 400자) 응답 캐러셀 커머스, 캐러셀 피드 캐러셀 커머스, 인트로 캐러셀이 있는 경우: `introcarousel.title` 응답 인트로 캐러셀이 없는 경우: 1번 캐러셀의 `message.carousel.title` 응답

String

메시지 유형, 아래 중 하나

BASIC_TEXT_MESSAGE: 기본 텍스트
WIDE_MESSAGE: 와이드 이미지
WIDE_LIST_MESSAGE: 와이드 리스트
CAROUSEL_COMMERCE_MESSAGE: 캐러셀 커머스형
CAROUSEL_FEED_MESSAGE: 캐러셀 피드형
PREMIUM_VIDEO_MESSAGE: 프리미엄 동영상
CATALOG_MESSAGE: 카탈로그

mainImageUrl

String

메시지 이미지

기본 텍스트(이미지 미등록)

NULL로 응답

기본 텍스트, 와이드 이미지, 와이드리스트

message.items.imageurl 응답

캐러셀 커머스, 캐러셀 피드

캐러셀 커머스, 인트로 캐러셀이 있는 경우: introcarousel.imageurl 응답
인트로 캐러셀이 없는 경우: 1번 캐러셀의 message.carousel.imageurl 응답

카탈로그

1번 카탈로그의 아이템의 이미지 (items[0].imageUrl 응답)

mainTitle

String

메시지 대표 텍스트
기본 텍스트, 와이드 이미지, 와이드리스트, 카탈로그

message.title(최대 400자) 응답

캐러셀 커머스, 캐러셀 피드

캐러셀 커머스, 인트로 캐러셀이 있는 경우: introcarousel.title 응답

인트로 캐러셀이 없는 경우: 1번 캐러셀의 message.carousel.title 응답

SendingReservation

이름	타입	설명
deviceTypes	`String[]`	디바이스 유형 `ANDROID`: 안드로이드 `IOS`: IOS
targeting	`Targeting`	타게팅 정보
price	`Long`	발송 단가(단위: 원), 아래 중 하나 `15`: 타게팅 미적용 `20`: 타게팅 적용
contractCount	`Integer`	구매발송수, 메시지광고 발송 예약 건 수
totalBudget	`Long`	구매 금액, 메시지광고 발송 예약 총 금액
totalBudgetWithVAT	`Long`	VAT 포함 구매 금액, `totalBudget`에 VAT를 포함한 금액
date	`String`	발송 시작 일시, `yyyy-MM-dd'T'HH:mm` 형식

Targeting

이름	타입	설명
genderType	`String`	성별 전체 선택 유형, 아래 중 하나 `ALL`: 전체 선택 `NOT_ALL`: 부분 선택
genders	`String[]`	성별 `M`: 남자 `F`: 여자
ageType	`String`	연령 전체 선택 유형, 아래 중 하나 `ALL`: 전체 선택 `NOT_ALL`: 부분 선택
ages	`String[]`	연령대 `15`: 15~19 `20`: 20~24 `25`: 25~29 `30`: 30~34 `35`: 35~39 `40`: 40~44 `45`: 45~49 `50`: 50~54 `55`: 55~59 `60`: 60~64 `65`: 65~69
locationType	`String`	지역 선택 유형, 아래 중 하나 `ALL`: 전체(국내, 해외) `DOMESTIC`: 국내만 `AREA`: 지역 선택
depth1Locations	`Location[]`	데모그래픽 > 행정구역 > 시/도 시/도 조회 참고
depth2Locations	`Depth2Location[]`	데모그래픽 > 행정구역 > 시/군/구 시/군/구 조회 참고
depth3Locations	`Depth3Location[]`	데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고

Metrics

이름	타입	설명
cost	`Long`	메시지 발송 비용(VAT 제외), 메시지광고 발송 완료로 과금된 총 비용
msg_send	`Long`	메시지 발송 수, 사용자에게 발송된 메시지 누적 수
msg_send_fail	`Long`	메시지 발송 실패 수, 사용자에게 발송 실패한 메시지 누적 수
msg_open	`Long`	메시지 열람 수, 발송된 메시지를 채팅방 진입 후 확인한 사용자 수
msg_click	`Long`	메시지 클릭 수, 메시지에서 발생한 전체 클릭 수

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
        "messageAdType": "PERSONAL",
        "messageAdIds": [],
        "statuses": [],
        "messageTypes": [],
        "start": null,
        "end": null,
        "searchKeyword": "메시지"
        }
    }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
            "messageAdId": "msg-ad-1196357486962585601",
            "messageAdType": "PERSONAL",
            "name": "메시지광고_테스트_와이드_이미지",
            "status": "READY",
            "sendingReservation": {
                "deviceTypes": [],
                "targeting": {
                    "genderType": "ALL",
                    "genders": [],
                    "ageType": "ALL",
                    "ages": [],
                    "locationType": "ALL",
                    "depth1Locations": [],
                    "depth2Locations": [],
                    "depth3Locations": []
                },
                "date": "2024-01-15 16:37"
            },
            "metrics": null,
            "createdDate": "2024-01-15 16:37:32",
            "lastModifiedDate": "2024-01-15 16:37:32"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 10,
        "sort": {
            "empty": false,
            "sorted": true,
            "unsorted": false
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalElements": 19,
    "totalPages": 2,
    "first": true,
    "size": 10,
    "number": 0,
    "sort": {
        "empty": false,
        "sorted": true,
        "unsorted": false
    },
    "numberOfElements": 10,
    "empty": false
}

메시지광고 조회

기본 정보

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

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

개별 메시지광고의 상세 정보를 조회합니다.

메시지 내용, 발송 시간, 발송 대상 등을 확인할 수 있습니다.

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

요청

헤더

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

경로 변수

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

응답

본문

이름	타입	설명
messageAdId	`String`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
messageAdType	`String`	메시지광고 타입 `BROADCAST`: 메시지광고
name	`String`	메시지 이름(최대: 50자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값
message	`ResponseMessage`	메시지 정보
sendingReservation	`SendingReservation`	메시지 발송예약 정보
status	`String`	메시지 상태, 아래 중 하나 `DRAFT`: 임시저장 `READY`: 발송전 `SENDING`: 발송중 `FINISHED`: 발송완료 `ADMIN_STOP`: 관리자정지 `DEL`: 삭제
ageVerification	`Boolean`	연령인증 필요 메시지 여부 `true`: 연령인증 필요 메시지 `false`: 일반 메시지
createdDate	`String`	메시지광고 생성일, `yyyy-MM-dd HH:mm:ss` 형식
lastModifiedDate	`String`	메시지광고 마지막 수정일, `yyyy-MM-dd HH:mm:ss` 형식

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}" \
  -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-1195183093423038464",
    "messageAdType": "BROADCAST",
    "name": "메시지광고_테스트_와이드_이미지",
    "message": {
        "type": "WIDE_MESSAGE",
        "title": "홍보문구",
        "items": [
            {
                "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/72750c9573241f3409d6f8e44cd66ac8.jpg",
                "pcLandingUrl": "https://daum.net",
                "mobileLandingUrl": "https://daum.net"
            }
        ],
        "buttons": [
            {
                "title": "버튼 1 버튼명",
                "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
    },
    "sendingReservation": {},
    "status": "DRAFT",
    "ageVerification": false,
    "createdDate": "2024-01-12 10:50:54",
    "lastModifiedDate": "2024-01-12 10:50:54"
}

메시지광고 삭제

기본 정보

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

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

메시지광고를 삭제합니다.

삭제한 메시지 정보는 더 이상 조회할 수 없고, 복구도 불가능합니다.

비즈니스 토큰과 광고계정 ID, 카카오톡 채널 프로필 ID를 헤더에 담아 DELETE로 요청합니다. 요청 성공 시 응답은 본문 없이 HTTP 200 상태 코드만 반환합니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

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

경로 변수

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

예제

요청

curl -v -X DELETE "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}" \
  -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

메시지 조회

기본 정보

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

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

메시지 내용을 상세 조회합니다.

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

요청

헤더

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

경로 변수

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

응답

본문

메시지광고: 메시지 유형별 구성 요소

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

예제

요청

curl -X GET "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"

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "messageAdId": "msg-ad-1195179794616258561",
    "name": "메시지광고_테스트_베이직_텍스트",
    "type": "BASIC_TEXT_MESSAGE",
    "title": "홍보문구",
    "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}/copy`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

카카오톡 채널에서 발송될 메시지광고의 메시지를 복사합니다.

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

요청

헤더

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

경로 변수

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

응답

본문

메시지광고: 메시지 유형별 구성 요소

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

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/copy" \
  -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-1195179794616258561",
    "name": "메시지광고_테스트_베이직_텍스트",
    "type": "BASIC_TEXT_MESSAGE",
    "title": "홍보문구 변경",
    "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/reports`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

메시지에 대한 보고서를 조회합니다.

보고서 지표 그룹(metricsGroup)은 복수 선택이 가능합니다.

특정 일자에 해당하는 보고서는 그 다음날 오전 8시 이전까지는 변동 가능한 실시간성 지표로 참고합니다. 오늘(실시간) 보고서가 궁금하다면 datePreset=TODAY를, 시간대별 데이터가 궁금하다면 dimension=HOUR를 사용합니다.

dataPreset 혹은 start, end 중 1개의 값을 요청할 수 있습니다. 중복 요청 시 start, end 조건의 데이터가 조회됩니다.

보고서 조회 기준(dimension)은 MESSAGE_TYPE(메시지유형), DEVICE_TYPE(디바이스), HOUR(시간대)를 제공합니다.

비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답은 data 필드 하위에 배열로 보고서 데이터를 포함합니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더

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

본문

이름	타입	설명	필수
messageAdIds	`String[]`	메시지광고 번호(최초 생성 시 부여된 메시지 식별용 번호) 목록(최대: 100개)	X
datePreset	`DatePreset`	보고서 조회기간, 아래 중 하나 `TODAY`: 오늘(기본값) `YESTERDAY`: 어제 `LAST_7DAY`: 지난 1주 `LAST_14DAY`: 지난 2주 `LAST_30DAY`: 지난 30일 `THIS_MONTH`: 이번 달 `LAST_MONTH`: 저번 달	X
start	`String`	보고서 조회기간 시작일, `YYYY-MM-DD` 형식 `start`, `end` 중 하나라도 `null`이면 `datePreset` 기준으로 조회 `datePreset`도 명시되지 않았다면 `datePreset` 중 `TODAY` 기준으로 조회 시작일은 조회일 전일까지 설정 가능	X
end	`String`	보고서 조회기간 종료일, `YYYY-MM-DD` 형식 종료일은 시작일부터 조회일 전일까지 설정 가능	X
dimension	`Dimension`	보고서 조회 기준, 보고서 조회 시 데이터가 그룹화될 기준	O
metricsGroup	`MetricsGroup[]`	보고서 지표 그룹	O

Enum: Dimension

값	설명	코드
MESSAGE_AD	메시지광고	MESSAGE_AD
MESSAGE_TYPE	메시지 유형 기본 텍스트 와이드 리스트 와이드 이미지 캐러셀 커머스 캐러셀 피드 카탈로그	BASIC_TEXT_MESSAGE WIDE_LIST_MESSAGE WIDE_MESSAGE CAROUSEL_COMMERCE_MESSAGE CAROUSEL_FEED_MESSAGE CATALOG_MESSAGE
DEVICE_TYPE	디바이스 total PC Android iOS 기타	total PC Android iOS N/A
HOUR	시간대 total 00:00~00:59 01:00~01:59 02:00~02:59 03:00~03:59 04:00~04:59 05:00~05:59 06:00~06:59 07:00~07:59 08:00~08:59 09:00~09:59 10:00~10:59 11:00~11:59 12:00~12:59 13:00~13:59 14:00~14:59 15:00~15:59 16:00~16:59 17:00~17:59 18:00~18:59 19:00~19:59 20:00~20:59 21:00~21:59 22:00~22:59 23:00~23:59	total 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23

MetricsGroup

값	설명	코드
MESSAGE	메시지 기본 지표 비용 발송수 열람수 전체 클릭수 발송 실패수	cost msg_send msg_open msg_click msg_send_fail
MESSAGE_ADDITION	메시지 추가 지표 발송당 비용 열람당 비용 전체 클릭당 비용 열람률 메시지 클릭률	cost_per_msg_send cost_per_msg_open cost_per_msg_click msg_open_rate msg_click_rate
PIXEL_SDK_CONVERSION	픽셀 & SDK 전환 지표 가입 완료 (1일) 가입 완료 (7일) 장바구니 보기 (1일) 장바구니 보기 (7일) 구매 (1일) 구매 (7일) 구매 금액 (1일) 구매 금액 (7일) 잠재 고객 (1일) 잠재 고객 (7일) 서비스 신청 (1일) 서비스 신청 (7일) 앱 설치 (1일) 앱 설치 (7일) 회원 가입당 비용 (1일) 회원 가입당 비용 (7일) 회원 가입률 (1일) 회원 가입률 (7일) 관심상품추가 (1일) 관심상품추가당 비용 (1일) 관심상품추가율 (1일) 관심상품추가 (7일) 관심상품추가당 비용 (7일) 관심상품추가율 (7일) 장바구니추가(1일) 장바구니추가당 비용(1일) 장바구니추가율(1일) 장바구니추가(7일) 장바구니추가당 비용(7일) 장바구니추가율(7일) 장바구니 열람당 비용 (1일) 장바구니 열람당 비용 (7일) 장바구니 열람률 (1일) 장바구니 열람률 (7일) 구매당 비용 (1일) 구매당 비용 (7일) 구매율 (1일) 구매율 (7일) 잠재 고객당 비용 (1일) 잠재 고객당 비용 (7일) 잠재 고객률 (1일) 잠재 고객률 (7일) 서비스 신청당 비용 (1일) 서비스 신청당 비용 (7일) 서비스 신청률 (1일) 서비스 신청률 (7일) 앱 설치당 비용 (1일) 앱 설치당 비용 (7일) 앱 설치율 (1일) 앱 설치율 (7일)	conv_cmpt_reg_1d conv_cmpt_reg_7d conv_view_cart_1d conv_view_cart_7d conv_purchase_1d conv_purchase_7d conv_purchase_p_1d conv_purchase_p_7d conv_participation_1d conv_participation_7d conv_signup_1d conv_signup_7d conv_app_install_1d conv_app_install_7d cost_per_conv_cmpt_reg_1d cost_per_conv_cmpt_reg_7d conv_cmpt_reg_1d_rate conv_cmpt_reg_7d_rate conv_add_to_wishlist_1d cost_per_conv_add_to_wishlist_1d conv_add_to_wishlist_1d_rate conv_add_to_wishlist_7d cost_per_conv_add_to_wishlist_7d conv_add_to_wishlist_7d_rate conv_add_to_cart_1d cost_per_conv_add_to_cart_1d conv_add_to_cart_1d_rate conv_add_to_cart_7d cost_per_conv_add_to_cart_7d conv_add_to_cart_7d_rate cost_per_conv_view_cart_1d cost_per_conv_view_cart_7d conv_view_cart_1d_rate conv_view_cart_7d_rate cost_per_conv_purchase_1d cost_per_conv_purchase_7d conv_purchase_1d_rate conv_purchase_7d_rate cost_per_conv_participation_1d cost_per_conv_participation_7d conv_participation_1d_rate conv_participation_7d_rate cost_per_conv_signup_1d cost_per_conv_signup_7d conv_signup_1d_rate conv_signup_7d_rate cost_per_conv_app_install_1d cost_per_conv_app_install_7d conv_app_install_1d_rate conv_app_install_7d_rate
MESSAGE_CLICK	메시지 클릭 지표 공유버튼 클릭수 이미지/동영상 클릭수 타이틀 클릭수 텍스트 클릭수 리스트1 클릭수 리스트2 클릭수 리스트3 클릭수 리스트4 클릭수 리스트5 클릭수 버튼1 클릭수 버튼2 클릭수 캐러셀 1 버튼1 클릭수 캐러셀 2 버튼1 클릭수 캐러셀 3 버튼1 클릭수 캐러셀 4 버튼1 클릭수 캐러셀 5 버튼1 클릭수 캐러셀 6 버튼1 클릭수 캐러셀 1 버튼2 클릭수 캐러셀 2 버튼2 클릭수 캐러셀 3 버튼2 클릭수 캐러셀 4 버튼2 클릭수 캐러셀 5 버튼2 클릭수 캐러셀 6 버튼2 클릭수 캐러셀 1 쿠폰 버튼 클릭수 캐러셀 2 쿠폰 버튼 클릭수 캐러셀 3 쿠폰 버튼 클릭수 캐러셀 4 쿠폰 버튼 클릭수 캐러셀 5 쿠폰 버튼 클릭수 캐러셀 6 쿠폰 버튼 클릭수 아이템1 클릭수 아이템2 클릭수 아이템3 클릭수 아이템4 클릭수 아이템5 클릭수 아이템6 클릭수 아이템7 클릭수 더보기 클릭수 쿠폰 버튼 클릭수 기타 클릭수	msg_click_share msg_click_media msg_click_title msg_click_text msg_click_list1 msg_click_list2 msg_click_list3 msg_click_list4 msg_click_list5 msg_click_button1 msg_click_button2 msg_click_carousel_button1 msg_click_carousel_button2 msg_click_carousel_button3 msg_click_carousel_button4 msg_click_carousel_button5 msg_click_carousel_button6 msg_click_carousel_share1 msg_click_carousel_share2 msg_click_carousel_share3 msg_click_carousel_share4 msg_click_carousel_share5 msg_click_carousel_share6 msg_click_carousel1_coupon msg_click_carousel2_coupon msg_click_carousel3_coupon msg_click_carousel4_coupon msg_click_carousel5_coupon msg_click_carousel6_coupon msg_click_catalog_item1 msg_click_catalog_item2 msg_click_catalog_item3 msg_click_catalog_item4 msg_click_catalog_item5 msg_click_catalog_item6 msg_click_catalog_item7 msg_click_carousel_more msg_click_coupon msg_click_others
MESSAGE_CAROUSEL_VIEW	메시지 노출 지표 캐러셀 인트로 노출수 캐러셀 1 노출수 캐러셀 2 노출수 캐러셀 3 노출수 캐러셀 4 노출수 캐러셀 5 노출수 캐러셀 6 노출수	msg_carousel_intro_view msg_carousel1_view msg_carousel2_view msg_carousel3_view msg_carousel4_view msg_carousel5_view msg_carousel6_view

응답

본문

이름	타입	설명
code	`Integer`	응답 코드
message	`String`	결과 안내 메시지
data	`Data`	각 보고서 상세 데이터

Data

이름	타입	설명
start	`String`	시작일, `YYYY-MM-DD` 형식
end	`String`	종료일, `YYYY-MM-DD` 형식
dimensions	`Dimension`	보고서 기준과 값
metrics	`MetricsGroup`	보고서 지표와 값

Dimension

값	설명	코드
message_ad_id	메시지광고 번호 최초 생성 시 부여된 메시지 식별용 번호	-
MESSAGE_AD	메시지광고	MESSAGE_AD
MESSAGE_TYPE	메시지 유형 기본 텍스트 와이드 리스트 와이드 이미지 캐러셀 커머스 캐러셀 피드 카탈로그	BASIC_TEXT_MESSAGE WIDE_LIST_MESSAGE WIDE_MESSAGE CAROUSEL_COMMERCE_MESSAGE CAROUSEL_FEED_MESSAGE CATALOG_MESSAGE
DEVICE_TYPE	디바이스 total PC Android iOS 기타	total PC Android iOS N/A
HOUR	시간대 total 00:00~00:59 01:00~01:59 02:00~02:59 03:00~03:59 04:00~04:59 05:00~05:59 06:00~06:59 07:00~07:59 08:00~08:59 09:00~09:59 10:00~10:59 11:00~11:59 12:00~12:59 13:00~13:59 14:00~14:59 15:00~15:59 16:00~16:59 17:00~17:59 18:00~18:59 19:00~19:59 20:00~20:59 21:00~21:59 22:00~22:59 23:00~23:59	total 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23

MetricsGroup

값	설명	코드
MESSAGE	메시지 기본 지표 비용 발송수 열람수 전체 클릭수 발송 실패수	cost msg_send msg_open msg_click msg_send_fail
MESSAGE_ADDITION	메시지 추가 지표 발송당 비용 열람당 비용 전체 클릭당 비용 열람률 메시지 클릭률	cost_per_msg_send cost_per_msg_open cost_per_msg_click msg_open_rate msg_click_rate
PIXEL_SDK_CONVERSION	픽셀 & SDK 전환 지표 가입 완료 (1일) 가입 완료 (7일) 장바구니 보기 (1일) 장바구니 보기 (7일) 구매 (1일) 구매 (7일) 구매 금액 (1일) 구매 금액 (7일) 잠재 고객 (1일) 잠재 고객 (7일) 서비스 신청 (1일) 서비스 신청 (7일) 앱 설치 (1일) 앱 설치 (7일) 회원 가입당 비용 (1일) 회원 가입당 비용 (7일) 회원 가입률 (1일) 회원 가입률 (7일) 관심상품추가 (1일) 관심상품추가당 비용 (1일) 관심상품추가율 (1일) 관심상품추가 (7일) 관심상품추가당 비용 (7일) 관심상품추가율 (7일) 장바구니추가(1일) 장바구니추가당 비용(1일) 장바구니추가율(1일) 장바구니추가(7일) 장바구니추가당 비용(7일) 장바구니추가율(7일) 장바구니 열람당 비용 (1일) 장바구니 열람당 비용 (7일) 장바구니 열람률 (1일) 장바구니 열람률 (7일) 구매당 비용 (1일) 구매당 비용 (7일) 구매율 (1일) 구매율 (7일) 잠재 고객당 비용 (1일) 잠재 고객당 비용 (7일) 잠재 고객률 (1일) 잠재 고객률 (7일) 서비스 신청당 비용 (1일) 서비스 신청당 비용 (7일) 서비스 신청률 (1일) 서비스 신청률 (7일) 앱 설치당 비용 (1일) 앱 설치당 비용 (7일) 앱 설치율 (1일) 앱 설치율 (7일)	conv_cmpt_reg_1d conv_cmpt_reg_7d conv_view_cart_1d conv_view_cart_7d conv_purchase_1d conv_purchase_7d conv_purchase_p_1d conv_purchase_p_7d conv_participation_1d conv_participation_7d conv_signup_1d conv_signup_7d conv_app_install_1d conv_app_install_7d cost_per_conv_cmpt_reg_1d cost_per_conv_cmpt_reg_7d conv_cmpt_reg_1d_rate conv_cmpt_reg_7d_rate conv_add_to_wishlist_1d cost_per_conv_add_to_wishlist_1d conv_add_to_wishlist_1d_rate conv_add_to_wishlist_7d cost_per_conv_add_to_wishlist_7d conv_add_to_wishlist_7d_rate conv_add_to_cart_1d cost_per_conv_add_to_cart_1d conv_add_to_cart_1d_rate conv_add_to_cart_7d cost_per_conv_add_to_cart_7d conv_add_to_cart_7d_rate cost_per_conv_view_cart_1d cost_per_conv_view_cart_7d conv_view_cart_1d_rate conv_view_cart_7d_rate cost_per_conv_purchase_1d cost_per_conv_purchase_7d conv_purchase_1d_rate conv_purchase_7d_rate cost_per_conv_participation_1d cost_per_conv_participation_7d conv_participation_1d_rate conv_participation_7d_rate cost_per_conv_signup_1d cost_per_conv_signup_7d conv_signup_1d_rate conv_signup_7d_rate cost_per_conv_app_install_1d cost_per_conv_app_install_7d conv_app_install_1d_rate conv_app_install_7d_rate
MESSAGE_CLICK	메시지 클릭 지표 공유버튼 클릭수 이미지/동영상 클릭수 타이틀 클릭수 텍스트 클릭수 리스트1 클릭수 리스트2 클릭수 리스트3 클릭수 리스트4 클릭수 리스트5 클릭수 버튼1 클릭수 버튼2 클릭수 캐러셀 1 버튼1 클릭수 캐러셀 2 버튼1 클릭수 캐러셀 3 버튼1 클릭수 캐러셀 4 버튼1 클릭수 캐러셀 5 버튼1 클릭수 캐러셀 6 버튼1 클릭수 캐러셀 1 버튼2 클릭수 캐러셀 2 버튼2 클릭수 캐러셀 3 버튼2 클릭수 캐러셀 4 버튼2 클릭수 캐러셀 5 버튼2 클릭수 캐러셀 6 버튼2 클릭수 캐러셀 1 쿠폰 버튼 클릭수 캐러셀 2 쿠폰 버튼 클릭수 캐러셀 3 쿠폰 버튼 클릭수 캐러셀 4 쿠폰 버튼 클릭수 캐러셀 5 쿠폰 버튼 클릭수 캐러셀 6 쿠폰 버튼 클릭수 아이템1 클릭수 아이템2 클릭수 아이템3 클릭수 아이템4 클릭수 아이템5 클릭수 아이템6 클릭수 아이템7 클릭수 더보기 클릭수 쿠폰 버튼 클릭수 기타 클릭수	msg_click_share msg_click_media msg_click_title msg_click_text msg_click_list1 msg_click_list2 msg_click_list3 msg_click_list4 msg_click_list5 msg_click_button1 msg_click_button2 msg_click_carousel_button1 msg_click_carousel_button2 msg_click_carousel_button3 msg_click_carousel_button4 msg_click_carousel_button5 msg_click_carousel_button6 msg_click_carousel_share1 msg_click_carousel_share2 msg_click_carousel_share3 msg_click_carousel_share4 msg_click_carousel_share5 msg_click_carousel_share6 msg_click_carousel1_coupon msg_click_carousel2_coupon msg_click_carousel3_coupon msg_click_carousel4_coupon msg_click_carousel5_coupon msg_click_carousel6_coupon msg_click_catalog_item1 msg_click_catalog_item2 msg_click_catalog_item3 msg_click_catalog_item4 msg_click_catalog_item5 msg_click_catalog_item6 msg_click_catalog_item7 msg_click_carousel_more msg_click_coupon msg_click_others

예제

요청

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/reports" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "dimension": "MESSAGE_AD",
        "start": null,
        "end": null,
        "datePreset": "LAST_30DAY",
        "messageAdIds": ["msg-ad-1164368618878062593"],
        "metricsGroup": ["MESSAGE", "MESSAGE_ADDITION", "MESSAGE_CLICK", "PIXEL_SDK_CONVERSION"]
    }'

응답

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "code":200,
  "message":"Success",
  "data":[
    {
      "start":"2023-10-10",
      "end":"2023-10-10",
      "dimensions":{
        "message_ad_id":"msg-ad-1"
      },
      "metrics":{
        "msg_click":0,
        "msg_send":0,
        "cost":0.0,
        "msg_send_fail":0,
        "msg_open":1
      }
    }
  ]
}

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

메시지광고 관리

메시지광고 목록 조회

기본 정보

요청

헤더

쿼리 파라미터

본문

Filter

응답

본문

Content

SimpleMessage

SendingReservation

Targeting

Metrics

예제

요청

응답

메시지광고 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

메시지광고 삭제

기본 정보

요청

헤더

경로 변수

예제

요청

응답

메시지 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

메시지 복사

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

메시지광고 보고서 조회

기본 정보

요청

헤더

본문

Enum: Dimension

MetricsGroup

응답

본문

Data

Dimension

MetricsGroup

예제