카카오 알림톡 템플릿 관리하기

카카오 알림톡은 사전에 검수된 알림톡 템플릿을 기반으로 발송됩니다. 센드온 SDK는 카카오 알림톡 템플릿을 쉽게 생성, 조회, 관리할 수 있는 기능을 제공합니다. 이 문서에서는 알림톡 템플릿 관리와 관련된 주요 기능들을 설명합니다.

알림톡 템플릿 생성
설명
새로운 알림톡 템플릿을 생성합니다. 생성된 알림톡 템플릿은 검수를 거쳐야 발송에 사용할 수 있습니다.
요청 예제
async function createTemplate() {
const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
const result = await sendon.kakao.createTemplate(sendProfileId, {
templateName: '카드 승인 알림',
templateContent: '안녕하세요 #{이름}님, 카드 승인이 완료되었습니다.\n사용처: #{사용처}\n일시: #{일시}',
templateMessageType: 'BA', // BA, EX, AD, MI
templateEmphasizeType: 'TEXT', // NONE, TEXT, IMAGE, ITEM_LIST
templateTitle: '123,456원',
templateSubtitle: '승인금액',
buttons: [
{
name: '자세히 보기',
type: 'WL', // 웹 링크
urlMobile: 'https://example.com/welcome',
urlPc: 'https://example.com/welcome',
},
],
});
console.log('템플릿 생성 결과:', JSON.stringify(result, null, 2));
return result;
}
파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
sendProfileId | string | 채널 ID | 필수 |
templateName | string | 템플릿 이름 (선택이지만 실무에서는 필수 입력 권장) | 선택 |
templateContent | string | 템플릿 본문 내용 | 필수 |
templateMessageType | string | 템플릿 메시지 타입 (BA , EX , AD , MI ) | 선택 |
templateEmphasizeType | string | 강조 표기 타입 (NONE , TEXT , IMAGE , ITEM_LIST ) | 선택 |
templateTitle | string | 강조 표기형 제목 (TEXT 타입 사용 시 필수) | 선택 |
templateSubtitle | string | 강조 표기형 부제목 (TEXT 타입 사용 시 필수) | 선택 |
templateExtra | string | 부가 정보 (EX , MI 타입에서 사용) | 선택 |
templateImageUrl | string | 이미지 강조형(IMAGE )에서 사용할 이미지 URL | 선택 |
templateImageName | string | 이미지 파일명 (이미지 강조형) | 선택 |
securityFlag | boolean | 보안 템플릿 여부 (true 설정 시 보안 강조) | 선택 |
buttons | array | 버튼 정보 배열 (최대 5개) | 선택 |
fallback | object | 카카오 메시지 실패 시 대체 문자 설정 (type , senderNumber 등) | 선택 |
버튼 파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
name | string | 버튼 텍스트 | 필수 |
type | string | 버튼 타입 (WL , AL , BK , MD , DS , AC ) | 필수 |
ordering | number | 버튼 노출 순서 (0부터 시작, 미입력 시 생성 순서) | 선택 |
urlMobile | string | 모바일 링크 URL (WL , AL 사용 시) | 조건부 필수 |
urlPc | string | PC 링크 URL (WL , AL 사용 시) | 조건부 필수 |
schemeAndroid | string | Android 앱 딥링크 (AL 사용 시) | 조건부 필수 |
schemeIos | string | iOS 앱 딥링크 (AL 사용 시) | 조건부 필수 |
응답 예시
{
"code": 200,
"message": "성공",
"data": {
"id": "생성된_템플릿ID",
"profileId": "채널(발신프로필)ID",
"templateName": "회원가입 완료 안내",
"status": "NEED_REVIEW",
"templateMessageType": "BA",
"templateEmphasizeType": "TEXT",
"templateContent": "안녕하세요 #{이름}님, 회원가입이 완료되었습니다.\n가입일시: #{가입일시}",
"createdAt": "2025-01-01T00:00:00.000Z"
}
}
알림톡 템플릿 수정
설명
검수 전 상태의 템플릿을 수정합니다. 검수가 완료된 템플릿은 수정할 수 없습니다.
요청 예제
async function updateTemplate() {
const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
const templateId = TEMPLATE_ID; // 템플릿 ID
const result = await sendon.kakao.updateTemplate(sendProfileId, templateId, {
templateName: '회원가입 완료 안내 (수정)',
templateContent: '안녕하세요 #{이름}님, 회원가입이 완료되었습니다.\n가입일시: #{가입일시}\n감사합니다.',
templateEmphasizeType: 'TEXT',
buttons: [
{
name: '홈으로 가기',
type: 'WL',
urlMobile: 'https://example.com/home',
urlPc: 'https://example.com/home',
},
],
});
console.log('템플릿 수정 결과:', JSON.stringify(result, null, 2));
return result;
}
파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
sendProfileId | string | 채널 ID | 필수 |
templateId | string | 템플릿 ID | 필수 |
templateName | string | 템플릿 이름 | 선택 |
templateContent | string | 템플릿 내용 | 선택 |
templateEmphasizeType | string | 강조 표기 타입 (NONE, TEXT, IMAGE) | 선택 |
templateTitle | string | 강조 표기형 title (TEXT 타입에서만 사용) | 선택 |
templateSubtitle | string | 강조 표기형 subtitle (TEXT 타입에서만 사용) | 선택 |
templateExtra | string | 부가 정보 | 선택 |
buttons | array | 버튼 정보 배열 (최대 5개) | 선택 |
응답 예시
{
"code": 200,
"message": "성공"
}
알림톡 템플릿 목록 조회
설명
등록된 카카오 알림톡 템플릿 목록을 조회합니다.
요청 예제
async function getTemplates() {
const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
const result = await sendon.kakao.getTemplates(sendProfileId, {
limit: 10, // 조회할 최대 템플릿 수
// 선택적 파라미터
// status: 'APPROVED', // 특정 상태의 템플릿만 조회
// sort: 'CREATED_AT', // 정렬 기준
// keyword: '회원가입', // 검색 키워드
// nextCursor: 'cursor_value' // 페이징을 위한 커서 값
});
console.log('템플릿 목록:', JSON.stringify(result, null, 2));
return result;
}
파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
sendProfileId | string | 채널 ID | 필수 |
options.limit | number | 조회할 최대 템플릿 수 | 선택 |
options.status | string | 특정 상태의 템플릿만 조회 (NEED_REVIEW, IN_REVIEW, APPROVED, REJECTED, DORMANT, DELETED) | 선택 |
options.sort | string | 정렬 기준 (CREATED_AT, RECENT_USED) | 선택 |
options.keyword | string | 검색 키워드 | 선택 |
options.nextCursor | string | 페이징을 위한 커서 값 | 선택 |
응답 예시
{
"code": 200,
"message": "성공",
"data": {
"templates": [
{
"id": "템플릿ID_1",
"profileId": "채널(발신프로필)ID",
"templateCode": "템플릿코드_1",
"templateName": "회원가입 안내",
"status": "APPROVED",
"templateMessageType": "BA",
"templateContent": "안녕하세요 #{이름}님, 회원가입이 완료되었습니다.",
"createdAt": "2023-01-01T00:00:00.000Z"
},
{
"id": "템플릿ID_2",
"profileId": "채널(발신프로필)ID",
"templateCode": "템플릿코드_2",
"templateName": "주문 완료 안내",
"status": "APPROVED",
"templateMessageType": "BA",
"templateContent": "#{이름}님, 주문이 완료되었습니다.",
"createdAt": "2023-01-02T00:00:00.000Z"
}
],
"nextCursor": "next_cursor_value"
}
}
알림톡 템플릿 상세 조회
설명
특정 템플릿의 상세 정보를 조회합니다.
요청 예제
async function getTemplateDetails() {
const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
const templateId = TEMPLATE_ID; // 템플릿 ID
const result = await sendon.kakao.getTemplate(sendProfileId, templateId);
console.log('템플릿 상세 정보:', result);
return result;
}
파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
sendProfileId | string | 채널 ID | 필수 |
templateId | string | 템플릿 ID | 필수 |
응답 예시
{
"code": 200,
"message": "성공",
"data": {
"id": "템플릿ID",
"profileId": "채널(발신프로필)ID",
"templateCode": "템플릿코드",
"templateName": "회원가입 안내",
"status": "APPROVED",
"templateMessageType": "BA",
"templateEmphasizeType": "TEXT",
"templateContent": "안녕하세요 #{이름}님, 회원가입이 완료되었습니다.\n가입일시: #{가입일시}",
"buttons": [
{
"name": "자세히 보기",
"type": "WL",
"urlMobile": "https://example.com",
"urlPc": "https://example.com"
}
],
"templateTitle": "회원가입 안내", // 강조 표기형(TEXT)에서만 사용
"templateSubtitle": "환영합니다", // 강조 표기형(TEXT)에서만 사용
"kepStatus": "O",
"createdAt": "2023-01-01T00:00:00.000Z",
"updatedAt": "2023-01-01T00:00:00.000Z",
"lastUsedAt": "2023-01-05T00:00:00.000Z"
}
}
알림톡 템플릿 삭제
설명
더 이상 사용하지 않는 템플릿을 삭제합니다.
요청 예제
async function deleteTemplate() {
const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
const templateId = TEMPLATE_ID; // 템플릿 ID
const result = await sendon.kakao.deleteTemplate(sendProfileId, templateId);
console.log('템플릿 삭제 결과:', result);
return result;
}
파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
sendProfileId | string | 채널 ID | 필수 |
templateId | string | 템플릿 ID | 필수 |
응답 예시
{
"code": 200,
"message": "성공"
}
알림톡 템플릿 검수 요청
설명
생성한 템플릿을 카카오에 검수 요청합니다.
요청 예제
async function requestTemplateReview() {
const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
const templateId = TEMPLATE_ID; // 템플릿 ID
const result = await sendon.kakao.requestReview(sendProfileId, templateId);
console.log('템플릿 검수 요청 결과:', result);
return result;
}
파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
sendProfileId | string | 채널 ID | 필수 |
templateId | string | 템플릿 ID | 필수 |
응답 예시
{
"code": 200,
"message": "성공"
}
알림톡 템플릿 검수 취소
설명
검수 중인 템플릿의 검수 요청을 취소합니다.
요청 예제
async function cancelTemplateReview() {
const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
const templateId = TEMPLATE_ID; // 템플릿 ID
const result = await sendon.kakao.cancelReview(sendProfileId, templateId);
console.log('템플릿 검수 취소 결과:', result);
return result;
}
파라미터
파라미터 | 타입 | 설명 | 필수 여부 |
---|---|---|---|
sendProfileId | string | 채널 ID | 필수 |
templateId | string | 템플릿 ID | 필수 |
응답 예시
{
"code": 200,
"message": "성공"
}
알림톡 템플릿 메시지 타입
알림톡 템플릿은 다음과 같은 메시지 타입을 지원합니다:
타입 코드 | 타입명 | 설명 |
---|---|---|
BA | 기본형 | 일반적인 텍스트 메시지 (최대 1,000자) |
EX | 부가 정보형 | 메시지 하단에 부가 정보를 포함하는 타입 |
AD | 채널 추가형 | 카카오톡 채널 추가 버튼을 포함하는 타입 |
MI | 복합형 | 부가 정보와 채널 추가를 모두 포함하는 타입 |
강조 표기 타입
templateEmphasizeType을 통해 메시지의 강조 표시 방식을 설정할 수 있습니다:
타입 | 설명 |
---|---|
NONE | 강조 표기 없음 |
TEXT | 강조 표기형 - title과 subtitle을 포함한 텍스트 강조 (templateTitle, templateSubtitle 사용) |
IMAGE | 이미지형 - 메시지에 이미지를 포함 |
알림톡 템플릿 상태
카카오 알림톡 템플릿은 다음과 같은 상태를 가질 수 있습니다:
상태 | 설명 |
---|---|
NEED_REVIEW | 검수 필요 - 템플릿 생성 후 검수 요청이 필요한 상태 |
IN_REVIEW | 검수 진행중 - 카카오에서 검수 중인 상태 |
APPROVED | 검수 통과 - 검수가 완료되어 알림톡 발송에 사용 가능한 상태 |
REJECTED | 검수 반려 - 검수가 반려된 상태, 수정 후 재검수 필요 |
DORMANT | 휴면 - 장기간 사용하지 않아 휴면 상태로 전환됨 |
DELETED | 삭제 - 삭제된 템플릿 |
알림톡 템플릿 휴면 정책
템플릿 등록 후 1년간 동일한 상태로 유지되거나 추가 발송이 없는 경우 휴면 상태로 전환됩니다. 휴면 상태로 1년 경과 시 템플릿이 삭제되며, 삭제된 템플릿은 복구할 수 없습니다. 휴면 상태 해제 후 30일간 알림톡 발송 이력이 없을 경우, 재휴면 처리됩니다.
주의사항
-
템플릿 검수
- 모든 알림톡 템플릿은 카카오의 검수를 거쳐야만 발송에 사용할 수 있습니다.
- 검수에는 일반적으로 영업일 기준 1-2일이 소요됩니다.
- 검수 반려 시 사유를 확인하고 수정하여 재검수를 요청해야 합니다.
-
템플릿 변수
- 템플릿에 변수를 사용할 경우
#{변수명}
형식으로 작성합니다. - 변수는 알림톡 발송 시 실제 값으로 치환됩니다.
- 변수명은 한글, 영문, 숫자, 특수문자 '_' 를 사용할 수 있습니다.
- 템플릿에 변수를 사용할 경우
-
템플릿 수정 제한
- 검수가 완료된 템플릿은 수정할 수 없습니다.
- 검수 완료된 템플릿을 변경하려면 새로운 템플릿을 생성해야 합니다.
-
템플릿 휴면 및 삭제
- 1년간 사용되지 않은 템플릿은 휴면 상태로 전환됩니다.
- 휴면 상태가 1년 이상 지속되면 템플릿이 자동 삭제됩니다.
- 휴면 상태 해제 후 30일간 사용하지 않으면 다시 휴면 상태로 전환됩니다.
-
템플릿 개수 제한
- 하나의 채널당 생성 가능한 템플릿 수는 제한되어 있습니다.
- 사용하지 않는 템플릿은 삭제하여 관리하는 것이 좋습니다.
관련 링크
Updated 20 days ago