자체 알림톡 템플릿을 생성합니다. 알림톡은 카카오 검수에서 승인(APR)된 템플릿으로만 보낼 수 있으므로, 템플릿을 먼저 만들고 승인을 받은 뒤 변수만 바꿔 보냅니다.
부트페이가 검수를 받아 둔 공식 템플릿은 그룹키가 등록된 채널이면 검수 없이 바로 보낼 수 있습니다.
승인까지의 순서
| 단계 | 하는 일 | 문구 수정·삭제 |
|---|---|---|
| 1. 템플릿 생성 | 이 API 로 만들면 카카오에 바로 올라갑니다 | 가능 |
| 2. 검수 요청 | 검수 요청을 호출해 카카오에 심사를 맡깁니다 | 결과가 나올 때까지 불가 |
| 3. 승인 | 카카오가 승인하면 발송할 수 있습니다 | 불가 |
반려되면 반려 사유대로 수정한 뒤 다시 검수를 요청합니다.
만들기만 해서는 카카오 검수가 시작되지 않습니다. 검수를 요청하기 전까지는 고치거나 지울 수 있습니다.
요청 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
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에 잡힙니다.
템플릿을 만들거나 고칠 때 웹링크 링크가 프로토콜 + 변수 하나 형식이 아니면 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}"
}
]
}'bashrequire 'bootpay'
commerce = BootpayStore::RestClient.new(client_key: 'your-commerce-client-key', secret_key: 'your-commerce-secret-key')
response = commerce.alimtalk_template_create(
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}'
}
]
)
puts response.dataruby응답
{
"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를 호출합니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
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 를 넘기면 그 채널 사전으로 채워지고, 자체 템플릿은 소속 채널의 사전이 자동으로 적용됩니다.



