카카오모먼트

메시지광고 관리

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

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

메시지광고 목록 조회

기본 정보

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

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 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

쿼리 파라미터

이름	타입	설명	필수
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`(메시지광고)로 고정 참고: 응답에 `MULTI_BROADCAST`(최적화 메시지광고) 포함	X
messageAdIds	`String[]`	메시지광고 번호(최초 생성 시 부여된 메시지 식별용 번호) 목록	X
statuses	`String[]`	메시지 상태 `DRAFT`: 임시저장 `READY`: 발송전 `SENDING`: 발송중 `PAUSE`: 발송중지 `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`: 카탈로그 `SPOTLIGHT_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	`Enum`	메시지광고 타입 `BROADCAST`: 일반 메시지광고 `MULTI_BROADCAST`: 최적화 메시지광고
message	`SimpleMessage`	메시지 간편 정보 제공 조건: `messageAdType`이 `BROADCAST`인 경우
messages	`SimpleMessage[]`	최적화 메시지광고의 소재별 간편 정보 목록, 소재 순서대로 제공 제공 조건: `messageAdType`이 `MULTI_BROADCAST`인 경우
name	`String`	메시지 이름(최대: 150자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값
status	`Enum`	메시지 상태 `DRAFT`: 임시저장 `READY`: 발송전 `SENDING`: 발송중 `PAUSE`: 발송중지 `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	`Enum`	메시지 유형 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스형 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드형 `PREMIUM_VIDEO_MESSAGE`: 프리미엄 동영상 `CATALOG_MESSAGE`: 카탈로그 `SPOTLIGHT_MESSAGE`: 스포트라이트
mainImageUrl	`String`	메시지 대표 이미지 기본 텍스트, 와이드 이미지, 와이드 리스트, 카탈로그, 스포트라이트: 첫 번째 `message.items`의 `imageUrl` 응답 아이템에 이미지가 없는 경우: 첫 번째 아이템의 `video.thumbnailUrl` 응답, 이미지와 동영상이 없는 경우 `null` 응답 캐러셀 커머스, 인트로 캐러셀의 이미지가 있는 경우: `message.introCarousel.imageUrl` 응답 캐러셀 커머스, 캐러셀 피드: 첫 번째 `message.carousels`의 `imageUrl` 응답
mainTitle	`String`	메시지 대표 텍스트 기본 텍스트, 와이드 이미지, 와이드 리스트, 프리미엄 동영상, 카탈로그, 스포트라이트: `message.messageTitle` 응답, 값이 없는 경우 `message.description` 응답 캐러셀 커머스, 인트로 캐러셀의 제목이 있는 경우: `message.introCarousel.messageTitle` 응답 캐러셀 커머스, 캐러셀 피드: 첫 번째 `message.carousels`의 `messageTitle` 응답

SendingReservation

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

Targeting

이름	타입	설명
type	`Enum`	타게팅 유형 `WHOLE`: 전체 친구 `DIRECT`: 직접 설정 `SMART`: 추천 친구 참고: 최적화 메시지광고를 조회한 경우에만 제공하는 값 `OPTIMIZATION_WHOLE`: 전체 친구 최적화 `OPTIMIZATION_DIRECT`: 직접 설정 최적화
optimizationTarget	`TargetingOptimization`	최적화 설정 정보 제공 조건: 최적화 메시지광고를 조회한 경우
devices	`Enum: DeviceType[]`	디바이스 유형 `ANDROID`: 안드로이드 `IOS`: iOS
businessTypes	`UfoBusinessType[]`	업종 타게팅 정보
interests	`UfoInterest[]`	관심사 타게팅 정보
demographics	`Demographics`	성별, 연령, 지역 타게팅 정보
friendPeriod	`FriendPeriod`	카카오톡 채널 친구 추가 기간 타게팅 정보
customs	`CustomTargeting[]`	맞춤타겟 정보

Demographics

이름	타입	설명
genders	`String[]`	성별 `M`: 남자 `F`: 여자
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 `70`: 70 이상
locationType	`Enum`	지역 선택 유형 `ALL`: 전체(국내, 해외) `DOMESTIC`: 국내만 `AREA`: 지역 선택
depth1Locations	`String[]`	시/도 지역 값 목록
depth2Locations	`String[]`	시/군/구 지역 값 목록
depth3Locations	`String[]`	동/읍/면 지역 값 목록

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": "BROADCAST",
        "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": "BROADCAST",
      "name": "메시지광고_테스트_와이드_이미지",
      "status": "READY",
      "sendingReservation": {
        "targeting": {
          "type": "DIRECT",
          "devices": [],
          "businessTypes": [],
          "interests": [],
          "demographics": {
            "genders": [],
            "ages": [],
            "locationType": "ALL",
            "depth1Locations": [],
            "depth2Locations": [],
            "depth3Locations": []
          },
          "customs": []
        },
        "date": "2024-01-15 16:37"
      },
      "metrics": null,
      "createdDate": "2024-01-15 16:37:32",
      "lastModifiedDate": "2024-01-15 16:37:32",
      "message": {
        "type": "WIDE_MESSAGE",
        "mainTitle": "홍보문구",
        "mainImageUrl": "https://t1.kakaocdn.net/b2/creative/56493/72750c9573241f3409d6f8e44cd66ac8.jpg"
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "empty": false,
      "sorted": true,
      "unsorted": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "size": 10,
  "number": 0,
  "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
  },
  "numberOfElements": 1,
  "empty": false
}

메시지광고 조회

기본 정보

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

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 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`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
messageAdType	`Enum`	메시지광고 타입 `BROADCAST`: 일반 메시지광고 `MULTI_BROADCAST`: 최적화 메시지광고
name	`String`	메시지 이름(최대: 150자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값
message	`ResponseMessage` 또는 `ResponseMultiMessage`	메시지 정보 일반 메시지광고: `ResponseMessage` 형식 최적화 메시지광고: `ResponseMultiMessage` 형식, 소재 정보는 `message.messages`에 포함 참고: `messageAdId`, `name`은 생략, 광고의 연령인증 여부는 최상위 `ageVerification`으로 확인 가능
sendingReservation	`SendingReservation`	메시지 발송예약 정보
status	`Enum`	메시지 상태 `DRAFT`: 임시저장 `READY`: 발송전 `SENDING`: 발송중 `PAUSE`: 발송중지 `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",
    "items": [
      {
        "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/72750c9573241f3409d6f8e44cd66ac8.jpg",
        "landing": {
          "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,
    "description": "홍보문구"
  },
  "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 등록 비즈니스 동의항목 설정	에러 코드 용어집

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

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

요청

헤더

이름	설명	필수
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 -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 등록 비즈니스 동의항목 설정	에러 코드 용어집

메시지 상세 정보를 반환합니다.

일반 메시지광고는 응답 본문 형식으로, 최적화 메시지광고는 ResponseMultiMessage 형식으로 반환합니다.

요청

헤더

이름	설명	필수
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`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
name	`String`	메시지 이름(최대: 150자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값
type	`Enum`	메시지 유형 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스형 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드형 `PREMIUM_VIDEO_MESSAGE`: 프리미엄 동영상 `CATALOG_MESSAGE`: 카탈로그 `SPOTLIGHT_MESSAGE`: 스포트라이트
messageTitle	`String`	메시지 제목 제공 조건: 해당 메시지 유형에서 제목을 사용하는 경우
description	`String`	홍보 문구 제공 조건: 해당 메시지 유형에서 홍보 문구를 사용하는 경우
items	`Item[]`	리스트 정보
buttons	`Button[]`	버튼 정보
couponBook	`CouponBook`	쿠폰 정보
introCarousel	`IntroCarousel`	인트로 정보
carousels	`Carousel[]`	캐러셀 정보
moreButton	`Landing`	캐러셀 더보기 랜딩 정보 제공 조건: 값이 있는 경우
buttonTitle	`String`	스포트라이트 메시지 버튼 이름
landingUrl	`String`	스포트라이트 메시지 랜딩 URL
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",
  "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,
  "description": "홍보문구"
}

메시지 복사

기본 정보

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

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

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

일반 메시지광고는 응답 본문 형식으로, 최적화 메시지광고는 ResponseMultiMessage 형식으로 반환합니다.

요청

헤더

이름	설명	필수
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`	메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호
name	`String`	메시지 이름(최대: 150자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값
type	`Enum`	메시지 유형 `BASIC_TEXT_MESSAGE`: 기본 텍스트 `WIDE_MESSAGE`: 와이드 이미지 `WIDE_LIST_MESSAGE`: 와이드 리스트 `CAROUSEL_COMMERCE_MESSAGE`: 캐러셀 커머스형 `CAROUSEL_FEED_MESSAGE`: 캐러셀 피드형 `PREMIUM_VIDEO_MESSAGE`: 프리미엄 동영상 `CATALOG_MESSAGE`: 카탈로그 `SPOTLIGHT_MESSAGE`: 스포트라이트
messageTitle	`String`	메시지 제목 제공 조건: 해당 메시지 유형에서 제목을 사용하는 경우
description	`String`	홍보 문구 제공 조건: 해당 메시지 유형에서 홍보 문구를 사용하는 경우
items	`Item[]`	아이템 정보
buttons	`Button[]`	버튼 정보
couponBook	`CouponBook`	쿠폰 정보
introCarousel	`IntroCarousel`	인트로 정보
carousels	`Carousel[]`	캐러셀 정보
moreButton	`Landing`	캐러셀 더보기 랜딩 정보 제공 조건: 값이 있는 경우
buttonTitle	`String`	스포트라이트 메시지 버튼 이름
landingUrl	`String`	스포트라이트 메시지 랜딩 URL
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",
  "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,
  "description": "홍보문구 변경"
}

메시지광고 보고서 조회

기본 정보

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

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

메시지에 대한 보고서를 반환합니다.

보고서 조회 조건

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

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

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

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

요청

헤더

이름	설명	필수
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

본문

이름	타입	설명	필수
messageAdIds	`String[]`	메시지광고 번호(최초 생성 시 부여된 메시지 식별용 번호) 목록(최대: 100개)	X
datePreset	`Enum: DatePreset`	보고서 조회기간(기본값: `TODAY`)	X
start	`String`	보고서 조회기간 시작일, `YYYY-MM-DD` 형식 시작일은 조회 당일까지 설정 가능 중요: `end` 포함 시 필수 참고: `start`, `end`를 모두 생략하면 `datePreset` 기준으로 조회	X
end	`String`	보고서 조회기간 종료일, `YYYY-MM-DD` 형식 종료일은 시작일부터 조회 당일까지 설정 가능 중요: `start` 포함 시 필수	X
dimension	`Enum: Dimension`	보고서 조회 기준, 보고서 조회 시 데이터가 그룹화될 기준	O
metricsGroup	`Enum: MetricsGroup[]`	보고서 지표 그룹	O

Enum: Dimension

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

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

응답

본문

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

Data

이름	타입	설명
start	`String`	시작일, `YYYY-MM-DD` 형식
end	`String`	종료일, `YYYY-MM-DD` 형식
dimensions	`JSON`	보고서 기준과 값 참고: 조회 기준에 따라 포함되는 키와 값은 Dimension 참고
metrics	`JSON`	보고서 지표와 값 참고: 지표 코드는 Enum: MetricsGroup 참고

Dimension

이름	설명	값
message_ad_id	메시지광고 번호 최초 생성 시 부여된 메시지 식별용 번호	실제 메시지광고 번호(`messageAdId`)
message_type	메시지 유형 기본 텍스트 와이드 리스트 와이드 이미지 캐러셀 커머스 캐러셀 피드 카탈로그 스포트라이트	BASIC_TEXT_MESSAGE WIDE_LIST_MESSAGE WIDE_MESSAGE CAROUSEL_COMMERCE_MESSAGE CAROUSEL_FEED_MESSAGE CATALOG_MESSAGE SPOTLIGHT_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

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

예제

요청

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

채널 영상 목록 조회

기본 정보

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

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

메시지 소재에서 사용할 카카오톡 채널 동영상 목록을 반환합니다.

인증 정보에 따라 결정된 카카오톡 채널의 동영상 목록이 반환됩니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O

쿼리 파라미터

이름	타입	설명	필수
page	`Integer`	조회할 페이지 번호, 0번부터 시작(기본값: 0)	X
size	`Integer`	한 페이지에 조회할 동영상 개수(기본값: 20, 최대: 1000)	X

응답

본문

이름	타입	설명
items	`TalkChannelVideo[]`	채널 동영상 목록
totalElements	`Long`	조회 가능한 전체 동영상 수

TalkChannelVideo

이름	타입	설명
url	`String`	동영상 URL
title	`String`	동영상 제목
talkChannelProfileId	`String`	카카오톡 채널 프로필 ID
vid	`String`	동영상 VID
mediaId	`Long`	동영상 미디어 ID
status	`String`	동영상 상태
duration	`Integer`	동영상 재생 시간
width	`Integer`	동영상 가로 크기
height	`Integer`	동영상 세로 크기
playCount	`Integer`	동영상 재생 수
autoThumbnail	`TalkChannelVideoThumbnail`	자동 생성 썸네일 정보
uploadThumbnail	`TalkChannelVideoThumbnail`	사용자 업로드 썸네일 정보

TalkChannelVideoThumbnail

이름	타입	설명
url	`String`	썸네일 URL
fileName	`String`	썸네일 파일명
width	`Integer`	썸네일 가로 크기
height	`Integer`	썸네일 세로 크기
fileSize	`Long`	썸네일 파일 크기
mineType	`String`	썸네일 MIME 타입

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/talk-channel-videos?page=0&size=20" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

응답

// HTTP/1.1 200 OK
// Content-Type: application/json;charset=UTF-8
{
  "items": [
    {
      "url": "https://pf.kakao.com/_Xxju/vod/svbjfjfy6nip184ci0zq1maf3",
      "title": "테스트 영상",
      "talkChannelProfileId": "_Xxju",
      "vid": "svbjfjfy6nip184ci0zq1maf3",
      "mediaId": 408,
      "status": "PUBLIC",
      "duration": 15,
      "width": 1920,
      "height": 1080,
      "playCount": 0,
      "autoThumbnail": {
        "url": "https://thumb.kakaocdn.net/dna/kamp-sbox/.../thumb.jpg",
        "width": 0,
        "height": 0,
        "fileSize": 0
      }
    }
  ],
  "totalElements": 1
}

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

메시지광고 관리

메시지광고 목록 조회

기본 정보

요청

헤더

쿼리 파라미터

본문

Filter

응답

본문

Content

SimpleMessage

SendingReservation

Targeting

Demographics

Metrics

예제

요청

응답

메시지광고 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

메시지광고 삭제

기본 정보

요청

헤더

경로 변수

응답

예제

요청

응답

메시지 조회

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

메시지 복사

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

메시지광고 보고서 조회

기본 정보

보고서 조회 조건

요청

헤더

본문

Enum: Dimension

Enum: MetricsGroup

응답

본문

Data

Dimension