사이드 메뉴
시작하기
로그인
커뮤니케이션
광고
메시지광고 관리
이 문서는 카카오모먼트 메시지광고의 메시지광고 관리 API 사용 방법을 안내합니다. 메시지광고 관리 API는 메시지광고 운영에 필요한 공통 관리 기능을 제공합니다.
카카오톡 채널x도달 캠페인 하위 메시지 소재는 광고 생성: 메시지 소재에서, 개인화 메시지 x 도달 캠페인 하위 메시지 소재는 광고 생성: 개인화 메시지 소재에서 확인할 수 있습니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | https://apis.moment.kakao.com/openapi/message/v2/message-ads | 비즈니스 토큰 |
카카오톡 채널 하위에 생성된 메시지광고 목록을 조회합니다.
비즈니스 토큰과 광고계정 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 |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| messageAdType | String | 메시지광고 타입BROADCAST: 메시지광고 | X |
| messageAdIds | String[] | 메시지광고 번호(최초 생성 시 부여된 메시지 식별용 번호) 목록 | X |
| statuses | String[] | 메시지 상태
| X |
| messageTypes | String[] | 메시지 유형
| 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 | 첫 페이지 여부, 아래 중 하나
|
| last | Boolean | 마지막 페이지 여부, 아래 중 하나
|
| size | Integer | 페이지 크기, 페이지당 메시지광고 수 |
| number | Integer | 페이지 번호 |
| numberOfElements | Integer | 현재 페이지에 포함된 메시지광고 수 |
| 이름 | 타입 | 설명 |
|---|---|---|
| messageAdId | String | 메시지광고 번호, 최초 생성 시 부여된 메시지 식별용 번호 |
| messageAdType | String | 메시지광고 타입BROADCAST: 메시지광고 |
| message | SimpleMessage | 메시지 간편 정보 |
| name | String | 메시지 이름(최대: 50자), 최초 생성 시 미입력한 경우 자동 생성 규칙이 적용된 값 |
| status | String | 메시지 상태, 아래 중 하나
|
| sendingReservation | SendingReservation | 메시지 발송예약 정보 |
| metrics | Metrics | 메시지 요약 보고서 |
| createdDate | String | 메시지광고 생성일, yyyy-MM-dd HH:mm:ss 형식 |
| lastModifiedDate | String | 메시지광고 마지막 수정일, yyyy-MM-dd HH:mm:ss 형식 |
| 이름 | 타입 | 설명 |
|---|---|---|
| type | String | 메시지 유형, 아래 중 하나
|
| mainImageUrl | String | 메시지 이미지 기본 텍스트(이미지 미등록)
기본 텍스트, 와이드 이미지, 와이드리스트
캐러셀 커머스, 캐러셀 피드
카탈로그
|
| mainTitle | String | 메시지 대표 텍스트 기본 텍스트, 와이드 이미지, 와이드리스트, 카탈로그
캐러셀 커머스, 캐러셀 피드
message.carousel.title 응답 |
| 이름 | 타입 | 설명 |
|---|---|---|
| deviceTypes | String[] | 디바이스 유형
|
| targeting | Targeting | 타게팅 정보 |
| price | Long | 발송 단가(단위: 원), 아래 중 하나
|
| contractCount | Integer | 구매발송수, 메시지광고 발송 예약 건 수 |
| totalBudget | Long | 구매 금액, 메시지광고 발송 예약 총 금액 |
| totalBudgetWithVAT | Long | VAT 포함 구매 금액, totalBudget에 VAT를 포함한 금액 |
| date | String | 발송 시작 일시, yyyy-MM-dd'T'HH:mm 형식 |
| 이름 | 타입 | 설명 |
|---|---|---|
| genderType | String | 성별 전체 선택 유형, 아래 중 하나
|
| genders | String[] | 성별M: 남자F: 여자 |
| ageType | String | 연령 전체 선택 유형, 아래 중 하나
|
| ages | String[] | 연령대15: 15~1920: 20~2425: 25~2930: 30~3435: 35~3940: 40~4445: 45~4950: 50~5455: 55~5960: 60~6465: 65~69 |
| locationType | String | 지역 선택 유형, 아래 중 하나
|
| depth1Locations | Location[] | 데모그래픽 > 행정구역 > 시/도 시/도 조회 참고 |
| depth2Locations | Depth2Location[] | 데모그래픽 > 행정구역 > 시/군/구 시/군/구 조회 참고 |
| depth3Locations | Depth3Location[] | 데모그래픽 > 행정구역 > 동/읍/면 동/읍/면 조회 참고 |
| 이름 | 타입 | 설명 |
|---|---|---|
| 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} | 비즈니스 토큰 |
개별 메시지광고의 상세 정보를 조회합니다.
메시지 내용, 발송 시간, 발송 대상 등을 확인할 수 있습니다.
비즈니스 토큰과 광고계정 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 | 메시지 상태, 아래 중 하나
|
| ageVerification | Boolean | 연령인증 필요 메시지 여부
|
| 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} | 비즈니스 토큰 |
메시지광고를 삭제합니다.
삭제한 메시지 정보는 더 이상 조회할 수 없고, 복구도 불가능합니다.
비즈니스 토큰과 광고계정 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 OKContent-Length: 0Content-Type: application/json;charset=UTF-8
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/message | 비즈니스 토큰 |
메시지 내용을 상세 조회합니다.
비즈니스 토큰과 광고계정 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 | 메시지 유형, 아래 중 하나
|
| title | String | 홍보 문구 |
| items | Item[] | 리스트 정보 |
| buttons | Button[] | 버튼 정보 |
| couponBook | CouponBook[] | 쿠폰 정보 |
| introCarousel | IntroCarousel | 인트로 정보 |
| carousels | Carousel[] | 캐러셀 정보 |
| ageVerification | Boolean | 연령인증 메시지 여부
|
| adFlag | Boolean | 광고성 메시지
|
| shareFlag | Boolean | 공유하기 사용 여부
중요: 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 | 비즈니스 토큰 |
카카오톡 채널에서 발송될 메시지광고의 메시지를 복사합니다.
비즈니스 토큰과 광고계정 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 | 메시지 유형, 아래 중 하나
|
| title | String | 홍보 문구 |
| items | Item[] | 아이템 정보 |
| buttons | Button[] | 버튼 정보 |
| couponBook | CouponBook[] | 쿠폰 정보 |
| introCarousel | IntroCarousel | 인트로 정보 |
| carousels | Carousel[] | 캐러셀 정보 |
| ageVerification | Boolean | 연령인증 메시지 여부
|
| adFlag | Boolean | 광고성 메시지
|
| shareFlag | Boolean | 공유하기 사용 여부
중요: 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 | 비즈니스 토큰 |
메시지에 대한 보고서를 조회합니다.
보고서 지표 그룹(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 | 보고서 조회기간, 아래 중 하나
| 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 |
| 값 | 설명 | 코드 |
|---|---|---|
| MESSAGE_AD | 메시지광고 | MESSAGE_AD |
| MESSAGE_TYPE | 메시지 유형
|
|
| DEVICE_TYPE | 디바이스
|
|
| HOUR | 시간대
|
|
| 값 | 설명 | 코드 |
|---|---|---|
| MESSAGE | 메시지 기본 지표
|
|
| MESSAGE_ADDITION | 메시지 추가 지표
|
|
| PIXEL_SDK_CONVERSION | 픽셀 & SDK 전환 지표
|
|
| MESSAGE_CLICK | 메시지 클릭 지표
|
|
| MESSAGE_CAROUSEL_VIEW | 메시지 노출 지표
|
|
| 이름 | 타입 | 설명 |
|---|---|---|
| code | Integer | 응답 코드 |
| message | String | 결과 안내 메시지 |
| data | Data | 각 보고서 상세 데이터 |
| 이름 | 타입 | 설명 |
|---|---|---|
| start | String | 시작일, YYYY-MM-DD 형식 |
| end | String | 종료일, YYYY-MM-DD 형식 |
| dimensions | Dimension | 보고서 기준과 값 |
| metrics | MetricsGroup | 보고서 지표와 값 |
| 값 | 설명 | 코드 |
|---|---|---|
| message_ad_id | 메시지광고 번호 최초 생성 시 부여된 메시지 식별용 번호 | - |
| MESSAGE_AD | 메시지광고 | MESSAGE_AD |
| MESSAGE_TYPE | 메시지 유형
|
|
| DEVICE_TYPE | 디바이스
|
|
| HOUR | 시간대
|
|
| 값 | 설명 | 코드 |
|---|---|---|
| MESSAGE | 메시지 기본 지표
|
|
| MESSAGE_ADDITION | 메시지 추가 지표
|
|
| PIXEL_SDK_CONVERSION | 픽셀 & SDK 전환 지표
|
|
| MESSAGE_CLICK | 메시지 클릭 지표
|
|
요청
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 | 비즈니스 토큰 |
메시지 소재에서 사용할 카카오톡 채널 동영상 목록을 조회합니다.
비즈니스 토큰을 헤더에 담아 GET으로 요청합니다. 인증 정보에 따라 결정된 카카오톡 채널의 동영상 목록이 조회됩니다. 동영상 목록은 페이지 단위로 조회 가능하며, page, size 파라미터로 조회 범위와 정렬 기준을 지정할 수 있습니다.
요청 성공 시 응답 본문에 JSON 객체로 채널 동영상 목록을 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| page | Integer | 조회할 페이지 번호, 0번부터 시작(기본값: 0) | X |
| size | Integer | 한 페이지에 조회할 동영상 개수(기본값: 20, 최대값: 1000) | X |
| 이름 | 타입 | 설명 |
|---|---|---|
| items | TalkChannelVideo[] | 채널 동영상 목록 |
| totalElements | Long | 조회 가능한 전체 동영상 수 |
| 이름 | 타입 | 설명 |
|---|---|---|
| url | String | 동영상 URL |
| title | String | 동영상 제목 |
| talkChannelProfileId | String | 카카오톡 채널 프로필 ID |
| vid | String | 동영상 VID |
| mediaId | Long | 동영상 미디어 ID |
| status | String | 동영상 상태 |
| duration | Integer | 동영상 재생 시간 |
| width | Integer | 동영상 가로 크기 |
| height | Integer | 동영상 세로 크기 |
| playCount | Long | 동영상 재생 수 |
| autoThumbnail | TalkChannelVideoThumbnail | 자동 생성 썸네일 정보 |
| uploadThumbnail | 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://sandbox-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","fileName": "thumb.jpg","width": 1920,"height": 1080,"fileSize": 102400,"mineType": "image/jpeg"},"uploadThumbnail": null}],"totalElements": 1}