카카오 템플릿 관리하기

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


템플릿 생성

설명

새로운 알림톡 템플릿을 생성합니다. 생성된 템플릿은 검수를 거쳐야 발송에 사용할 수 있습니다.

요청 예제

async function createTemplate() {
  const sendProfileId = SEND_PROFILE_ID; // 채널 ID (예: 'alipeople')
  
  const result = await sendon.kakao.createTemplate(sendProfileId, {
    templateName: '카드 승인 알림',
    templateContent: '안녕하세요 #{이름}님, 카드 승인이 완료되었습니다.\n사용처: #{사용처}\n일시: #{일시}',
    templateMessageType: 'BA', // 기본형 템플릿
    templateEmphasizeType: 'TEXT', // 강조 표기형
    templateTitle: '123,456원', // 강조 표기형 제목 (최대 50자)
    templateSubtitle: '승인금액', // 강조 표기형 소제목 (최대 18-21자)
    buttons: [
      {
        name: '자세히 보기',
        type: 'WL', // 웹 링크
        urlMobile: 'https://example.com/welcome',
        urlPc: 'https://example.com/welcome',
      },
    ],
  });
  
  console.log('템플릿 생성 결과:', result);
  return result;
}

파라미터

파라미터타입설명필수 여부
sendProfileIdstring채널 ID필수
templateNamestring템플릿 이름필수
templateContentstring템플릿 내용필수
templateMessageTypestring템플릿 메시지 타입 (BA: 기본형, EX: 부가정보형, AD: 채널추가형, MI: 복합형)선택
templateEmphasizeTypestring강조 표기 타입 (NONE: 없음, TEXT: 강조 표기형, IMAGE: 이미지형)선택
templateTitlestring강조 표기형 title (최대 50자, TEXT 타입에서만 사용)선택
templateSubtitlestring강조 표기형 subtitle (최대 18-21자, TEXT 타입에서만 사용)선택
templateExtrastring부가 정보 (EX, MI 타입에서 사용)선택
buttonsarray버튼 정보 배열 (최대 5개)선택

버튼 파라미터

파라미터타입설명필수 여부
namestring버튼 텍스트필수
typestring버튼 타입 (WL: 웹링크, AL: 앱링크, BK: 봇키워드, MD: 메시지전달, DS: 배송조회, AC: 채널추가)필수
urlMobilestring모바일 링크 URL (WL, AL 타입에서 사용)조건부 필수
urlPcstringPC 링크 URL (WL, AL 타입에서 사용)조건부 필수
schemeAndroidstringAndroid 앱 URL 스키마 (AL 타입에서 사용)조건부 필수
schemeIosstringiOS 앱 URL 스키마 (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('템플릿 수정 결과:', result);
  return result;
}

파라미터

파라미터타입설명필수 여부
sendProfileIdstring채널 ID필수
templateIdstring템플릿 ID필수
templateNamestring템플릿 이름선택
templateContentstring템플릿 내용선택
templateEmphasizeTypestring강조 표기 타입 (NONE, TEXT, IMAGE)선택
templateTitlestring강조 표기형 title (TEXT 타입에서만 사용)선택
templateSubtitlestring강조 표기형 subtitle (TEXT 타입에서만 사용)선택
templateExtrastring부가 정보선택
buttonsarray버튼 정보 배열 (최대 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('템플릿 목록:', result);
  return result;
}

파라미터

파라미터타입설명필수 여부
sendProfileIdstring채널 ID필수
options.limitnumber조회할 최대 템플릿 수선택
options.statusstring특정 상태의 템플릿만 조회 (NEED_REVIEW, IN_REVIEW, APPROVED, REJECTED, DORMANT, DELETED)선택
options.sortstring정렬 기준 (CREATED_AT, RECENT_USED)선택
options.keywordstring검색 키워드선택
options.nextCursorstring페이징을 위한 커서 값선택

응답 예시

{
  "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;
}

파라미터

파라미터타입설명필수 여부
sendProfileIdstring채널 ID필수
templateIdstring템플릿 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;
}

파라미터

파라미터타입설명필수 여부
sendProfileIdstring채널 ID필수
templateIdstring템플릿 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;
}

파라미터

파라미터타입설명필수 여부
sendProfileIdstring채널 ID필수
templateIdstring템플릿 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;
}

파라미터

파라미터타입설명필수 여부
sendProfileIdstring채널 ID필수
templateIdstring템플릿 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. 템플릿 검수

    • 모든 알림톡 템플릿은 카카오의 검수를 거쳐야만 발송에 사용할 수 있습니다.
    • 검수에는 일반적으로 영업일 기준 1-2일이 소요됩니다.
    • 검수 반려 시 사유를 확인하고 수정하여 재검수를 요청해야 합니다.
  2. 템플릿 변수

    • 템플릿에 변수를 사용할 경우 #{변수명} 형식으로 작성합니다.
    • 변수는 알림톡 발송 시 실제 값으로 치환됩니다.
    • 변수명은 한글, 영문, 숫자, 특수문자 '_' 를 사용할 수 있습니다.
  3. 템플릿 수정 제한

    • 검수가 완료된 템플릿은 수정할 수 없습니다.
    • 검수 완료된 템플릿을 변경하려면 새로운 템플릿을 생성해야 합니다.
  4. 템플릿 휴면 및 삭제

    • 1년간 사용되지 않은 템플릿은 휴면 상태로 전환됩니다.
    • 휴면 상태가 1년 이상 지속되면 템플릿이 자동 삭제됩니다.
    • 휴면 상태 해제 후 30일간 사용하지 않으면 다시 휴면 상태로 전환됩니다.
  5. 템플릿 개수 제한

    • 하나의 채널당 생성 가능한 템플릿 수는 제한되어 있습니다.
    • 사용하지 않는 템플릿은 삭제하여 관리하는 것이 좋습니다.

관련 링크