템플릿
템플릿은 발송할 메시지의 본문을 코드와 분리해 관리하는 단위입니다.
애플리케이션은 본문 전체 대신 templateCode와 변수 값만 보내고, 본문 수정·버전 관리·발행은 대시보드에서 처리합니다.
템플릿과 버전, 발행
하나의 템플릿은 여러 개의 버전을 가집니다. 실제 발송에 사용되는 것은 항상 발행(published)된 버전입니다.
| 구분 | 설명 |
|---|---|
| 템플릿 | 채널(channel) + 코드(code) + 이름(name)의 묶음입니다. 코드는 워크스페이스 안에서 유일해야 합니다. |
| 버전 | 본문(contentText), 제목(contentTitle), HTML(contentHtml), 변수 스키마(variablesSchema), 변경 메모(note)를 담는 스냅샷입니다. |
| 상태 | draft(작성 중) · published(발행됨) · archived(보관됨) 세 가지입니다. |
버전 상태는 다음 규칙을 따릅니다.
- 한 템플릿에
published버전은 동시에 1개만 존재합니다. 새 버전을 발행하면 기존 발행 버전은 자동으로archived로 전환됩니다. - 템플릿을 처음 만들면 버전 1이 자동으로 발행됩니다.
draft로 시작할 수 없으며, 초안은 두 번째 버전부터 만들 수 있습니다. - 발송은 항상 가장 최신의 published 버전을 사용하므로, 발행이 곧 배포입니다.
템플릿은 모든 발송 채널에서 사용할 수 있습니다.
템플릿 만들기
대시보드 셋업 › 템플릿 › 새 템플릿에서 만들 수 있습니다. 생성·수정에는 운영자 이상의 역할이 필요합니다.
- 코드(
code)는 워크스페이스 안에서 유일해야 하며, 이미 존재하면 생성이 거부됩니다. - 생성 직후 버전 1이
published상태로 만들어지며, 변경 메모에는 “최초 버전”이 기록됩니다. - 변수 스키마는 변수 이름과 설명의 목록입니다. 발송 시 변수 검증보다는 대시보드에서의 문서화·미리보기 용도로 사용됩니다.
API로 관리하려면 템플릿 API를 참고하세요.
발송 시점 치환이 필요한 자리에는 본문에 {{변수명}} 표기를 사용하세요.
카카오 알림톡 카탈로그와 AI 생성 결과에서 쓰는 #{변수명} 표기와는 다릅니다.
아래 “변수 표기 주의”를 참고하세요.
버전 관리
| 작업 | 방법 |
|---|---|
| 새 버전 만들기 | 템플릿 상세에서 “새 버전”을 실행합니다. 버전 번호는 자동으로 최대값 + 1이 부여되며, 상태를 지정하지 않으면 draft로 생성됩니다. |
| 초안 발행 | 버전 목록에서 발행을 실행합니다. 해당 버전이 발행되고 기존 발행 버전은 archived로 전환됩니다. |
| 롤백 | 과거 버전의 내용으로 새 버전을 만들어 즉시 발행하는 방식입니다. 대시보드의 롤백 버튼이 이를 수행하며, 변경 메모에 v{n} 내용으로 롤백이 자동 기록됩니다. 별도의 롤백 기능 API는 없습니다. |
버전은 삭제되지 않고 이력으로 남으므로, 언제든 과거 본문으로 되돌릴 수 있습니다.
카카오 알림톡 채널이라면 알림톡 템플릿 바인딩(alimtalkTemplateId)도 버전 단위로 저장되어 롤백 시 함께 복원됩니다.
발송에 연결하기 — templateCode와 templateVariables
알림 발송 API에서 content.templateCode를 지정하면 서버가 해당 코드의 템플릿에서 가장 최신 published 버전을 불러와 본문으로 사용합니다.
애플리케이션은 templateCode와 templateVariables(변수 값)만 보내면 되고, 본문의 {{변수명}} 자리가 발송 시점에 변수 값으로 치환됩니다.
요청 형식, 템플릿 해석 규칙, 에러 목록은 알림 발송 API › 템플릿 발송을 참고하세요. 카카오 알림톡 채널은 버전에 바인딩된 알림톡 템플릿의 공급자 메타데이터가 자동 주입됩니다 — 카카오 알림톡 참고.
변수 표기 주의: {{변수}} vs #{변수}
| 표기 | 쓰이는 곳 | 치환 주체 |
|---|---|---|
{{변수명}} | 일반 채널 템플릿 본문, 뉴스레터 본문 | Posmit이 발송 시점에 templateVariables(뉴스레터는 구독자 속성)로 치환합니다. |
#{변수명} | 카카오 알림톡 카탈로그 본문, AI 생성 결과 | 알림톡은 변수 값이 공급자 메타데이터로 전달되어 공급자가 치환합니다. |
이메일·SMS 등 일반 채널 템플릿에서 발송 시점 치환을 기대한다면 반드시 {{변수명}} 표기를 사용해야 합니다.
AI 템플릿 생성
자연어로 의도를 설명하면 채널 규칙에 맞는 템플릿 후보를 생성해 주는 기능입니다. 대시보드 템플릿 › AI로 템플릿 생성에서 사용할 수 있으며, 운영자 이상 권한이 필요합니다.
AI 생성 결과는 자동으로 저장되지 않습니다. 생성된 후보를 검토한 뒤 “템플릿으로 저장”을 눌러야 실제 템플릿(버전 1 발행)으로 만들어집니다. 새 버전 위저드에서 본문 채우기 용도로도 쓸 수 있습니다.
- 채널마다 기본 모델이 정해져 있고, 생성할 때 다른 모델을 선택할 수도 있습니다.
- 생성 결과는 저장 전에 채널 규칙(알림톡 1,000자·광고성 문구 금지, SMS 길이, 이메일 HTML 유무 등)으로 자동 검증됩니다. 위반이 있으면 화면에 표시되며, 수정하거나 다른 모델로 다시 생성할 수 있습니다.
모델 카탈로그와 검증 규칙 전체 목록은 템플릿 API를 참고하세요.