템플릿 생성

자체 알림톡 템플릿을 생성합니다. 알림톡은 카카오 검수에서 승인(APR)된 템플릿으로만 보낼 수 있으므로, 템플릿을 먼저 만들고 승인을 받은 뒤 변수만 바꿔 보냅니다.

부트페이가 검수를 받아 둔 공식 템플릿은 그룹키가 등록된 채널이면 검수 없이 바로 보낼 수 있습니다.

승인까지의 순서

단계 하는 일 문구 수정·삭제
1. 템플릿 생성 이 API 로 만들면 카카오에 바로 올라갑니다 가능
2. 검수 요청 검수 요청을 호출해 카카오에 심사를 맡깁니다 결과가 나올 때까지 불가
3. 승인 카카오가 승인하면 발송할 수 있습니다 불가

반려되면 반려 사유대로 수정한 뒤 다시 검수를 요청합니다.

만들기만 해서는 카카오 검수가 시작되지 않습니다. 검수를 요청하기 전까지는 고치거나 지울 수 있습니다.

POSThttps://message.bootapi.com/alimtalk/templatesBasic Auth

요청 파라미터

파라미터 타입 필수 설명
ksp_id String 필수 소유 채널 id. sender_id 로도 받습니다
register Boolean 선택 생략하면 카카오에 바로 올라갑니다. false면 부트페이에만 저장해 두고 나중에 등록합니다
name String 필수 템플릿 이름. 같은 채널 안에서 중복될 수 없습니다
content String 필수 본문 (최대 1000자). 변수는 #{변수명}, 템플릿 전체에서 최대 40개
msg_type String 선택 BA(기본형, 기본값)·EX(부가정보형)·AD(채널추가형)·MI(복합형)
emphasize_type String 선택 NONE·TEXT(강조표기형)·IMAGE(이미지형)·ITEM_LIST(아이템리스트형)
emphasize_title String 선택 강조 타이틀 (최대 50자). 발송할 때 치환됩니다
emphasize_subtitle String 선택 강조 보조문구 (최대 40자). 변수를 쓸 수 없습니다 — 쓰면 3017로 거부됩니다
template_extra String 선택 부가정보 문구. EX·MI는 필수
template_header String 선택 헤더 (최대 16자). 아이템리스트형에서만 전송됩니다
item_highlight Object 선택 아이템 하이라이트 (title·description·storage_image_url)
template_item Object 선택 아이템 리스트 (list 2~10개, summary 선택)
buttons Array 선택 버튼 (최대 5개)
image_url String 선택 카카오 사본 이미지 URL을 직접 넣는 경우
storage_image_url String 선택 이미지 업로드 응답의 image_url
security_flag Boolean 선택 보안 템플릿 여부
category String 선택 분류
tags Array 선택 태그
examples Object 선택 변수 예문(표시용). 주면 모든 변수에 예문이 있어야 하고, 채널의 변수 예문 사전에 합쳐집니다
template_code String 선택 생략하면 서버가 BT_ 로 시작하는 코드를 채번합니다

메시지 유형

유형 값 조건
기본형 BA 본문만 있으면 됨
부가정보형 EX template_extra 필수
채널추가형 AD 채널추가(AC) 버튼 필수
복합형 MI template_extra + AC 버튼 둘 다 필수

강조 유형

유형 값 조건
없음 NONE —
강조표기형 TEXT emphasize_title·emphasize_subtitle 둘 다 필수
이미지형 IMAGE 이미지 필수. 이미지 업로드로 먼저 올립니다
아이템리스트형 ITEM_LIST template_item.list 2~10개 필수 + template_header·item_highlight·이미지 중 하나 이상

아이템리스트형 글자 수 제한

항목 한도
헤더 (template_header) 16자
하이라이트 타이틀 30자 (썸네일이 있으면 21자)
하이라이트 설명 19자 (썸네일이 있으면 13자)
아이템 타이틀 6자
아이템 설명 23자
요약 타이틀 6자
요약 설명 14자. 변수·숫자·화폐 단위·쉼표·마침표만 쓸 수 있습니다

버튼

필드 설명
name 버튼명 (최대 14자). 변수를 쓸 수 없습니다​. DS(배송조회)는 배송 조회하기로 고정입니다
linkType WL(웹링크)·AL(앱링크)·DS(배송조회)·BK(봇키워드)·MD(메시지전달)·BC(상담톡)·BT(봇전환)·AC(채널추가)
linkMo 모바일 링크. WL은 필수입니다. https://#{변수명} 형식만 쓸 수 있습니다 — http:// 또는 https:// 뒤에 변수 하나만 둡니다 (예: https://#{linkMo})
linkPc PC 링크(선택). 쓰면 linkMo와 같은 형식을 따릅니다 (예: https://#{linkPc})
linkIos / linkAnd 앱링크용. AL은 둘 중 하나 이상 필요합니다

버튼 링크에는 변수를 쓸 수 있고, 그 변수도 required_variables에 잡힙니다.

웹링크(WL) 링크는 https://#{변수명} 형식만 받습니다

템플릿을 만들거나 고칠 때 웹링크 링크가 프로토콜 + 변수 하나 형식이 아니면 3017로 거절됩니다.

  • 허용: https://#{linkMo} · http://#{linkPc} · https://#{mobile_link}
  • 거절: https://shop.example.com(고정 주소) · https://shop.example.com/orders/#{order_id}(경로 + 변수) · #{linkMo}(프로토콜 없음) · https://#{a}#{b}(변수 둘)

주소는 발송할 때 그 변수의 값으로 넘깁니다 — 예: linkMo = shop.example.com/orders/1. 값에 프로토콜을 붙여 보내면 겹치지 않고 값에 붙인 프로토콜이 남습니다 — 예: 템플릿 https://#{linkMo} + 값 http://shop.example.com → http://shop.example.com. 변수명에는 공백·#·중괄호를 쓸 수 없습니다.

코드 예제

curl -X POST "https://message.bootapi.com/alimtalk/templates" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "ksp_id": "6a718d6cdd5558fb1fff72af",
    "name": "예약 확정 안내",
    "content": "#{company_name}\n#{user_name}님, #{booking_date} 예약이 확정되었어요.",
    "msg_type": "BA",
    "buttons": [
      {
        "name": "예약 확인하기",
        "linkType": "WL",
        "linkMo": "https://#{mobile_link}",
        "linkPc": "https://#{pc_link}"
      }
    ]
  }'bash

응답

{
  "id": "68b0f2a1c3d4e5f6a7b8c9d0",
  "code": "BT_A58A7B_1A2B3C4D",
  "ksp_id": "6a718d6cdd5558fb1fff72af",
  "name": "예약 확정 안내",
  "content": "#{company_name}\n#{user_name}님, #{booking_date} 예약이 확정되었어요.",
  "msg_type": "BA",
  "emphasize_type": "NONE",
  "required_variables": ["company_name", "user_name", "booking_date", "mobile_link", "pc_link"],
  "inspection_status": "registered",
  "vendor_status": 1,
  "comments": [],
  "comment_count": 0,
  "created_at": "2026-08-27 10:00:00 +0900"
}json

시각 필드 형식은 응답의 시각 형식을 참고합니다.

에러 코드

코드 error_code 메시지 대처 방법
3017 TEMPLATE_VARIABLE_MISSING 변수 누락·규격 위반 글자 수·강조표기 조건·버튼 규격(웹링크는 https://#{변수명} 형식)을 확인합니다
3018 SENDER_NOT_VERIFIED 발신프로필 미검증 채널을 다시 연동해 인증을 마칩니다
3019 TEMPLATE_CODE_DUPLICATED 템플릿 코드 중복 template_code를 비워 서버 채번에 맡깁니다
3024 SENDER_NOT_LINKED 발신프로필 미연결 ksp_id가 이 프로젝트의 채널인지 확인합니다
3027 TEMPLATE_NAME_DUPLICATED 템플릿 이름 중복 같은 채널 안에서 이름이 겹칩니다. 다른 이름을 사용합니다
3013 KAKAO_TEMPLATE_REQUEST_FAILED 등록 거부 (HTTP 500) 카카오가 등록을 거부했습니다. message의 사유를 확인합니다

변수 예문 사전

채널마다 표시용 예문​​을 모아 둔 사전이 있어, 템플릿·공식 템플릿 응답의 variable_examples 와 미리보기에서 #{user_name} 같은 자리표시자가 홍길동처럼 표시됩니다.

발송값이 아닙니다

예문은 화면 표시 전용입니다. 카카오로 전송되지 않고 검수 상태에도 영향을 주지 않습니다. 실제로 나가는 값은 발송의 variables입니다.

사전은 두 경로로 채워집니다.

  • 템플릿을 생성·수정할 때 examples 를 주면 그 채널 사전에 합쳐집니다.
  • 템플릿과 상관없이 예문만 바꾸려면 아래 API를 호출합니다.
PUThttps://message.bootapi.com/alimtalk/senders/{ksp_id}/variable_examplesBasic Auth
파라미터 타입 필수 설명
ksp_id String 필수 채널 id (경로 파라미터)
examples Object 선택 변수명 → 예문 매핑. 비우면 아무것도 바꾸지 않고 현재 사전을 돌려줍니다

보낸 키만 덮어쓰는 부분 갱신​​입니다. 다른 변수의 예문은 그대로 남고, 한 채널 안에서는 같은 변수에 같은 예문이 적용됩니다. 빈 문자열은 무시되므로 이 API로 예문을 지울 수는 없습니다. . 이 들어가거나 $ 로 시작하는 키는 오류 없이 버려집니다.

curl -X PUT "https://message.bootapi.com/alimtalk/senders/6a718d6cdd5558fb1fff72af/variable_examples" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{ "examples": { "user_name": "홍길동", "company_name": "부트페이몰" } }'bash

갱신된 사전 전체를 돌려줍니다.

{
  "ksp_id": "6a718d6cdd5558fb1fff72af",
  "variable_examples": {
    "user_name": "홍길동",
    "company_name": "부트페이몰",
    "order_number": "20260827-0001"
  }
}json

이 프로젝트에 연동된 채널이 아니면 3024(SENDER_NOT_LINKED)입니다. 공식 템플릿은 조회할 때 ksp_id 를 넘기면 그 채널 사전으로 채워지고, 자체 템플릿은 소속 채널의 사전이 자동으로 적용됩니다.

함께 보기