템플릿

템플릿은 발송할 메시지의 본문을 코드와 분리해 관리하는 단위입니다. 애플리케이션은 본문 전체 대신 templateCode와 변수 값만 보내고, 본문 수정·버전 관리·발행은 대시보드에서 처리합니다.

템플릿과 버전, 발행

하나의 템플릿은 여러 개의 버전을 가집니다. 실제 발송에 사용되는 것은 항상 발행(published)된 버전입니다.

버전 상태는 다음 규칙을 따릅니다.

• 한 템플릿에 published 버전은 동시에 1개만 존재합니다. 새 버전을 발행하면 기존 발행 버전은 자동으로 archived로 전환됩니다.
• 템플릿을 처음 만들면 버전 1이 자동으로 발행됩니다. draft로 시작할 수 없으며, 초안은 두 번째 버전부터 만들 수 있습니다.
• 발송은 항상 가장 최신의 published 버전을 사용하므로, 발행이 곧 배포입니다.

지원 채널은 kakao_alimtalk, sms, push_fcm, email, slack_webhook, slack_bot, discord_webhook, discord_bot 8종입니다.

템플릿 만들기

대시보드 셋업 › 템플릿 › 새 템플릿에서 만들 수 있습니다(커맨드 팔레트 ⌘K → “새 템플릿”). 생성·수정에는 운영자(operator) 이상의 역할이 필요합니다.

curl -X POST https://api.posmit.io/v1/templates \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "code": "welcome-email",
    "name": "가입 환영 메일",
    "contentTitle": "환영합니다, {{고객명}}님",
    "contentText": "안녕하세요 {{고객명}}님, 가입을 환영합니다.",
    "contentHtml": "<p>안녕하세요 <b>{{고객명}}</b>님</p>",
    "variablesSchema": { "고객명": "수신자 이름" },
    "enabled": true
  }'

• code가 이미 존재하면 400 에러(Template code already exists)가 반환됩니다.
• 생성 직후 버전 1이 published 상태로 만들어지며, 변경 메모에는 “최초 버전”이 기록됩니다.
• variablesSchema는 변수 이름과 설명의 목록입니다. 발송 시 변수 검증보다는 대시보드에서의 문서화·미리보기 용도로 사용됩니다.

버전 관리

버전은 삭제되지 않고 이력으로 남으므로, 언제든 과거 본문으로 되돌릴 수 있습니다. 카카오 알림톡 채널이라면 알림톡 템플릿 바인딩(alimtalkTemplateId)도 버전 단위로 저장되어 롤백 시 함께 복원됩니다.

발송에 연결하기 — templateCode와 templateVariables

알림 발송 API(POST /v1/notifications, API 키 인증)에서 content.templateCode를 지정하면 서버가 해당 코드의 템플릿에서 가장 최신 published 버전을 불러와 본문으로 사용합니다.

curl -X POST https://api.posmit.io/v1/notifications \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "x-timestamp: 1760000000" \
  -H "x-nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-signature: HMAC_SHA256_SIGNATURE" \
  -d '{
    "channel": "email",
    "recipient": { "address": "user@example.com", "name": "홍길동" },
    "content": {
      "templateCode": "welcome-email",
      "templateVariables": { "고객명": "홍길동" }
    }
  }'

동작 규칙은 다음과 같습니다.

• 본문의 {{변수명}} 자리가 templateVariables 값으로 치환됩니다. 값이 없는 변수는 빈 문자열이 됩니다.
• 요청에 content.text·title·html을 함께 보내면 요청 값이 템플릿 값을 덮어씁니다. 보내지 않은 필드만 템플릿 버전의 값이 사용됩니다.
• API 키에 발송 가능 템플릿 화이트리스트가 설정되어 있으면, 목록에 없는 템플릿으로는 발송할 수 없습니다(403).
• 카카오 알림톡 채널이고 버전에 알림톡 템플릿이 바인딩되어 있으면 공급자 메타데이터가 자동 주입됩니다. 자세한 내용은 카카오 알림톡을 참고하세요.

자주 만나는 에러는 다음과 같습니다.

인증 헤더(HMAC 서명) 생성 방법은 개발자 › 인증을 참고하세요.

변수 표기 주의: {{변수}} vs #{변수}

이메일·SMS 등 일반 채널 템플릿에서 발송 시점 치환을 기대한다면 반드시 {{변수명}} 표기를 사용해야 합니다.

AI 템플릿 생성

자연어로 의도를 설명하면 채널 규칙에 맞는 템플릿 후보를 생성해 주는 기능입니다. 대시보드 템플릿 › AI로 템플릿 생성(또는 ⌘K → “AI 템플릿 생성”)에서 사용할 수 있으며, 운영자 이상 권한이 필요합니다.

curl -X POST https://api.posmit.io/v1/ai/templates/generate \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "intent": "주문 완료 후 배송 시작을 알리는 메일. 주문번호와 예상 도착일을 포함해 주세요.",
    "tone": "친절하고 간결하게",
    "variableHints": ["고객명", "주문번호", "도착예정일"]
  }'

응답에는 생성에 사용된 모델(modelRef), 템플릿 후보(template), 검증 결과(validation)가 담깁니다.

모델 선택

채널마다 기본 모델이 정해져 있고, 요청의 model 필드로 단건 재지정(override)할 수 있습니다. 사용 가능한 모델 목록은 GET /v1/ai/models?channel={channel}로 조회합니다.

텍스트 채널은 SMS·푸시·Slack·Discord를 말합니다. 카탈로그에 없는 모델이나 채널이 지원하지 않는 모델을 지정하면 400, 모델 호출 자체가 실패하면 502가 반환됩니다(다른 모델로 재시도할 수 있습니다).

자동 검증

생성 결과는 저장 전 규칙 기반으로 검증되며, 위반 사항이 validation.violations에 담깁니다.

error 위반이 하나라도 있으면 validation.ok가 false가 됩니다. 대시보드에서는 위반 내용을 확인하고 수정하거나 다른 모델로 다시 생성할 수 있습니다.

다음 단계