알림톡 API를 연동 사용하다 보면 메시지를 보내는 기능만큼 자주 확인하게 되는 것이 템플릿입니다. 알림톡은 카카오가 승인한 템플릿을 기반으로 발송되기 때문에 어떤 템플릿을 등록했고 검수 상태가 어디까지 진행됐는지 확인하는 일이 운영 과정에 계속 따라오죠.
초기에는 콘솔에서 템플릿을 하나씩 등록하고 확인해도 충분합니다. 하지만 자체 CRM이나 관리자 페이지에서 템플릿을 직접 관리해야 한다면 이야기가 달라져요. 운영자가 콘솔을 오가지 않고도 템플릿을 조회하고, 새 템플릿을 등록하고, 필요한 경우 수정할 수 있어야 하니까요.
이번 글에서는 비즈고 알림톡 API에서 템플릿을 조회, 등록, 수정하는 방법을 중심으로 정리했습니다. 실제 요청 방식과 세부 값은 알림톡 API 문서에서 확인할 수 있습니다.
🖥️ 비즈고 알림톡 API가 제공하는 템플릿 관리 기능
비즈고 알림톡 API는 메시지 발송 외에도 템플릿을 조회하고, 새로 등록하고, 수정하고, 검수 요청까지 보낼 수 있는 기능을 함께 제공합니다. 작업별로 필요한 API를 먼저 정리하면 이렇습니다.
🔍 조회 API로 확인할 수 있는 템플릿 정보
이미 등록된 템플릿을 확인할 때는 템플릿 조회 API를 사용합니다. 기준이 되는 값은 senderKey와 templateCode입니다. senderKey는 카카오톡 비즈메시지 발신프로필 키이고, templateCode는 알림톡 템플릿을 구분하는 코드예요.
조회 API에서는 템플릿 이름, 본문은 물론 검수 상태나 버튼 정보처럼 운영 중에 필요한 값까지 함께 확인할 수 있어요.
알림톡 API를 사용할 때 특히 자주 보게 되는 값은 inspectionStatus입니다. 등록 직후에는 아직 발송에 사용할 수 없거든요. 알림톡 템플릿은 카카오 검수 승인 이후 사용할 수 있으므로, 등록 후에는 조회 API로 검수 상태를 다시 확인해야 합니다.
📝 등록 API에서 꼭 보내야 하는 값
새 알림톡 템플릿을 만들 때는 템플릿 등록 API를 사용합니다. 등록 요청에서 핵심이 되는 값은 다음과 같아요.
여기서 가장 먼저 정해야 할 값은 templateCode입니다. 등록 후 조회, 수정, 검수 요청, 발송 단계에서 계속 사용되는 값이기 때문이에요. 이후 알림톡 템플릿 자동치환 발송을 사용할 때도 템플릿 코드를 기준으로 본문을 불러와 변수 값을 치환합니다.
본문에는 #{name}, #{orderNo}처럼 변수 자리를 넣을 수 있습니다. 다만 알림톡은 변수를 제외한 본문이 고정되는 구조예요. 따라서 실제 고객별로 달라지는 이름, 주문번호, 날짜 같은 값은 변수로 분리하고, 승인받아야 하는 문구는 템플릿 본문에 정확히 넣어야 합니다.
버튼이나 링크가 필요한 경우에는 attachment 또는 link 구조를 함께 사용합니다. 예를 들어 주문 조회, 배송 조회, 예약 확인 버튼을 붙이는 템플릿이라면 버튼명과 모바일 URL, PC URL 등을 함께 넘기게 됩니다.
🖼️이미지 템플릿 등록 전에 필요한 업로드 API
이미지형, 와이드 이미지형, 아이템리스트형 템플릿은 이미지를 먼저 올린 뒤 등록하는 구조입니다.
템플릿 이미지 업로드 API에 이미지 파일을 FORM-DATA로 업로드하면 응답으로 imgUrl, fileName을 받아요. 이후 템플릿 등록 요청에서 imgUrl은 그대로, fileName은 imgName 필드에 넣어 함께 보내면 됩니다.
알림톡 이미지를 어떻게 준비해야 하는지 궁금하다면 준비된 이미지 없이도, 알림톡 이미지 바로 완성하는 법에서 확인해 보세요.
✅등록한 템플릿을 검수 요청하는 법
등록한 템플릿을 카카오 검수로 넘기려면 템플릿 검수 요청 API를 호출합니다. 검수 요청에서 필요한 핵심 값은 senderKey와 templateCode예요. 검수 의견이나 문의 사항이 있다면 comment 값을 함께 보낼 수 있습니다. 템플릿 상태가 대기이고 검수 상태가 등록인 경우 검수 요청을 보낼 수 있어요. 검수 요청을 이미 보낸 뒤 취소해야 한다면 검수 요청 취소 API를 사용할 수 있습니다.
⚙️수정 API로 바꿀 수 있는 항목과 주의할 점
등록된 템플릿 정보를 수정할 때는 템플릿 수정 API를 사용합니다. 수정 요청에 들어가는 구조는 등록 API와 비슷합니다. senderKey, templateCode, templateName, templateMessageType, templateEmphasizeType, text 같은 값을 기준으로 템플릿 정보를 다시 보냅니다.
다만 수정이 가능한 건 등록만 하고 아직 검수를 요청하지 않은 템플릿입니다. 승인된 템플릿은 수정이나 삭제가 되지 않아요. 승인된 템플릿의 내용을 바꿔야 한다면 새 템플릿을 등록한 뒤 검수를 다시 진행해야 합니다.
자체 시스템에서 알림톡 템플릿을 관리하려면 등록, 조회, 수정, 검수 요청 API를 순서대로 연결하는 흐름이 필요합니다. 각 API의 상세 파라미터와 응답 구조는 알림톡 API 문서에서 확인할 수 있고, 샌드박스에서 실제 요청을 테스트해볼 수도 있어요. 알림톡 API 연동을 검토하고 있다면 언제든 비즈고에 도입 문의를 남겨주세요.
FAQ
Q. 알림톡 템플릿을 API로 등록하면 바로 발송할 수 있나요?
아니요. 알림톡 템플릿은 카카오 검수 승인 이후 사용할 수 있습니다. 등록 API 호출 후에는 검수 요청 API를 호출하고, 조회 API로 검수 상태를 확인해야 합니다.
Q. 승인 여부는 어떤 API로 확인하나요?
템플릿 조회 API에서 inspectionStatus 값으로 검수 상태를 확인합니다. 운영 중인 템플릿이라면 차단 여부나 휴면 여부도 함께 보면 돼요.
Q. 자동치환 발송과 템플릿 등록 API는 어떤 관계인가요?
템플릿 등록 API는 발송 전에 템플릿 자체를 만드는 API입니다. 자동치환 발송은 이미 등록된 템플릿의 templateCode와 변수 값만으로 알림톡을 보내는 발송 방식이에요. 템플릿을 먼저 등록하고 승인받아야 자동치환 발송에서도 해당 코드를 사용할 수 있습니다.
