> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifly.tech/llms.txt > Use this file to discover all available pages before exploring further. # 카카오 브랜드 메시지 자유형 발송 > 템플릿 없이 발송합니다. **응답과 발송 결과** * 한 요청에 포함된 모든 수신자에게 동일한 콘텐츠가 발송됩니다. * 이미지가 필요한 유형은 먼저 [브랜드 메시지 이미지 업로드](/api-reference/upload-kakao-brand-message-image)를 호출하고, 응답의 `data.images[].url`을 사용해야 합니다. * `PREMIUM_VIDEO`의 `videoUrl`에는 카카오 비즈메시지 동영상 업로드 API에서 등록·인코딩이 완료된 발송용 URL을 사용해야 합니다. 일반 동영상 URL이나 KakaoTV 페이지 URL을 직접 사용할 수 없습니다. 현재 노티플라이 공개 동영상 업로드 API는 제공되지 않으므로 사용이 필요한 경우 [contact@notifly.tech](mailto:contact@notifly.tech)으로 문의해주세요. * 자유형은 `M`, `N`, `I` 타깃을 지원합니다. `I+N`은 지원하지 않습니다. * HTTP API 발송은 카카오톡 발송 플랫폼이 `Notifly`인 경우만 지원합니다. `Notifly (Legacy)`는 사용할 수 없습니다. ## OpenAPI ````yaml /ko/api-reference/openapi.yaml post /messages/kakao-brand-message/freestyle openapi: 3.0.3 info: title: Notifly API version: 1.0.0 contact: email: contact@notifly.tech servers: - url: https://api.notifly.tech description: 노티플라이 API 서버입니다 security: [] paths: /messages/kakao-brand-message/freestyle: post: summary: send-kakao-brand-message-freestyle operationId: sendKakaoBrandMessageFreestyle requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequest' examples: image: summary: 이미지형 자유형 메시지 value: projectId: example_project_1234567890abcdef channelId: your-kakao-channel-id target: M chatBubbleType: IMAGE message: 새로운 라이브 상품이 등록되었습니다. attachment: image: imgUrl: https://mud-kage.kakao.com/example/image.jpg imgLink: https://example.com/products/123 recipientList: - recipientNo: '01012345678' carouselCommerce: summary: 캐러셀 커머스형 자유형 메시지 value: projectId: example_project_1234567890abcdef channelId: your-kakao-channel-id target: M chatBubbleType: CAROUSEL_COMMERCE carousel: list: - additionalContent: 오늘만 할인 attachment: image: imgUrl: https://mud-kage.kakao.com/example/product-1.jpg imgLink: https://example.com/products/1 commerce: title: 첫 번째 상품 regularPrice: 10000 discountPrice: 8000 discountRate: 20 button: - name: 구매하기 type: WL urlMobile: https://example.com/products/1 - attachment: image: imgUrl: https://mud-kage.kakao.com/example/product-2.jpg imgLink: https://example.com/products/2 commerce: title: 두 번째 상품 regularPrice: 20000 button: - name: 구매하기 type: WL urlMobile: https://example.com/products/2 recipientList: - recipientNo: '01012345678' responses: '200': description: 발송 요청이 큐에 접수되었습니다. 카카오의 최종 발송 성공을 의미하지 않습니다. content: application/json: schema: $ref: '#/components/schemas/KakaoBrandMessageFreestyleSuccessResponse' example: success: true '400': description: 요청 형식이 잘못되었거나 해당 `channelId`의 발신자 정보가 등록되지 않았습니다. content: application/json: schema: $ref: '#/components/schemas/KakaoBrandMessageFreestyleErrorResponse' example: success: false error: Sender info is not registered. '401': description: 인증 토큰이 없거나 유효하지 않습니다. content: application/json: schema: $ref: '#/components/schemas/KakaoBrandMessageFreestyleErrorResponse' example: success: false error: Invalid Authorization Token '413': description: 수신자가 1,000명을 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/KakaoBrandMessageFreestyleErrorResponse' example: success: false error: >- Payload Too Large. Can accept up to 1000 recipients per request. '500': description: 발신자 조회, 메시지 데이터 생성 또는 큐 접수 중 서버 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/KakaoBrandMessageFreestyleErrorResponse' example: success: false error: Internal Server Error security: - bearerAuth: [] components: schemas: KakaoBrandMessageFreestyleRequest: $ref: '#/components/schemas/KakaoBrandMessageFreestyleContent' KakaoBrandMessageFreestyleSuccessResponse: type: object required: - success properties: success: type: boolean enum: - true description: true이면 발송 요청이 큐에 접수된 것입니다. 카카오의 최종 발송 성공을 의미하지 않습니다. KakaoBrandMessageFreestyleErrorResponse: type: object required: - success - error properties: success: type: boolean enum: - false description: false이면 발송 요청이 거절되었거나 서버 오류가 발생한 것입니다. error: type: string description: 요청 거절 또는 서버 오류 사유입니다. KakaoBrandMessageFreestyleContent: oneOf: - title: 텍스트형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - message properties: chatBubbleType: type: string description: 메시지 타입 enum: - TEXT message: type: string maxLength: 1300 description: | 사용자에게 전달될 메시지 - 줄바꿈: 최대 99개 - URL 형식 입력 가능 attachment: type: object description: 메시지에 첨부할 내용 properties: button: type: array maxItems: 5 description: | 버튼 목록 Coupon을 적용할 경우 최대 4개 items: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleTextImageButton coupon: $ref: '#/components/schemas/KakaoBrandMessageFreestyleCoupon' - title: 이미지형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - message - attachment properties: chatBubbleType: type: string description: 메시지 타입 enum: - IMAGE message: type: string maxLength: 1300 description: | 사용자에게 전달될 메시지 - 줄바꿈: 최대 99개 - URL 형식 입력 가능 attachment: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleImageAttachment - title: 와이드 이미지형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - message - attachment properties: chatBubbleType: type: string description: 메시지 타입 enum: - WIDE message: type: string maxLength: 76 description: | 사용자에게 전달될 메시지 - 줄바꿈: 최대 5개 attachment: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleWideAttachment - title: 와이드 아이템리스트형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - header - attachment properties: chatBubbleType: type: string description: 메시지 타입 enum: - WIDE_ITEM_LIST header: type: string maxLength: 20 description: | `header` 필드 필수 - 줄바꿈: 불가 attachment: type: object description: 메시지에 첨부할 내용 required: - item properties: item: type: object description: 와이드 리스트 요소 required: - list properties: list: type: array minItems: 3 maxItems: 5 description: | 와이드 리스트 - 1번째 아이템은 `title` 필수 아님 - 2\~5번째 아이템은 `title` 필수 입력 items: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleWideItem button: type: array maxItems: 2 description: 버튼 목록 items: $ref: '#/components/schemas/KakaoBrandMessageFreestyleButton' coupon: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleWideOrVideoCoupon - title: 캐러셀 피드형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - carousel properties: chatBubbleType: type: string description: 메시지 타입 enum: - CAROUSEL_FEED carousel: type: object description: 캐러셀 요소 required: - list properties: list: type: array minItems: 2 maxItems: 6 description: 캐러셀 리스트 items: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleCarouselFeedItem tail: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleCarouselTail - title: 프리미엄 동영상형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - attachment properties: chatBubbleType: type: string description: 메시지 타입 enum: - PREMIUM_VIDEO header: type: string maxLength: 20 description: | `header` 필드 선택 - 줄바꿈: 불가 message: type: string maxLength: 76 description: | 사용자에게 전달될 메시지 - 줄바꿈: 최대 5개 attachment: type: object description: 메시지에 첨부할 내용 required: - video properties: video: type: object description: 동영상 요소 required: - videoUrl properties: videoUrl: type: string format: uri maxLength: 500 description: 동영상 업로드 API에 업로드된 동영상의 `videoUrl` thumbnailUrl: type: string format: uri maxLength: 500 description: > [이미지 업로드 API](/api-reference/upload-kakao-brand-message-image)로 등록한 동영상 썸네일용 이미지 URL (기본값: 동영상 기본 썸네일 이미지) - `thumbnailUrl` 필드 필수 - `videoUrl`이 비공개 동영상인 경우 button: type: array maxItems: 1 description: 버튼 목록 items: $ref: '#/components/schemas/KakaoBrandMessageFreestyleButton' coupon: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleWideOrVideoCoupon - title: 커머스형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - attachment properties: chatBubbleType: type: string description: 메시지 타입 enum: - COMMERCE additionalContent: type: string maxLength: 34 description: | 부가 정보 - 줄바꿈: 최대 1개 attachment: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleCommerceAttachment - title: 캐러셀 커머스형 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleRequestCommon' - type: object required: - chatBubbleType - carousel properties: chatBubbleType: type: string description: 메시지 타입 enum: - CAROUSEL_COMMERCE carousel: type: object description: 캐러셀 요소 required: - list properties: head: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleCarouselHead list: type: array minItems: 1 maxItems: 6 description: | 캐러셀 리스트 - `carousel.head`를 사용하지 않으면 최소 2개 items: type: object required: - attachment properties: additionalContent: type: string maxLength: 34 description: | 캐러셀 리스트 부가 정보 - 줄바꿈: 최대 1개 attachment: description: 캐러셀 아이템 이미지, 버튼 정보 allOf: - $ref: >- #/components/schemas/KakaoBrandMessageFreestyleCommerceAttachment tail: $ref: >- #/components/schemas/KakaoBrandMessageFreestyleCarouselTail discriminator: propertyName: chatBubbleType KakaoBrandMessageFreestyleRequestCommon: type: object required: - projectId - channelId - target - recipientList properties: projectId: type: string description: 노티플라이 설정 페이지에서 확인할 수 있는 프로젝트 ID입니다. channelId: type: string description: 프로젝트에 카카오 비즈메시지 발신자로 등록된 카카오 채널 ID입니다. target: type: string enum: - M - 'N' - I description: >- 발송 타깃입니다. `M`: 마케팅 수신 동의 회원, `N`: 마케팅 수신 동의 회원 중 채널 비친구, `I`: 채널 친구. 자유형은 `I+N`을 지원하지 않습니다. adult: type: boolean default: false description: 성인용 메시지 여부입니다. recipientList: type: array minItems: 1 maxItems: 1000 description: 수신자 목록입니다. 같은 요청의 모든 수신자에게 동일한 메시지 콘텐츠가 발송됩니다. items: $ref: '#/components/schemas/KakaoBrandMessageFreestyleRecipient' KakaoBrandMessageFreestyleTextImageButton: description: 브랜드 메시지 버튼 타입별 사용 가능한 버튼 파라미터와 필수 파라미터입니다. allOf: - type: object required: - name properties: name: type: string maxLength: 14 description: 버튼 제목 - $ref: '#/components/schemas/KakaoBrandMessageFreestyleButtonCommon' KakaoBrandMessageFreestyleCoupon: type: object description: > 쿠폰 요소 메세지 최하단 노출 - 채널 쿠폰 URL(포맷: `alimtalk=coupon://`) 사용시 `schemeAndroid`, `schemeIos` 중 하나 필수 입력 - 채널 쿠폰 URL이 아닌 기본 쿠폰 사용시 `urlMobile` 필수 입력 required: - title - description allOf: - type: object properties: title: $ref: '#/components/schemas/KakaoBrandMessageFreestyleCouponTitle' description: type: string maxLength: 12 description: 쿠폰 설명 - $ref: '#/components/schemas/KakaoBrandMessageFreestyleCouponLinks' KakaoBrandMessageFreestyleImageAttachment: type: object description: 메시지에 첨부할 내용 required: - image properties: image: $ref: '#/components/schemas/KakaoBrandMessageFreestyleImage' button: type: array maxItems: 5 description: | 버튼 목록 Coupon을 적용할 경우 최대 4개 items: $ref: '#/components/schemas/KakaoBrandMessageFreestyleTextImageButton' coupon: $ref: '#/components/schemas/KakaoBrandMessageFreestyleCoupon' KakaoBrandMessageFreestyleWideAttachment: type: object description: 메시지에 첨부할 내용 required: - image properties: image: $ref: '#/components/schemas/KakaoBrandMessageFreestyleImage' button: type: array maxItems: 2 description: 버튼 목록 items: $ref: '#/components/schemas/KakaoBrandMessageFreestyleButton' coupon: $ref: '#/components/schemas/KakaoBrandMessageFreestyleWideOrVideoCoupon' KakaoBrandMessageFreestyleWideItem: type: object required: - imgUrl - urlMobile properties: title: type: string maxLength: 30 description: | 아이템 제목 - 1번째 아이템 - 최대 25자 (줄바꿈: 최대 1개) - 2\~5번째 아이템 - 최대 30자 (줄바꿈: 최대 1개) imgUrl: type: string format: uri description: >- [이미지 업로드 API](/api-reference/upload-kakao-brand-message-image)로 등록한 아이템 이미지 URL urlMobile: type: string format: uri maxLength: 1000 description: MOBILE 환경에서 클릭 시 이동할 URL urlPc: type: string format: uri maxLength: 1000 description: PC 환경에서 클릭 시 이동할 URL schemeAndroid: type: string maxLength: 1000 description: MOBILE Android 환경에서 클릭 시 실행할 application custom scheme schemeIos: type: string maxLength: 1000 description: MOBILE iOS 환경에서 클릭 시 실행할 application custom scheme KakaoBrandMessageFreestyleButton: description: 브랜드 메시지 버튼 타입별 사용 가능한 버튼 파라미터와 필수 파라미터입니다. allOf: - type: object required: - name properties: name: type: string maxLength: 8 description: 버튼 제목 - $ref: '#/components/schemas/KakaoBrandMessageFreestyleButtonCommon' KakaoBrandMessageFreestyleWideOrVideoCoupon: type: object description: > 쿠폰 요소 메세지 최하단 노출 - 채널 쿠폰 URL(포맷: `alimtalk=coupon://`) 사용시 `schemeAndroid`, `schemeIos` 중 하나 필수 입력 - 채널 쿠폰 URL이 아닌 기본 쿠폰 사용시 `urlMobile` 필수 입력 required: - title - description allOf: - type: object properties: title: $ref: '#/components/schemas/KakaoBrandMessageFreestyleCouponTitle' description: type: string maxLength: 18 description: 쿠폰 설명 - $ref: '#/components/schemas/KakaoBrandMessageFreestyleCouponLinks' KakaoBrandMessageFreestyleCarouselFeedItem: type: object required: - header - message - attachment properties: header: type: string maxLength: 20 description: | 캐러셀 리스트 헤더 - 줄바꿈: 불가 message: type: string maxLength: 180 description: | 캐러셀 리스트 메시지 - 줄바꿈: 최대 10개 attachment: type: object description: 캐러셀 아이템 이미지, 버튼 정보 required: - image - button properties: image: description: 캐러셀 이미지 allOf: - $ref: '#/components/schemas/KakaoBrandMessageFreestyleImage' button: type: array minItems: 1 maxItems: 2 description: 캐러셀 리스트 버튼 목록 items: $ref: '#/components/schemas/KakaoBrandMessageFreestyleButton' coupon: $ref: '#/components/schemas/KakaoBrandMessageFreestyleCoupon' KakaoBrandMessageFreestyleCarouselTail: type: object description: 더보기 버튼 required: - urlMobile properties: urlMobile: type: string format: uri maxLength: 1000 description: MOBILE 환경에서 클릭 시 이동할 URL urlPc: type: string format: uri maxLength: 1000 description: PC 환경에서 클릭 시 이동할 URL schemeAndroid: type: string maxLength: 1000 description: MOBILE Android 환경에서 클릭 시 실행할 application custom scheme schemeIos: type: string maxLength: 1000 description: MOBILE iOS 환경에서 클릭 시 실행할 application custom scheme KakaoBrandMessageFreestyleCommerceAttachment: type: object description: 메시지에 첨부할 내용 required: - image - commerce - button properties: image: $ref: '#/components/schemas/KakaoBrandMessageFreestyleImage' commerce: $ref: '#/components/schemas/KakaoBrandMessageFreestyleCommerce' button: type: array minItems: 1 maxItems: 2 description: 버튼 목록 items: $ref: '#/components/schemas/KakaoBrandMessageFreestyleButton' coupon: $ref: '#/components/schemas/KakaoBrandMessageFreestyleCoupon' KakaoBrandMessageFreestyleCarouselHead: type: object description: 캐러셀 인트로 required: - header - content - imageUrl properties: header: type: string maxLength: 20 description: | 캐러셀 인트로 헤더 - 줄바꿈: 불가 content: type: string maxLength: 50 description: | 캐러셀 인트로 내용 - 줄바꿈: 최대 2개 imageUrl: type: string format: uri description: >- [이미지 업로드 API](/api-reference/upload-kakao-brand-message-image)로 등록한 캐러셀 인트로 이미지 URL urlMobile: type: string format: uri maxLength: 1000 description: > MOBILE 환경에서 클릭 시 이동할 URL - `urlMobile` 필수 - `urlMobile`, `urlPc`, `schemeAndroid`, `schemeIos` 중 하나라도 입력하는 경우 urlPc: type: string format: uri maxLength: 1000 description: PC 환경에서 클릭 시 이동할 URL schemeAndroid: type: string maxLength: 1000 description: MOBILE Android 환경에서 클릭 시 실행할 application custom scheme schemeIos: type: string maxLength: 1000 description: MOBILE iOS 환경에서 클릭 시 실행할 application custom scheme KakaoBrandMessageFreestyleRecipient: type: object required: - recipientNo properties: recipientNo: type: string description: 수신자 휴대폰 번호입니다. KakaoBrandMessageFreestyleButtonCommon: type: object required: - type properties: type: type: string enum: - WL - AL - BK - MD - AC - BC - BT - BF description: | 버튼 타입. 버튼 타입별 필수 파라미터를 모두 입력해야 메시지 발송 가능 - `AC` - 버튼 클릭 시 카카오톡 채널 추가 - 강조형 버튼(노란색)으로 표기되며, 버튼이 여러개일 경우 지정된 위치에 사용해야함 - `TEXT`, `IMAGE` - 첫번째 버튼 (최상단) - 그 외 - 두번째 버튼 (우측) - `name`은 `채널 추가`로 고정 - 캐러셀형은 전체 캐러셀 통틀어 1개만 사용가능 - 타겟팅 `M`, `N`만 사용 가능 - `WL` - 지정한 웹 링크로 이동 - `urlMobile` 필수 - `AL` - 지정한 앱 스킴 또는 웹 링크로 이동 - `schemeAndroid`, `schemeIos`, `urlMobile` 중 2가지 이상 필수 - `BK` - 해당 버튼 텍스트 발송 - `MD` - 해당 버튼 텍스트 + 메시지 본문 발송 - `BC` - 상담톡을 이용하는 카카오톡 채널만 이용 가능 - `BT` - 카카오 I 오픈빌더의 챗봇을 사용하는 카카오톡 채널만 이용 가능 - `BF` - 카카오 비즈니스폼을 실행 - 강조형 버튼(노란색)으로 표기되며 지정된 위치에 사용해야함 - `AC` 버튼이 없으면 - `TEXT`, `IMAGE` - 첫번째 버튼 (최상단) - 그 외 - 두번째 버튼 (우측) - `AC` 버튼이 있으면 - `TEXT`, `IMAGE` - 두번째 버튼 (위에서 두번째) - 그 외 - 첫번째 버튼 (좌측) - `name`은 다음 중 사용 가능 - `톡에서 예약하기` - `톡에서 설문하기` - `톡에서 응모하기` - `bizFormKey` 필수 schemeAndroid: type: string maxLength: 1000 description: MOBILE Android 환경에서 클릭 시 실행할 application custom scheme schemeIos: type: string maxLength: 1000 description: MOBILE iOS 환경에서 클릭 시 실행할 application custom scheme urlMobile: type: string format: uri maxLength: 1000 description: MOBILE 환경에서 클릭 시 이동할 URL urlPc: type: string format: uri maxLength: 1000 description: PC 환경에서 클릭 시 이동할 URL chatExtra: type: string description: 상담톡<->카카오톡 챗봇 전환 시 전달할 메타정보 chatEvent: type: string description: 카카오톡 챗봇 전환 시 연결할 카카오톡 챗봇 이벤트명 bizFormKey: type: string description: 비즈니스폼 업로드를 통해 발급받은 `bizFormKey` KakaoBrandMessageFreestyleCouponTitle: type: string description: | 쿠폰 제목 사용 가능한 쿠폰 제목 - `${숫자}원 할인 쿠폰` (숫자: 1\~99,999,999) - `${숫자}% 할인 쿠폰` (숫자: 1\~100) - `배송비 할인 쿠폰` - `${7자 이내} 무료 쿠폰` - `${7자 이내} UP 쿠폰` KakaoBrandMessageFreestyleCouponLinks: type: object properties: urlMobile: type: string format: uri maxLength: 1000 description: MOBILE 환경에서 클릭 시 이동할 URL urlPc: type: string format: uri maxLength: 1000 description: PC 환경에서 클릭 시 이동할 URL schemeAndroid: type: string maxLength: 1000 description: MOBILE Android 환경에서 클릭 시 실행할 application custom scheme schemeIos: type: string maxLength: 1000 description: MOBILE iOS 환경에서 클릭 시 실행할 application custom scheme KakaoBrandMessageFreestyleImage: type: object description: 이미지 요소 required: - imgUrl properties: imgUrl: type: string format: uri description: > [이미지 업로드 API](/api-reference/upload-kakao-brand-message-image)로 등록한 이미지 URL - `CAROUSEL_COMMERCE`는 전체 이미지 비율이 동일해야 함 imgLink: type: string format: uri maxLength: 1000 description: 이미지 클릭시 이동할 URL. 미설정시 카카오톡 내 이미지 뷰어 사용 KakaoBrandMessageFreestyleCommerce: type: object description: 커머스 요소 required: - title - regularPrice properties: title: type: string maxLength: 30 description: | 상품 제목 - 줄바꿈: 불가 regularPrice: type: integer minimum: 0 maximum: 99999999 description: 정상 가격 discountPrice: type: integer minimum: 0 maximum: 99999999 description: 할인 후 가격 discountRate: type: integer minimum: 1 maximum: 100 description: | 할인율 할인 가격 존재시 `discountRate`, `discountFixed` 중 하나는 필수 discountFixed: type: integer minimum: 0 maximum: 999999 description: | 정액 할인 가격 할인 가격 존재시 `discountRate`, `discountFixed` 중 하나는 필수 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: POST /authenticate로 발급받은 인증 토큰을 Bearer 형식으로 전달합니다. ````