카카오 알림톡
카카오 알림톡은 사전 승인제 채널입니다. 카카오가 검수해 승인한 템플릿만 발송할 수 있으며, 템플릿 원본(본문·검수 상태)은 메시지 공급자(SOLAPI 또는 알리고) 측에 존재합니다. Posmit은 공급자의 알림톡 템플릿과 발신프로필을 동기화해 캐시하고, 발송 시 승인 여부를 검사한 뒤 공급자 메타데이터를 자동으로 주입합니다.
전체 흐름은 다음과 같습니다.
발신프로필(비즈채널) 준비
카카오 비즈니스 채널을 만들고 공급자(SOLAPI/알리고) 계정에 발신프로필로 연동합니다. 이 작업은 공급자 콘솔·카카오 측에서 진행합니다.
알림톡 템플릿 등록·검수 신청
공급자 콘솔에서 알림톡 템플릿을 등록하고 카카오 검수를 신청합니다. 검수 신청 역시 Posmit이 아닌 공급자 콘솔에서 합니다.
Posmit으로 동기화
대시보드 셋업 › 알림톡 템플릿에서 동기화를 실행하면 공급자에 등록된 템플릿·발신프로필·검수 상태가 Posmit 카탈로그로 들어옵니다.
Posmit 템플릿에 바인딩하고 발송
채널이 kakao_alimtalk인 Posmit 템플릿을 만들면서 승인된 알림톡 템플릿을 바인딩하면, templateCode로 발송할 수 있습니다.
발신프로필 등록
발신프로필(비즈채널)의 키는 pfId이며, 공급자에 따라 senderKey라고도 부릅니다.
발신프로필은 Posmit에서 직접 입력해 등록하는 값이 아닙니다. 공급자 계정에 연결된 프로필 목록을 동기화로 가져와서 골라 쓰는 값입니다. 발신프로필 전용 동기화 버튼은 없으며, 아래의 알림톡 템플릿 동기화를 실행하면 발신프로필도 함께 갱신됩니다.
가져온 발신프로필은 대시보드에서 확인할 수 있고, API로는 다음과 같이 조회합니다.
curl https://api.posmit.io/v1/kakao/senders \
-H "Authorization: Bearer YOUR_DASHBOARD_TOKEN"{
"senderProfiles": [
{ "pfId": "SENDER_KEY_xxx", "name": "@acme 공식", "providerKind": "solapi_kakao", "searchId": "acme" }
]
}알림톡 템플릿 동기화
대시보드 셋업 › 알림톡 템플릿의 동기화 버튼은 다음 API를 호출합니다(운영자 이상 권한).
curl -X POST https://api.posmit.io/v1/kakao/templates/sync \
-H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "providerKind": "solapi_kakao" }'providerKind(solapi_kakao또는aligo_kakao)를 생략하면 워크스페이스에 연결된 모든 카카오 공급자를 대상으로 동기화합니다.- 응답으로
{ alimtalkTemplates, added, updated, syncedAt }이 반환됩니다. 신규 템플릿은added, 기존 템플릿 갱신은updated로 집계됩니다. - 템플릿은 워크스페이스 + 공급자 종류 + 발신프로필 + 템플릿 코드 조합으로 식별되어 upsert됩니다. 같은 항목을 여러 번 동기화해도 안전합니다.
- 공급자 계정 중 하나가 실패해도 전체 동기화가 중단되지 않고 나머지 계정은 계속 처리됩니다.
동기화된 카탈로그는 GET /v1/kakao/templates로 조회할 수 있으며, 항목마다 본문(#{변수} 표기), 카테고리, 메시지 유형, 버튼 구성, 검수 상태가 담깁니다.
검수 상태
Posmit은 검수를 대행하지 않습니다. 검수 신청과 결과는 공급자 콘솔에서 관리되고, Posmit은 동기화 시점의 상태를 캐시해 보여줍니다.
| 상태 | 의미 | 발송 가능 여부 |
|---|---|---|
NONE | 검수 전 | 불가 |
INSPECTING | 검수 중 | 불가 |
APPROVED | 승인 | 가능 |
REJECTED | 반려 | 불가 — 반려 사유는 comments 필드로 확인할 수 있습니다. |
검수 상태는 마지막 동기화 시점의 값입니다. 공급자 콘솔에서 승인이 났더라도 동기화 전에는 Posmit에 반영되지 않으므로, 검수 결과가 나온 뒤에는 동기화를 한 번 실행해 주세요.
발송 연결 — 알림톡 템플릿 바인딩
알림톡 발송은 템플릿의 templateCode 발송 경로를 그대로 사용하되, 한 단계가 더 있습니다.
채널이 kakao_alimtalk인 Posmit 템플릿의 버전에 승인된 알림톡 템플릿을 alimtalkTemplateId로 바인딩합니다.
바인딩이 버전 단위이므로, 각 버전이 어떤 승인 템플릿을 스냅샷했는지 이력이 남습니다.
발송(POST /v1/notifications) 시 서버는 다음을 수행합니다.
templateCode로 Posmit 템플릿의 최신 발행 버전을 로드합니다.- 버전에 바인딩된 알림톡 템플릿을 조회합니다. 바인딩된 템플릿이 존재하지 않으면 400 에러입니다.
- 검수 상태가
APPROVED가 아니면 발송을 차단합니다 — 400Alimtalk template is not approved (status=...). - 승인 상태이면 공급자 메타데이터를 요청에 자동 주입합니다.
| 주입 메타 | 내용 |
|---|---|
alimtalk_variables_json | templateVariables를 JSON으로 직렬화한 변수 값 |
aligo_sender_key / aligo_template_code | 알리고용 발신프로필 키·템플릿 코드 |
solapi_pf_id / solapi_template_id | SOLAPI용 발신프로필·템플릿 식별자 |
각 공급자 어댑터는 자신에게 해당하는 메타만 사용합니다. 요청하는 쪽에서는 일반 발송과 똑같이 templateCode와 templateVariables만 보내면 됩니다.
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": "kakao_alimtalk",
"recipient": { "address": "01012345678", "name": "홍길동" },
"content": {
"templateCode": "order-confirm",
"templateVariables": { "고객명": "홍길동", "주문번호": "A-1024" }
}
}'알림톡 본문의 변수 표기는 #{변수명}입니다. 변수 값은 공급자에 전달되어 공급자 측에서 치환되며,
값이 전달되지 않은 변수는 원본 표기가 그대로 남습니다. 승인받은 본문과 실제 발송 본문이 달라지면 공급자가 발송을 거절할 수 있으므로,
본문 수정이 필요하면 공급자 콘솔에서 새 템플릿을 등록해 다시 검수를 받아야 합니다.
템플릿 구성 참고
동기화된 카탈로그 항목에는 카카오 알림톡의 세부 구성이 그대로 담깁니다.
| 항목 | 값 |
|---|---|
| 메시지 유형 | BA(기본형) · EX(부가정보형) · AD(채널추가형) · MI(복합형) |
| 강조 유형 | NONE · TEXT(강조 표기) · IMAGE(이미지) · ITEM_LIST(아이템 리스트) |
| 버튼 | 웹링크(WL), 앱링크(AL), 배송조회(DS), 봇키워드(BK), 메시지전달(MD), 채널추가(BC), 봇전환(BT), 상담톡전환(AC) |
주의사항
- 정보성 메시지만 허용됩니다. 할인·쿠폰·이벤트 등 광고성 내용은 검수에서 반려됩니다. 광고성 발송이 필요하면 알림톡이 아닌 다른 채널을 사용하세요.
- 본문은 최대 1,000자입니다.
- 검수 상태·반려 사유는 동기화 시점의 캐시입니다. 발송 전 상태가 의심되면 먼저 동기화하세요.
- 바인딩 없이
kakao_alimtalk채널로 발송하면 공급자 메타 없이 일반 텍스트 발송이 시도되어 공급자 단계에서 실패할 수 있습니다. 알림톡 발송에는 항상 승인 템플릿 바인딩을 사용하세요.