메시지 발송

POST

하나 이상의 메시지를 발송하는 API입니다. 만 건을 초과하는 메시지 발송이 필요한 경우 그룹 메시지 API를 사용하는 것을 권장합니다.

발신번호는 사전 등록 필수 → 발신번호 관리
발송 내역 확인 → 문자발송 내역
데이터 보관기간: 6개월 (생성일 기준)
발송할 수 있는 메시지가 없을 경우 자세한 에러 내역을 결과로 반환
6개월이 지난 내역은 조회 불가능

메시지 타입별 비교

구분	내용 길이 제한	필수 필드	선택 필드	주요 특징	autoTypeDetect 조건
SMS (단문)	90 byte (한글 45자)	messages.from messages.to messages.text	없음	일반 문자 메시지	text 필드가 90byte 이하일 경우
LMS (장문)	2,000 byte (한글 1,000자)	messages.from messages.to messages.text	messages.subject	장문 문자 메시지 (수신자 데이터 통신 필요)	text 필드가 90byte를 초과하거나 subject 필드가 있을 경우
MMS (사진 문자)	2,000 byte (한글 1,000자)	messages.from messages.to messages.text messages.imageId	messages.subject	이미지 첨부 가능 (수신자 데이터 통신 필요) 이미지: JPG, 최대 200KB	imageId 필드가 있을 경우
카카오 알림톡 (ATA)	한글 1,000자 (변수 치환 후 기준)	messages.to kakaoOptions.pfId kakaoOptions.templateId	from text subject [kakaoOptions] disableSms title buttons variables replacements	사전 등록된 템플릿 사용 변수 치환 가능 실패 시 문자 대체 발송 가능	해당 없음
카카오 브랜드 메시지 자유형 (BMS_FREE), (친구톡, 친구톡 이미지 대체)	타입별 상이 - TEXT: 1,300자 / 줄바꿈 99개 - IMAGE: 1,300자 / 줄바꿈 99개 - WIDE: 76자 / 줄바꿈 1개 - PREMIUM_VIDEO: 76자 / 줄바꿈 5개	messages.to kakaoOptions.pfId kakaoOptions.bms.targeting kakaoOptions.bms.chatBubbleType (타입별 required 필드)	messages.text 또는 kakaoOptions.bms.content buttons coupon 등(타입별 상이)	자유형 템플릿 기반 메시지 타입(chatBubbleType) 선택	kakaoOptions.bms.chatBubbleType 필드가 있을 경우

카카오톡 알림톡(ATA)

사전에 등록된 템플릿 내용으로 알림톡을 발송하게 됩니다.
알림톡의 경우 템플릿으로 내용을 미리 정해놓지만 변수(치환문구)를 포함할 수 있어 발송할 때에도 내용을 지정해야 합니다.
본문 이외에도 강조 표기문구, 아이템 리스트, 부가정보 등을 모두 합하여 변수 치환 후 1,000자를 넘을 수 없습니다.

템플릿 변수 설정 방법

messages.kakaoOptions.variables 파라미터를 사용하면 템플릿의 변수만 간단히 지정할 수 있습니다.

인터랙티브 예제를 통해 카카오 알림톡 템플릿의 변수 설정 방법을 직접 체험해보세요!

카카오 알림톡 미리보기: 각 항목을 클릭하여 내용을 수정할 수 있습니다
JSON 데이터: 변수 값이 실시간으로 반영됩니다
양방향 동기화: 왼쪽에서 수정하면 오른쪽 JSON이 업데이트되고, JSON을 직접 수정해도 왼쪽 미리보기가 변경됩니다

알림톡 도착

안녕하세요,고객님!

회원 유형

가입일

회원 ID

🎉 가입 혜택

✓

카카오 브랜드 메시지 자유형 (BMS_FREE)

BMS_FREE유형의 메시지는 카카오 브랜드 메시지(Brand Message)를 템플릿 등록 없이 발송할 때 사용하는 유형입니다. messages.kakaoOptions.bms.chatBubbleType에 따라 필수 필드 / 사용 가능 필드가 달라집니다.

필수 입력 필드

수신번호: messages[].to (필수)
프로필 식별자: messages[].kakaoOptions.pfId 또는 messages[].kakaoOptions.senderKey 중 1개 (필수)
BMS 설정: messages[].kakaoOptions.bms
- 타겟팅: targeting = 'M'(마케팅수신동의자) | 'N'(마케팅수신동의자 - 채널친구) | 'I'(채널친구)
  (I를 제외한 타겟팅은 브랜드 등록이 필요합니다. 고객센터로 문의해주세요.)
- 말풍선 타입: chatBubbleType (필수, 아래 목록 참고)
- 성인 인증: adult (선택, 기본값 false)

chatBubbleType별로 내용 길이/줄바꿈/버튼 개수/이미지 타입 등 제약이 다릅니다.

지원 chatBubbleType(말풍선 타입)

TEXT, IMAGE, WIDE, WIDE_ITEM_LIST, COMMERCE, CAROUSEL_FEED, CAROUSEL_COMMERCE, PREMIUM_VIDEO

타입	필수필드	옵션필드
`TEXT` (텍스트형)	`messages[].text`	(옵션) `kakaoOptions.bms.adult` (옵션) `kakaoOptions.bms.buttons` (배열) (옵션) `kakaoOptions.bms.coupon`
`IMAGE` (이미지형)	`messages[].text` `kakaoOptions.bms.imageId`	(옵션) `kakaoOptions.bms.adult` (옵션) `kakaoOptions.bms.imageLink` (옵션) `kakaoOptions.bms.buttons` (배열) (옵션) `kakaoOptions.bms.coupon`
`WIDE` (와이드형)	`messages[].text` `kakaoOptions.bms.imageId`	(옵션) `kakaoOptions.bms.adult` (옵션) `kakaoOptions.bms.buttons` (배열) (옵션) `kakaoOptions.bms.coupon`
`WIDE_ITEM_LIST` (와이드 아이템 리스트형)	`kakaoOptions.bms.header` `kakaoOptions.bms.mainWideItem` - `mainWideItem.imageId` - `mainWideItem.linkMobile` `kakaoOptions.bms.subWideItemList` (배열) - 각 아이템 필수: `title`, `imageId`, `linkMobile`	(옵션) `kakaoOptions.bms.adult` (옵션) `mainWideItem.title` (옵션) `mainWideItem.linkPc`/`mainWideItem.linkAndroid`/`mainWideItem.linkIos` (옵션) `subWideItemList[].linkPc`/`subWideItemList[].linkAndroid`/`subWideItemList[].linkIos` (옵션) `kakaoOptions.bms.buttons` (배열) (옵션) `kakaoOptions.bms.coupon`
`COMMERCE` (커머스형)	`kakaoOptions.bms.imageId` `kakaoOptions.bms.commerce` - `commerce.title` `kakaoOptions.bms.buttons` (배열) - 각 버튼 필수: `name`, `linkType` - `linkType`이 `WL`이면 `linkMobile` 필수 - `linkType`이 `AL`이면 `linkMobile`/`linkAndroid`/`linkIos` 중 하나 필수	(옵션) `kakaoOptions.bms.adult` (옵션) `kakaoOptions.bms.additionalContent` (옵션) `commerce.regularPrice`/`commerce.discountPrice`/`commerce.discountRate`/`commerce.discountFixed` (옵션) `buttons[].linkPc`/`buttons[].linkAndroid`/`buttons[].linkIos` (옵션) `kakaoOptions.bms.coupon`
`CAROUSEL_FEED` (캐러셀피드형)	`kakaoOptions.bms.carousel` - `carousel.list` (배열) - 각 아이템 필수: `header`, `content`, `imageId`, `buttons`	(옵션) `kakaoOptions.bms.adult` (옵션) `carousel.tail` (사용 시 `tail.linkMobile` 필수) (옵션) `carousel.list[].imageLink` (옵션) `carousel.list[].coupon`
`CAROUSEL_COMMERCE` (캐러셀커머스형)	`kakaoOptions.bms.carousel` - `carousel.list` (배열) - 각 아이템 필수: `commerce`, `imageId`, `buttons` - `commerce` 필수: `title`	(옵션) `kakaoOptions.bms.adult` (옵션) `kakaoOptions.bms.additionalContent` (옵션) `carousel.head` (사용 시 필수: `header`, `content`, `imageId`) (옵션) `carousel.tail` (사용 시 필수: `linkMobile`) (옵션) `carousel.list[].additionalContent` (옵션) `carousel.list[].imageLink` (옵션) `carousel.list[].coupon` (옵션) `commerce.regularPrice`/`commerce.discountPrice`/`commerce.discountRate`/`commerce.discountFixed`
`PREMIUM_VIDEO` (프리미엄비디오형)	`kakaoOptions.bms.video` (필수)	(옵션) `kakaoOptions.bms.adult` (옵션) `kakaoOptions.bms.header` (옵션) `messages[].text` (옵션) `kakaoOptions.bms.buttons` (배열) (옵션) `kakaoOptions.bms.coupon` (권장) `video.videoUrl` 또는 `video.imageId` 중 1개 이상 입력 - `videoUrl`을 쓰는 경우 `https://tv.kakao.com/` 형식만 허용

하위 오브젝트 필드 설명

아래 표는 messages[].kakaoOptions.bms 내부에서 자주 사용하는 하위 오브젝트(buttons, coupon, mainWideItem, subWideItemList, carousel)의 필드 규격을 정리한 것입니다.

`buttons[]` (버튼 오브젝트)

필드	타입	필수	설명/제약
`name`	string	조건부	버튼명 - `TEXT`, `IMAGE`: 최대 14자 - 그 외: 최대 8자 - `linkType=AC`(채널추가)인 경우 무시/삭제됨
`linkType`	string	O	버튼 링크 유형 - `WL`: 웹링크 - `AL`: 앱링크 - `AC`: 채널추가(이 경우 `name`은 사용하지 않음) - `CAROUSEL_FEED`/`CAROUSEL_COMMERCE`, `COMMERCE`에서는 `WL`/`AL`만 허용
`linkMobile`	string	조건부	`WL`인 경우 필수 `AL`인 경우(`linkAndroid`/`linkIos`가 없을 때) 대체로 사용 가능
`linkPc`	string	X	PC용 웹링크(선택)
`linkAndroid`	string	조건부	`AL`인 경우 `linkMobile`/`linkAndroid`/`linkIos` 중 1개 이상 필요
`linkIos`	string	조건부	`AL`인 경우 `linkMobile`/`linkAndroid`/`linkIos` 중 1개 이상 필요

버튼 개수 제한(요약):
- TEXT, IMAGE: 최대 5개(쿠폰 사용 시 최대 4개)
- WIDE: 최대 2개
- WIDE_ITEM_LIST: 최대 2개
- COMMERCE: 최소 1개 ~ 최대 2개
- CAROUSEL_FEED, CAROUSEL_COMMERCE: 카드당 최소 1개 ~ 최대 2개
- PREMIUM_VIDEO: 최대 1개

`coupon` (쿠폰 오브젝트)

필드	타입	필수	설명/제약
`title`	string	O	쿠폰 제목(아래 5가지 형식만 허용) - `\${숫자}원 할인 쿠폰` (199,999,999) - `\${숫자}% 할인 쿠폰` (1100) - `배송비 할인 쿠폰` - `\${7자 이내} 무료 쿠폰` (공백 제외 17자) - `\${7자 이내} UP 쿠폰` (공백 제외 17자)
`description`	string	O	쿠폰 설명 - `WIDE`, `WIDE_ITEM_LIST`: 최대 18자 - 그 외: 최대 12자
`linkMobile`	string	X	쿠폰 링크(선택)
`linkPc`	string	X	쿠폰 링크(선택)
`linkAndroid`	string	X	쿠폰 링크(선택)
`linkIos`	string	X	쿠폰 링크(선택)

`mainWideItem` (와이드 아이템 리스트: 메인 아이템)

필드	타입	필수	설명/제약
`title`	string	X	메인 아이템 제목(선택) - 최대 25자 / 줄바꿈 최대 1개
`imageId`	string	O	메인 아이템 이미지 아이디 - `BMS_WIDE_MAIN_ITEM_LIST` 타입 이미지여야 함
`linkMobile`	string	O	메인 아이템 링크(모바일)
`linkPc`	string	X	메인 아이템 링크(PC)
`linkAndroid`	string	X	메인 아이템 링크(안드로이드)
`linkIos`	string	X	메인 아이템 링크(iOS)

`subWideItemList[]` (와이드 아이템 리스트: 서브 아이템, `subWideItem`)

필드	타입	필수	설명/제약
`title`	string	O	서브 아이템 제목 - 최대 30자
`imageId`	string	O	서브 아이템 이미지 아이디 - `BMS_WIDE_SUB_ITEM_LIST` 타입 이미지여야 함
`linkMobile`	string	O	서브 아이템 링크(모바일)
`linkPc`	string	X	서브 아이템 링크(PC)
`linkAndroid`	string	X	서브 아이템 링크(안드로이드)
`linkIos`	string	X	서브 아이템 링크(iOS)

`carousel` (캐러셀 오브젝트)

필드	타입	필수	설명/제약
`list`	array	O	캐러셀 카드 리스트(아래 `carousel.list[]` 참고) - `head`(인트로) 사용 시: 최소 1개 ~ 최대 5개 - `head` 미사용 시: 최소 2개 ~ 최대 6개
`head`	object	조건부	`CAROUSEL_COMMERCE`에서만 사용 가능(선택)
`tail`	object	조건부	`CAROUSEL_FEED`/`CAROUSEL_COMMERCE`에서 사용 가능(선택)

`carousel.head` (캐러셀 인트로, `CAROUSEL_COMMERCE` 전용)

필드	타입	필수	설명/제약
`header`	string	O	최대 20자
`content`	string	O	최대 50자 / 줄바꿈 최대 2개
`imageId`	string	O	`BMS_CAROUSEL_COMMERCE_LIST` 타입 이미지여야 함
`linkMobile`	string	조건부	`linkPc`/`linkAndroid`/`linkIos` 중 1개라도 있으면 필수
`linkPc`	string	X	선택
`linkAndroid`	string	X	선택
`linkIos`	string	X	선택

`carousel.tail` (캐러셀 더보기 영역)

필드	타입	필수	설명/제약
`linkMobile`	string	O	필수
`linkPc`	string	X	선택
`linkAndroid`	string	X	선택
`linkIos`	string	X	선택

`carousel.list[]` (캐러셀 리스트)

CAROUSEL_FEED일 경우

필드	타입	필수	설명/제약
`header`	string	O	최대 20자
`content`	string	O	최대 180자 / 줄바꿈 최대 2개
`imageId`	string	O	`BMS_CAROUSEL_FEED_LIST` 타입 이미지여야 함
`imageLink`	string	X	선택
`buttons`	array	O	카드당 최소 1개 ~ 최대 2개(`WL`/`AL`만 허용)
`coupon`	object	X	선택

CAROUSEL_COMMERCE일 경우

필드	타입	필수	설명/제약
`commerce`	object	O	필수(`commerce.title` 포함)
`imageId`	string	O	`BMS_CAROUSEL_COMMERCE_LIST` 타입 이미지여야 함
`imageLink`	string	X	선택
`buttons`	array	O	카드당 최소 1개 ~ 최대 2개(`WL`/`AL`만 허용)
`coupon`	object	X	선택
`additionalContent`	string	X	선택 - 최대 34자 / 줄바꿈 최대 1개

chatBubbleType별 예시

텍스트형 BMS (자유형/chatBubbleType: TEXT)

필수
- messages[].text
선택
- messages[].kakaoOptions.bms.buttons[]
- messages[].kakaoOptions.bms.coupon
- messages[].kakaoOptions.bms.adult
주요 제약
- text: 최대 1,300자 / 줄바꿈 99개
- buttons[]: 최대 5개(쿠폰 사용 시 4개)
- coupon: title, description 필수(제목은 5가지 형식만 허용)
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "text": "브랜드 메시지 텍스트 예시입니다.",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "TEXT",
          "adult": false,
          "buttons": [
            {
              "name": "자세히 보기",
              "linkType": "WL",
              "linkMobile": "https://example.com"
            }
          ]
        }
      }
    }
  ]
}

이미지형 BMS (자유형/chatBubbleType: IMAGE)

필수
- messages[].text
- messages[].kakaoOptions.bms.imageId
선택
- messages[].kakaoOptions.bms.buttons[]
- messages[].kakaoOptions.bms.coupon
- messages[].kakaoOptions.bms.adult
주요 제약
- text: 최대 400자 / 줄바꿈 29개
- imageId: chatBubbleType에 맞는 이미지 타입이 아니면 검증 단계에서 실패
- buttons[]: 최대 5개(쿠폰 사용 시 4개)
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "text": "이미지형 브랜드 메시지 예시입니다.",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "IMAGE",
          "imageId": "IMGxxxxxxxxxxxxxxxx",
          "buttons": [
            {
              "name": "구매하기",
              "linkType": "WL",
              "linkMobile": "https://example.com/buy"
            }
          ]
        }
      }
    }
  ]
}

와이드형 BMS (자유형/chatBubbleType: WIDE)

필수
- messages[].text
- messages[].kakaoOptions.bms.imageId
선택
- messages[].kakaoOptions.bms.buttons[]
- messages[].kakaoOptions.bms.coupon
- messages[].kakaoOptions.bms.adult
주요 제약
- text: 최대 76자 / 줄바꿈 1개
- imageId: BMS_WIDE 타입 이미지여야 함
- buttons[]: 최대 2개
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "text": "와이드형 예시(76자/줄바꿈 1개 제한).",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "WIDE",
          "imageId": "IMGxxxxxxxxxxxxxxxx",
          "buttons": [
            {
              "name": "자세히",
              "linkType": "WL",
              "linkMobile": "https://example.com/detail"
            }
          ]
        }
      }
    }
  ]
}

와이드 아이템 리스트형 BMS (자유형/chatBubbleType: WIDE_ITEM_LIST)

필수
- messages[].kakaoOptions.bms.header
- messages[].kakaoOptions.bms.mainWideItem
  - mainWideItem.imageId
  - mainWideItem.linkMobile
- messages[].kakaoOptions.bms.subWideItemList[] (배열)
  - 각 아이템 필수: title, imageId, linkMobile
선택
- mainWideItem.title, mainWideItem.linkPc, mainWideItem.linkAndroid, mainWideItem.linkIos
- messages[].kakaoOptions.bms.buttons[]
- messages[].kakaoOptions.bms.coupon
- messages[].kakaoOptions.bms.adult
주요 제약
- header: 최대 20자, 줄바꿈 불가
- mainWideItem.title: 최대 25자
- mainWideItem.imageId: BMS_WIDE_MAIN_ITEM_LIST 타입 이미지여야 함
- subWideItemList[].title: 최대 30자
- subWideItemList[].imageId: BMS_WIDE_SUB_ITEM_LIST 타입 이미지여야 함
- 링크(link*): http(s):// 웹 링크만 허용
- buttons[]: 최대 2개
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "WIDE_ITEM_LIST",
          "header": "추천 상품",
          "mainWideItem": {
            "title": "메인 상품",
            "imageId": "IMG_MAIN_xxxxxxxxxxxxxxxx",
            "linkMobile": "https://example.com/main"
          },
          "subWideItemList": [
            {
              "title": "서브 상품 1",
              "imageId": "IMG_SUB1_xxxxxxxxxxxxxxxx",
              "linkMobile": "https://example.com/sub1"
            },
            {
              "title": "서브 상품 2",
              "imageId": "IMG_SUB2_xxxxxxxxxxxxxxxx",
              "linkMobile": "https://example.com/sub2"
            }
          ],
          "buttons": [
            {
              "name": "전체 보기",
              "linkType": "WL",
              "linkMobile": "https://example.com/all"
            }
          ]
        }
      }
    }
  ]
}

커머스형 BMS (자유형/chatBubbleType: COMMERCE)

필수
- messages[].kakaoOptions.bms.imageId
- messages[].kakaoOptions.bms.commerce.title
- messages[].kakaoOptions.bms.buttons[]
선택
- messages[].kakaoOptions.bms.additionalContent
- messages[].kakaoOptions.bms.commerce.regularPrice, discountPrice, discountRate, discountFixed
- messages[].kakaoOptions.bms.coupon
- messages[].kakaoOptions.bms.adult
주요 제약
- additionalContent: 최대 34자
- 가격 필드: 숫자 문자열만 허용(표기 방식에 따라 조합 사용)
- buttons[]: 최소 1개~최대 2개, WL/AL만 허용
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "COMMERCE",
          "imageId": "IMGxxxxxxxxxxxxxxxx",
          "additionalContent": "무료배송",
          "commerce": {
            "title": "상품명",
            "regularPrice": "12000",
            "discountPrice": "9900",
            "discountRate": "18"
          },
          "buttons": [
            {
              "name": "구매하기",
              "linkType": "WL",
              "linkMobile": "https://example.com/buy"
            }
          ]
        }
      }
    }
  ]
}

캐러셀피드형 BMS (자유형/chatBubbleType: CAROUSEL_FEED)

필수
- messages[].kakaoOptions.bms.carousel.list[]
  - 각 카드 필수: header, content, imageId, buttons[]
선택
- messages[].kakaoOptions.bms.carousel.tail (tail 링크)
- messages[].kakaoOptions.bms.carousel.list[].coupon (카드별)
- messages[].kakaoOptions.bms.adult
주요 제약
- carousel.list 개수: 2~6개
- carousel.list[].header: 최대 20자, 줄바꿈 불가
- carousel.list[].content: 최대 180자 / 줄바꿈 2개
- carousel.list[].buttons[]: 카드당 최소 1개~최대 2개, WL/AL만 허용
- carousel.tail.linkMobile 필수, tail 링크에는 변수 사용 불가
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "CAROUSEL_FEED",
          "carousel": {
            "list": [
              {
                "header": "카드 1 제목",
                "content": "카드 1 본문입니다.",
                "imageId": "IMG_CARD1_xxxxxxxxxxxxxxxx",
                "buttons": [
                  {
                    "name": "열기",
                    "linkType": "WL",
                    "linkMobile": "https://example.com/1"
                  }
                ]
              },
              {
                "header": "카드 2 제목",
                "content": "카드 2 본문입니다.",
                "imageId": "IMG_CARD2_xxxxxxxxxxxxxxxx",
                "buttons": [
                  {
                    "name": "열기",
                    "linkType": "AL",
                    "linkMobile": "https://example.com/2"
                  }
                ]
              }
            ],
            "tail": {
              "linkMobile": "https://example.com/more"
            }
          }
        }
      }
    }
  ]
}

캐러셀 커머스형 BMS (자유형/chatBubbleType: CAROUSEL_COMMERCE)

필수
- messages[].kakaoOptions.bms.carousel.list[]
  - 각 카드 필수: commerce.title, imageId, buttons[]
선택
- messages[].kakaoOptions.bms.carousel.head (head 영역)
- messages[].kakaoOptions.bms.carousel.tail (tail 링크)
- messages[].kakaoOptions.bms.additionalContent (캐러셀 상단 추가 문구)
- carousel.list[].additionalContent (카드별 추가 문구)
- messages[].kakaoOptions.bms.carousel.list[].coupon (카드별)
- messages[].kakaoOptions.bms.adult
주요 제약
- carousel.list 개수: head가 있으면 1~~5개, 없으면 2~~6개
- carousel.head: header(20자/줄바꿈 불가), content(50자/줄바꿈 2개), imageId 필수
  linkPc/linkAndroid/linkIos 중 하나라도 쓰면 linkMobile도 필수
- carousel.list[].buttons[]: 카드당 최소 1개~최대 2개, WL/AL만 허용
- additionalContent: 최대 34자
  carousel.list[].additionalContent는 줄바꿈 최대 1개
- carousel.tail.linkMobile 필수, tail 링크에는 변수 사용 불가
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "CAROUSEL_COMMERCE",
          "additionalContent": "연말 특가",
          "carousel": {
            "head": {
              "header": "지금 구매하세요",
              "content": "최대 50% 할인",
              "imageId": "IMG_HEAD_xxxxxxxxxxxxxxxx",
              "linkMobile": "https://example.com/event"
            },
            "list": [
              {
                "imageId": "IMG_C1_xxxxxxxxxxxxxxxx",
                "commerce": {
                  "title": "상품 1",
                  "regularPrice": "20000",
                  "discountPrice": "15000",
                  "discountRate": "25"
                },
                "buttons": [
                  {
                    "name": "구매",
                    "linkType": "WL",
                    "linkMobile": "https://example.com/p1"
                  }
                ]
              },
              {
                "imageId": "IMG_C2_xxxxxxxxxxxxxxxx",
                "additionalContent": "사은품 증정",
                "commerce": {
                  "title": "상품 2",
                  "regularPrice": "30000",
                  "discountPrice": "24000",
                  "discountRate": "20"
                },
                "buttons": [
                  {
                    "name": "구매",
                    "linkType": "WL",
                    "linkMobile": "https://example.com/p2"
                  }
                ]
              }
            ],
            "tail": {
              "linkMobile": "https://example.com/more"
            }
          }
        }
      }
    }
  ]
}

프리미엄 비디오형 BMS (자유형/chatBubbleType: PREMIUM_VIDEO)

필수
- messages[].kakaoOptions.bms.video
선택
- messages[].kakaoOptions.bms.header
- messages[].text (동영상 카드의 본문 content)
- messages[].kakaoOptions.bms.buttons[]
- messages[].kakaoOptions.bms.coupon
- messages[].kakaoOptions.bms.adult
주요 제약
- header: 최대 20자, 줄바꿈 불가
- text: 최대 76자 / 줄바꿈 1개
- video.videoUrl: https://tv.kakao.com/ 형식만 허용(그리고 https://로 시작해야 함)
- buttons[]: 최대 1개
파라미터 예시

{
  "messages": [
    {
      "to": "01012345678",
      "text": "프리미엄 비디오형 본문 예시입니다.",
      "kakaoOptions": {
        "pfId": "PFxxxxxxxxxxxxxxxx",
        "bms": {
          "targeting": "I",
          "chatBubbleType": "PREMIUM_VIDEO",
          "header": "영상 안내",
          "video": {
            "videoUrl": "https://tv.kakao.com/v/123456789"
          },
          "buttons": [
            {
              "name": "영상 보기",
              "linkType": "WL",
              "linkMobile": "https://example.com/video"
            }
          ]
        }
      }
    }
  ]
}

대체발송

알림톡(ATA), 친구톡(CTA), 이미지 친구톡(CTI), RCS 등의 경우 기본적으로 대체발송이 활성화되어 있습니다. messages.kakaoOptions.disableSms (카카오) 또는 messages.rcsOptions.disableSms (RCS)를 true로 설정하지 않는 한 발송에 실패하면 문자(SMS, LMS)로 대체 발송을 시도합니다. 아래 지원 여부 표를 통해 각 메시지 타입의 대체발송 지원 상태를 확인해주세요.

메시지 타입	대체발송 지원
SMS	미지원
LMS	미지원
MMS	미지원
카카오 알림톡	지원
카카오 친구톡	지원
카카오 이미지 친구톡	지원
카카오 브랜드 메시지	미지원
RCS SMS	지원
RCS LMS	지원
RCS MMS	지원
RCS 템플릿	미지원
RCS 이미지 템플릿	미지원
네이버 스마트 알림톡	지원
음성 메시지	미지원
FAX	미지원

대체발송 조건

대체발송이 정상적으로 동작하려면 요청 본문에 다음 조건을 모두 만족해야 합니다.

messages.kakaoOptions.disableSms: false로 설정
messages.rcsOptions.disableSms: false로 설정
messages.from: 사전 등록된 발신번호 명시

알림톡, 친구톡 발송 시 from 필드는 빈 값도 허용되지만, 대체발송을 원한다면 반드시 사전 등록된 발신번호를 명시해야 합니다. 조건을 만족하지 않으면 알림톡/친구톡 발송 실패 시 그대로 실패로 종결됩니다.

발신번호 사전 등록하러 가기

실패 원인	타입	설명
알림톡	정보성 메시지	기술적 전달 실패에 기반한 대체발송
친구톡	광고성 메시지	정책적 규칙을 포함한 대체발송
RCS	리치 커뮤니케이션	기술적 및 정책적 제약에 기반한 대체발송

대체발송 시 원래 메시지 타입의 가격은 환불되고 각 문자 타입에 맞는 금액이 차감됩니다.

친구톡 발송이 실패하여 문자 메시지로 대체 발송될 때, 솔라피 시스템은 정보통신망법의 광고성 정보 전송 규제를 준수하기 위해 메시지 본문에 (광고) 문구를 자동으로 추가합니다. 자세한 내용은 해당 문서를 확인해주세요.

대체발송 시 메시지 콘텐츠 변환

카카오톡의 리치 미디어 환경에서 문자 메시지 환경으로 채널이 전환될 때, 솔라피 시스템은 정보 손실을 최소화하고 핵심 내용을 보존하는 방향으로 콘텐츠를 변환합니다.

콘텐츠 유형	변환 방식
텍스트 콘텐츠	알림톡/RCS 템플릿의 경우 템플릿의 내용이, 친구톡/RCS의 경우 `messages.text` 필드에 입력한 내용이 대체발송 문자로 전송됩니다.
버튼 (웹/앱 링크)	버튼의 이름과 연결된 URL이 문자 메시지 본문에 텍스트 형태로 포함됩니다. 예시 이미지를 참고해주세요.
이미지	이미지가 포함된 친구톡은 MMS로 대체발송되지 않고 LMS로 전환됩니다. 이미지는 URL 링크 형태로 LMS 메시지 본문에 포함됩니다.

Body Params

Name	Type	Required	Description
messages	Array<Object>	O	발송할 메시지 내용
scheduledDate	date	-	메시지 예약 날짜. 날짜가 지정되면 해당 시간에 메시지가 발송됩니다. 만약 현재 시간보다 이전으로 지정하면 즉시 발송됩니다. 예약 즉시 일일발송량에 영향을 주며 잔액은 발송 시 차감됩니다.
strict	boolean	-	엄격 검사 여부. 기본값: `false` - 유요하지 않은 문자 검사(아닐 시 자체적으로 삭제). - LMS 나 MMS에서 제목 여부 검사. (아닐 시 문자 내용에서 제목을 구함). - 템플릿을 발송 전 검사(아닐 시 발송 후 실패).
agent	Object	-	에이전트
allowDuplicates	boolean	-	중복 수신번호 허용 여부. 기본값: `false`
showMessageList	boolean	-	응답에 메시지도 포함시킬지 선택 여부.

Response

Name	Type	Should Return	Description
failedMessageList	Array<Object>	O	등록 실패된 메시지 목록. 여기 목록에 포함되어 있는 메시지는 발송되지 않은 메시지입니다.
groupInfo	Object	O	발송 요청한 메시지들의 그룹 정보

Structures

{6 properties

"messages":

[1 items...]

{16 properties...}

"to": "string",

"from": "string",

"text": "string",

"type": "string",

"country": "string",

"subject": "string",

"imageId": "string",

"kakaoOptions":

{17 properties...}

"pfId": "string",

"templateId": "string",

"senderKey": "string",

"title": "string",

"adFlag": "boolean",

"templateCode": "string",

"buttonName": "string",

"buttonUrl": "string",

"disableSms": "boolean",

"imageId": "string",

"variables":

{3 properties...}

"#{홍길동}": "string",

"#{010-0000-0000}": "string",

"#{2021년 6월 17일}": "string"

}

"quickReplies":

[1 items...]

{8 properties...}

"name": "string",

"linkType": "string",

"linkMo": "string",

"linkPc": "string",

"linkAnd": "string",

"linkIos": "string",

"chatExtra": "string",

"targetOut": "boolean"

}

]

"highlight":

{1 properties...}

"title": "string"

}

"header": "string",

"item":

{2 properties...}

"list":

[1 items...]

{1 properties...}

"description": "string"

}

]

"summary":

{1 properties...}

"description": "string"

}

"buttons":

[1 items...]

{8 properties...}

"buttonName": "string",

"buttonType": "string",

"linkMo": "string",

"linkPc": "string",

"linkAnd": "string",

"linkIos": "string",

"chatExtra": "string",

"targetOut": "boolean"

}

]

"bms":

{14 properties...}

"targeting": "string",

"chatBubbleType": "string",

"adult": "boolean",

"header": "string",

"imageId": "string",

"imageLink": "string",

"additionalContent": "string",

"carousel":

{

}

"mainWideItem":

{

}

"subWideItemList":

{

}

"buttons":

{

}

"coupon":

{

}

"commerce":

{

}

"video":

{

}

"naverOptions":

{5 properties...}

"talkId": "string",

"templateId": "string",

"disableSms": "boolean",

"variables":

{3 properties...}

"#{홍길동}": "string",

"#{010-0000-0000}": "string",

"#{2021년 6월 17일}": "string"

}

"buttons":

[1 items...]

{7 properties...}

"buttonCode": "string",

"buttonName": "string",

"buttonType": "string",

"linkMo": "string",

"linkPc": "string",

"linkAnd": "string",

"linkIos": "string"

}

]

}

"rcsOptions":

{9 properties...}

"brandId": "string",

"templateId": "string",

"copyAllowed": "boolean",

"variables":

{3 properties...}

"{{홍길동}}": "string",

"{{010-0000-0000}}": "string",

"{{2021년 6월 17일}}": "string"

}

"mmsType": "string",

"commercialType": "boolean",

"disableSms": "boolean",

"additionalBody":

[1 items...]

{4 properties...}

"title": "string",

"description": "string",

"imageId": "string",

"buttons":

[1 items...]

{12 properties...}

"buttonType": "string",

"buttonName": "string",

"link": "string",

"latitude": "string",

"longitude": "string",

"label": "string",

"query": "string",

"title": "string",

"startTime": "date",

"endTime": "date",

"text": "string",

"phone": "string"

}

]

}

]

"buttons":

[1 items...]

{12 properties...}

"buttonType": "string",

"buttonName": "string",

"link": "string",

"latitude": "string",

"longitude": "string",

"label": "string",

"query": "string",

"title": "string",

"startTime": "date",

"endTime": "date",

"text": "string",

"phone": "string"

}

]

}

"faxOptions":

{1 properties...}

"fileIds":

[1 items...]

{

}

]

}

"voiceOptions":

{6 properties...}

"voiceType": "string",

"headerMessage": "string",

"tailMessage": "string",

"replyRange": "number",

"counselorNumber": "string",

"variables":

{

}

"customFields":

{1 properties...}

"key": "string"

}

"autoTypeDetect": "boolean",

"hint":

{

}

"replacements":

[1 items...]

{4 properties...}

"to": "string",

"from": "string",

"text": "string",

"customFields":

{1 properties...}

"key": "string"

}

]

}

]

"scheduledDate": "date",

"strict": "boolean",

"agent":

{3 properties...}

"appId": "string",

"osPlatform": "string",

"sdkVersion": "string"

}

"allowDuplicates": "boolean",

"showMessageList": "string"

}

{2 properties

"failedMessageList":

[1 items...]

{8 properties...}

"to": "string",

"from": "string",

"type": "string",

"country": "string",

"messageId": "string",

"statusCode": "string",

"statusMessage": "string",

"accountId": "string"

}

]

"groupInfo":

{28 properties...}

"count":

{9 properties...}

"total": "number",

"sentTotal": "number",

"sentFailed": "number",

"sentSuccess": "number",

"sentPending": "number",

"sentReplacement": "number",

"refund": "number",

"registeredFailed": "number",

"registeredSuccess": "number"

}

"countForCharge":

{24 properties...}

"sms":

{2 properties...}

"82": "number",

"101": "number"

}

"lms":

{2 properties...}

"82": "number",

"101": "number"

}

"mms":

{2 properties...}

"82": "number",

"101": "number"

}

"ata":

{2 properties...}

"82": "number",

"101": "number"

}

"cta":

{2 properties...}

"82": "number",

"101": "number"

}

"cti":

{2 properties...}

"82": "number",

"101": "number"

}

"nsa":

{2 properties...}

"82": "number",

"101": "number"

}

"rcs_sms":

{2 properties...}

"82": "number",

"101": "number"

}

"rcs_lms":

{2 properties...}

"82": "number",

"101": "number"

}

"rcs_mms":

{2 properties...}

"82": "number",

"101": "number"

}

"rcs_tpl":

{2 properties...}

"82": "number",

"101": "number"

}

"rcs_itpl":

{2 properties...}

"82": "number",

"101": "number"

}

"rcs_ltpl":

{2 properties...}

"82": "number",

"101": "number"

}

"fax":

{2 properties...}

"82": "number",

"101": "number"

}

"voice":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_text":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_image":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_wide":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_wide_item_list":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_carousel_feed":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_premium_video":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_commerce":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_carousel_commerce":

{2 properties...}

"82": "number",

"101": "number"

}

"bms_free":

{2 properties...}

"82": "number",

"101": "number"

}

"balance":

{5 properties...}

"requested": "number",

"replacement": "number",

"additional": "number",

"refund": "number",

"sum": "number"

}

"point":

{5 properties...}

"requested": "number",

"replacement": "number",

"additional": "number",

"refund": "number",

"sum": "number"

}

"app":

{3 properties...}

"profit":

{24 properties...}

"sms": "number",

"lms": "number",

"mms": "number",

"ata": "number",

"cta": "number",

"cti": "number",

"nsa": "number",

"rcs_sms": "number",

"rcs_lms": "number",

"rcs_mms": "number",

"rcs_tpl": "number",

"rcs_itpl": "number",

"rcs_ltpl": "number",

"fax": "number",

"voice": "number",

"bms_text": "number",

"bms_image": "number",

"bms_wide": "number",

"bms_wide_item_list": "number",

"bms_carousel_feed": "number",

"bms_premium_video": "number",

"bms_commerce": "number",

"bms_carousel_commerce": "number",

"bms_free": "number"

}

"app": "string",

"version": "string"

}

"serviceMethod": "string",

"sdkVersion": "string",

"osPlatform": "string",

"log":

[1 items...]

{7 properties...}

"createAt": "date",

"message": "string",

"oldBalance": "number",

"newBalance": "number",

"oldPoint": "number",

"newPoint": "number",

"totalPrice": "number"

}

]

"status": "string",

"dateSent": "date",

"scheduledDate": "date",

"dateCompleted": "date",

"isRefunded": "boolean",

"flagUpdated": "boolean",

"prepaid": "boolean",

"strict": "boolean",

"masterAccountId": "string",

"allowDuplicates": "boolean",

"_id": "string",

"accountId": "string",

"apiVersion": "string",

"customFields":

{1 properties...}

"key": "string"

}

"hint": "string",

"groupId": "string",

"price":

{1 properties...}

"82":

{24 properties...}

"sms": "number",

"lms": "number",

"mms": "number",

"ata": "number",

"cta": "number",

"cti": "number",

"nsa": "number",

"rcs_sms": "number",

"rcs_lms": "number",

"rcs_mms": "number",

"rcs_tpl": "number",

"rcs_itpl": "number",

"rcs_ltpl": "number",

"fax": "number",

"voice": "number",

"bms_text": "number",

"bms_image": "number",

"bms_wide": "number",

"bms_wide_item_list": "number",

"bms_carousel_feed": "number",

"bms_premium_video": "number",

"bms_commerce": "number",

"bms_carousel_commerce": "number",

"bms_free": "number"

}

"dateCreated": "date",

"dateUpdated": "date"

}

메시지 타입별 비교​

카카오톡 알림톡(ATA)​

템플릿 변수 설정 방법​

🎉 가입 혜택

카카오 브랜드 메시지 자유형 (BMS_FREE)​

필수 입력 필드​

지원 chatBubbleType(말풍선 타입)​

하위 오브젝트 필드 설명​

buttons[] (버튼 오브젝트)​

coupon (쿠폰 오브젝트)​

mainWideItem (와이드 아이템 리스트: 메인 아이템)​

subWideItemList[] (와이드 아이템 리스트: 서브 아이템, subWideItem)​

carousel (캐러셀 오브젝트)​

carousel.head (캐러셀 인트로, CAROUSEL_COMMERCE 전용)​

carousel.tail (캐러셀 더보기 영역)​

carousel.list[] (캐러셀 리스트)​

chatBubbleType별 예시​

텍스트형 BMS (자유형/chatBubbleType: TEXT)​

이미지형 BMS (자유형/chatBubbleType: IMAGE)​

와이드형 BMS (자유형/chatBubbleType: WIDE)​

와이드 아이템 리스트형 BMS (자유형/chatBubbleType: WIDE_ITEM_LIST)​

커머스형 BMS (자유형/chatBubbleType: COMMERCE)​

캐러셀피드형 BMS (자유형/chatBubbleType: CAROUSEL_FEED)​

캐러셀 커머스형 BMS (자유형/chatBubbleType: CAROUSEL_COMMERCE)​

프리미엄 비디오형 BMS (자유형/chatBubbleType: PREMIUM_VIDEO)​

대체발송​

대체발송 조건​

대체발송 시 메시지 콘텐츠 변환​

Body Params​

Response​

Structures​

메시지 타입별 비교

카카오톡 알림톡(ATA)

템플릿 변수 설정 방법

카카오 브랜드 메시지 자유형 (BMS_FREE)

필수 입력 필드

지원 chatBubbleType(말풍선 타입)

하위 오브젝트 필드 설명

`buttons[]` (버튼 오브젝트)

`coupon` (쿠폰 오브젝트)

`mainWideItem` (와이드 아이템 리스트: 메인 아이템)

`subWideItemList[]` (와이드 아이템 리스트: 서브 아이템, `subWideItem`)

`carousel` (캐러셀 오브젝트)

`carousel.head` (캐러셀 인트로, `CAROUSEL_COMMERCE` 전용)

`carousel.tail` (캐러셀 더보기 영역)

`carousel.list[]` (캐러셀 리스트)

chatBubbleType별 예시

텍스트형 BMS (자유형/chatBubbleType: TEXT)

이미지형 BMS (자유형/chatBubbleType: IMAGE)

와이드형 BMS (자유형/chatBubbleType: WIDE)

와이드 아이템 리스트형 BMS (자유형/chatBubbleType: WIDE_ITEM_LIST)

커머스형 BMS (자유형/chatBubbleType: COMMERCE)

캐러셀피드형 BMS (자유형/chatBubbleType: CAROUSEL_FEED)

캐러셀 커머스형 BMS (자유형/chatBubbleType: CAROUSEL_COMMERCE)

프리미엄 비디오형 BMS (자유형/chatBubbleType: PREMIUM_VIDEO)

대체발송

대체발송 조건

대체발송 시 메시지 콘텐츠 변환

Body Params

Response

Structures