API

브랜드 템플릿 추가

작성일 2026.03.09 | 수정일 2026.03.09

POST/kakao/v2/brand-templates

새로운 브랜드 템플릿을 등록합니다.
알림톡 템플릿과 달리 등록 즉시 검수 절차 없이 바로 사용할 수 있습니다. 다양한 버블 타입을 지원하며, 각 타입별로 필수 파라미터와 버튼 개수 제한이 다르므로 하단의 타입별 요약 표를 참고하세요.

pfIdpfGroupId 중 하나만 필수로 입력해야 하며, 둘 다 입력하거나 둘 다 입력하지 않으면 ValidationError가 발생합니다.
변수명은 최대 20자 이내로, 한글/영문/숫자/특수기호(-, _)만 사용 가능합니다.

Body Params

NameTypeRequiredDescription
pfIdstring플러스친구 아이디 (pfId와 pfGroupId 중 하나만 필수)
pfGroupIdstring플러스친구 그룹 아이디 (pfId와 pfGroupId 중 하나만 필수)
chatBubbleTypestring*채팅 버블 타입 (TEXT, IMAGE, WIDE, WIDE_ITEM_LIST, CAROUSEL_FEED, COMMERCE, CAROUSEL_COMMERCE, PREMIUM_VIDEO)
namestring템플릿 이름 (최대 100자)
contentstring템플릿 내용 (최대 400자, 타입별 제한 상이)
adultboolean성인용 메시지 여부 (기본값: false)
headerstring템플릿 헤더 (최대 20자, 줄바꿈 불가)
imageIdstring브랜드 메시지 이미지 아이디
imageLinkstring이미지 클릭 시 이동할 링크 (최대 500자)
additionalContentstring템플릿 부가정보
carouselobject캐러셀 정보
headobject캐러셀 인트로 (CAROUSEL_COMMERCE 전용)
headerstring헤더 (최대 20자)
contentstring내용 (최대 50자)
imageIdstring이미지 ID
linkPcstringPC 링크
linkMobilestring모바일 링크
linkAndroidstring안드로이드 링크
linkIosstringiOS 링크
listarray*캐러셀 아이템 목록 (최소 2개, 최대 6개)
headerstring아이템 헤더 (최대 20자)
contentstring아이템 내용 (최대 180자)
additionalContentstring부가정보 (최대 34자)
imageIdstring이미지 ID
imageLinkstring이미지 클릭 링크
commerceobject커머스 정보 (CAROUSEL_COMMERCE 전용, 구조는 하단 commerce 참고)
buttonsarray버튼 목록 (구조는 하단 buttons 참고)
couponobject쿠폰 정보 (구조는 하단 coupon 참고)
tailobject캐러셀 더보기 링크
linkPcstringPC 링크
linkMobilestring모바일 링크
linkAndroidstring안드로이드 링크
linkIosstringiOS 링크
mainWideItemobject와이드 리스트의 첫 번째 아이템
titlestring아이템 제목
imageIdstring이미지 ID
linkMobilestring모바일 링크
linkPcstringPC 링크
linkAndroidstring안드로이드 링크
linkIosstringiOS 링크
subWideItemListarray와이드 리스트의 서브 아이템들 (mainWideItem과 동일한 구조)
videoobject프리미엄 동영상 정보
videoUrlstring동영상 URL
imageIdstring썸네일 이미지 ID
commerceobject커머스 정보
titlestring상품명
regularPricestring정가 (0~99,999,999)
discountPricestring할인가 (0~99,999,999)
discountRatestring할인율 (0~99,999,999)
discountFixedstring정액 할인 (0~99,999,999)
buttonsarray버튼 목록 (타입별 개수 제한 있음)
namestring*버튼 이름
linkTypestring*링크 타입
linkMobilestring모바일 링크
linkPcstringPC 링크
linkAndroidstring안드로이드 링크
linkIosstringiOS 링크
couponobject쿠폰 정보
titlestring쿠폰 제목
descriptionstring쿠폰 설명 (WIDE 계열 최대 18자, 그 외 최대 12자)
linkMobilestring모바일 링크
linkPcstringPC 링크
linkAndroidstring안드로이드 링크
linkIosstringiOS 링크

chatBubbleType 필수 파라미터 요약

NameDescription
TEXT텍스트 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"TEXT"
content템플릿 내용 (최대 400자)
IMAGE이미지 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"IMAGE"
content템플릿 내용
imageId이미지 아이디
WIDE와이드 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"WIDE"
content템플릿 내용
imageId이미지 아이디
WIDE_ITEM_LIST와이드 아이템 리스트 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"WIDE_ITEM_LIST"
header헤더 (최대 20자)
mainWideItem메인 와이드 아이템
subWideItemList서브 와이드 아이템 목록
CAROUSEL_FEED캐러셀 피드 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"CAROUSEL_FEED"
carousel.list캐러셀 아이템 목록 (최소 2개, 최대 6개)
COMMERCE커머스 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"COMMERCE"
imageId이미지 아이디
commerce커머스 정보
buttons버튼 목록 (최소 1개)
CAROUSEL_COMMERCE캐러셀 커머스 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"CAROUSEL_COMMERCE"
carousel.list캐러셀 아이템 목록 (최소 2개, 최대 6개)
PREMIUM_VIDEO프리미엄 비디오 버블 타입
pfId 또는 pfGroupId플러스친구 아이디 또는 그룹 아이디 (둘 중 하나 필수)
name템플릿 이름
chatBubbleType"PREMIUM_VIDEO"
video프리미엄 동영상 정보

타입별 버튼 제한

NameDescription
TEXT쿠폰 적용 시 최대 4개, 그 외 최대 5개
IMAGE쿠폰 적용 시 최대 4개, 그 외 최대 5개
WIDE최대 2개
CAROUSEL_FEED캐러셀당 최소 1개, 최대 2개
CAROUSEL_COMMERCE캐러셀당 최소 1개, 최대 2개
WIDE_ITEM_LIST최대 2개
PREMIUM_VIDEO최대 1개
COMMERCE최소 1개, 최대 2개


Response

chat

브랜드 템플릿 객체를 반환합니다. 이 엔드포인트만 toV2UserJSON() 변환이 적용되어 pfId, pfGroupId, isDeleted 필드가 제외되고, 대신 statuscode 필드가 추가됩니다. 브랜드 템플릿 객체의 자세한 사항은 공통 응답 스키마를 참조하세요.

{
  "brandTemplateId": "KA01BP240101000000001",
  "accountId": "AC01000000000001",
  "name": "테스트 텍스트 템플릿",
  "assignType": "CHANNEL",
  "chatBubbleType": "TEXT",
  "content": "안녕하세요 #{이름}님",
  "header": null,
  "imageId": null,
  "imageLink": null,
  "additionalContent": null,
  "adult": false,
  "allowCopy": false,
  "buttons": [],
  "coupon": null,
  "carousel": null,
  "mainWideItem": null,
  "subWideItemList": [],
  "video": null,
  "commerce": null,
  "status": "ACTIVE",
  "code": "CODE01",
  "codes": [
    {
      "code": "CODE01",
      "status": "ACTIVE",
      "service": "biz",
      "isMain": true
    }
  ],
  "variables": [
    { "name": "이름" }
  ],
  "dateCreated": "2024-01-01T00:00:00.000Z",
  "dateUpdated": "2024-01-01T00:00:00.000Z"
}