연동한 채널이 가진 자체 템플릿을 조회합니다. 같은 채널을 쓰는 다른 프로젝트가 등록한 템플릿도 함께 나옵니다 — 같은 채널을 함께 쓸 때. 검수 상태로 걸러 보거나 이름·본문으로 검색할 수 있습니다.
발송 가능 여부는 inspection_status 가 approved(APR) 인지로 결정됩니다. 반려된 템플릿이라면 사유가 comments 에, 그 개수가 comment_count 에 담겨 옵니다.
1템플릿 목록
목록에는 페이지네이션이 없습니다. 필터에 걸린 템플릿을 한 번에 모두 돌려줍니다.
요청 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ins |
String | 선택 | 검수상태 필터. approved 처럼 키로 보냅니다 (검수 상태 참고). 벤더 문자열(APR)·숫자(3)도 그대로 받습니다 |
sort |
String | 선택 | latest(기본)·oldest·code |
keyword |
String | 선택 | 코드·이름·본문·분류 부분일치. q 로도 받습니다 |
해석할 수 없는 ins 값은 오류가 아니라 필터 없음으로 처리됩니다.
코드 예제
curl -X GET "https://message.bootapi.com/alimtalk/templates?ins=3&sort=latest" \
-H "Authorization: Basic {base64(client_key:secret_key)}"bashrequire 'bootpay'
commerce = BootpayStore::RestClient.new(client_key: 'your-commerce-client-key', secret_key: 'your-commerce-secret-key')
response = commerce.alimtalk_template_list(ins: 3, sort: 'latest')
puts response.dataruby응답
{
"list": [
{
"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"],
"inspection_status": "approved",
"vendor_status": 2,
"vendor_blocked": false,
"vendor_dormant": false,
"comments": [],
"comment_count": 0,
"version": 1,
"synced_at": "2026-08-27 10:05:00 +0900",
"created_at": "2026-08-27 10:00:00 +0900"
}
],
"count": 1,
"sort": "latest"
}json2템플릿 상세
요청 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
id |
String | 필수 | 템플릿 문서 id (경로 파라미터). ObjectId 형식이 아니면 템플릿 코드로 해석합니다 |
sync |
Boolean | 선택 | 카카오에 상태를 다시 확인할지. 생략하면 필요한 상태에서만 확인합니다(아래 참고). true 강제 · false 생략 |
검수 진행중(registered·requested)과 승인(approved)은 서버가 주기적으로 맞춰 둡니다.
따라서 상세를 조회할 때 다시 확인하지 않습니다.
반려(rejected·kakao_rejected)와 카카오에 올렸지만 검수 상태가 비어 있는 템플릿은 주기 동기화 대상이 아니므로, 상세를 조회할 때 한 번 확인합니다.
아직 올리기 전(register: false)인 템플릿은 어느 경우에도 확인하지 않습니다.
응답이 항상 최신이어야 하면 sync=true, 속도가 더 중요하면 sync=false 를 명시합니다.
이 확인은 응답을 0.5초 안팎 느리게 만듭니다.
코드 예제
curl -X GET "https://message.bootapi.com/alimtalk/templates/68b0f2a1c3d4e5f6a7b8c9d0" \
-H "Authorization: Basic {base64(client_key:secret_key)}"bash# sync 를 생략하면 필요한 상태에서만 카카오에 다시 확인합니다.
# 항상 최신이 필요하면 sync: true, 속도가 우선이면 sync: false
response = commerce.alimtalk_template_detail(
template_id: '68b0f2a1c3d4e5f6a7b8c9d0'
)
puts response.dataruby주요 응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
| inspection_status | String | 카카오 검수 상태 — 아래 표 참고 |
| vendor_status | Integer | 0 등록전 · 1 대기 · 2 정상 · 3 중단 |
| vendor_blocked | Boolean | 카카오 제재로 차단됨. 승인 상태여도 발송이 막힙니다 |
| vendor_dormant | Boolean | 카카오 휴면 처리됨 |
| comments | Array | 검수 반려 사유 |
| required_variables | Array | 발송할 때 채워야 하는 변수 |
| variable_examples | Object | 표시용 예문 (발송값이 아님) |
| buttons | Array | 버튼 목록 |
| emphasize_title · emphasize_subtitle | String | 강조 타이틀·보조문구 |
| template_header · item_highlight · template_item | String · Object · Object | 아이템리스트형 요소 |
| template_extra | String | 부가정보형(EX)의 추가 문구 |
| image_url · storage_image_url | String | 카카오에 등록된 이미지 주소 · 부트페이에 올린 원본 주소 |
| category_code · category · tags | String · String · Array | 템플릿 분류 코드 · 분류 · 태그 |
| security_flag | Boolean | 보안 템플릿 여부 |
| vendor_modified_at | String | 카카오 쪽 마지막 수정 시각 |
| synced_at | String | 마지막으로 상태를 맞춘 시각. 형식은 응답의 시각 형식 참고 |
검수 상태 (inspection_status)
| 값 | 키 | 벤더 코드 | 설명 |
|---|---|---|---|
1 |
registered |
REG | 카카오에 올라감, 검수 전 |
2 |
requested |
REQ | 검수 요청함 |
3 |
approved |
APR | 승인 — 이 상태여야 발송됩니다 |
4 |
kakao_rejected |
KRR | 등록 거절 |
5 |
rejected |
REJ | 승인 반려 |
응답에는 키가 내려오고, ins 필터에는 키·벤더 코드·숫자를 모두 보낼 수 있습니다.
같은 채널을 함께 쓸 때
자체 템플릿은 프로젝트가 아니라 채널에 묶입니다. 같은 카카오 채널을 연동한 프로젝트끼리는 템플릿을 함께 사용합니다. 리셀러가 채널을 일괄 연결한 하위 가맹점도 마찬가지입니다.
| 하는 일 | 동작 |
|---|---|
| 조회 | 다른 프로젝트가 등록한 템플릿도 나옵니다. 누가 등록했는지는 응답에 없습니다 |
| 발송 | 승인(APR)된 템플릿은 그 채널을 연동한 어느 프로젝트에서나 보낼 수 있습니다 |
| 수정·삭제 | 승인 전 템플릿은 그 채널을 연동한 어느 프로젝트에서나 고치거나 지울 수 있습니다. 승인된 템플릿은 누구도 고치거나 지울 수 없습니다 |
같은 채널을 쓰는 다른 프로젝트가 승인 전 템플릿을 바꾸거나 지울 수 있습니다. 프로젝트별로 템플릿을 분리해야 하면 채널을 따로 연동합니다.
에러 코드
| 코드 | error_code | 메시지 | 대처 방법 |
|---|---|---|---|
3015 |
TEMPLATE_NOT_FOUND |
템플릿 없음 | id 또는 코드가 맞는지 확인합니다 |
3024 |
SENDER_NOT_LINKED |
발신프로필 미연결 | 이 프로젝트에 연동되지 않은 채널의 템플릿입니다 |



