카카오 템플릿 관리하기

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


템플릿 생성

설명

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

요청 예제

async function createTemplate() {
  const sendProfileId = SEND_PROFILE_ID; // 발신 프로필 ID (예: 'alipeople')
  
  const result = await sendon.kakao.createTemplate(sendProfileId, {
    templateName: '회원가입 완료 안내',
    templateContent: '안녕하세요 #{이름}님, 회원가입이 완료되었습니다.\n가입일시: #{가입일시}',
    templateMessageType: 'BA', // 기본형 템플릿
    templateEmphasizeType: 'TEXT', // 텍스트 강조
    templateTitle: '회원가입 안내', // 템플릿 제목
    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: 이미지, ITEM_LIST: 아이템 리스트)선택
templateTitlestring템플릿 제목선택
templateSubtitlestring템플릿 부제목선택
templateAdstring광고 문구 (AD, MI 타입에서 사용)선택
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": "2023-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, ITEM_LIST)선택
templateTitlestring템플릿 제목선택
templateSubtitlestring템플릿 부제목선택
templateAdstring광고 문구선택
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": "회원가입 안내",
    "templateSubtitle": "환영합니다",
    "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": "성공"
}

템플릿 상태

카카오 알림톡 템플릿은 다음과 같은 상태를 가질 수 있습니다:

상태설명
NEED_REVIEW검수 필요 - 템플릿 생성 후 검수 요청이 필요한 상태
IN_REVIEW검수 진행중 - 카카오에서 검수 중인 상태
APPROVED검수 통과 - 검수가 완료되어 알림톡 발송에 사용 가능한 상태
REJECTED검수 반려 - 검수가 반려된 상태, 수정 후 재검수 필요
DORMANT휴면 - 장기간 사용하지 않아 휴면 상태로 전환됨
DELETED삭제 - 삭제된 템플릿

템플릿 휴면 정책

템플릿 등록 후 1년간 동일한 상태로 유지되거나 추가 발송이 없는 경우 휴면 상태로 전환됩니다. 휴면 상태로 1년 경과 시 템플릿이 삭제되며, 삭제된 템플릿은 복구할 수 없습니다. 휴면 상태 해제 후 30일간 알림톡 발송 이력이 없을 경우, 재휴면 처리됩니다.

주의사항

  1. 템플릿 검수

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

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

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

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

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

관련 링크