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

<Image align="center" src="https://files.readme.io/94826973692cf1ce851e71b7952b79ac238cbda781403aff6ecb85fc7e5671a6-at_re_re.png" />

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

<Image align="center" src="https://files.readme.io/94d1f849ade584c9790b5e5985072416865e29c36f15e52a8a7035002c0d3d1e-at_re.png" />

<br />

## 알림톡 템플릿 생성

### 설명

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

### 요청 예제

```typescript
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` 사용 시)                                             | 조건부 필수 |

### 응답 예시

```json
{
  "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"
  }
}
```

## 알림톡 템플릿 수정

### 설명

검수 전 상태의 템플릿을 수정합니다. 검수가 완료된 템플릿은 수정할 수 없습니다.

### 요청 예제

```typescript
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개)                          | 선택    |

### 응답 예시

```json
{
  "code": 200,
  "message": "성공"
}
```

## 알림톡 템플릿 목록 조회

### 설명

등록된 카카오 알림톡 템플릿 목록을 조회합니다.

### 요청 예제

```typescript
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 | 페이징을 위한 커서 값                                                                    | 선택    |

### 응답 예시

```json
{
  "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"
  }
}
```

## 알림톡 템플릿 상세 조회

### 설명

특정 템플릿의 상세 정보를 조회합니다.

### 요청 예제

```typescript
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    | 필수    |

### 응답 예시

```json
{
  "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"
  }
}
```

## 알림톡 템플릿 삭제

### 설명

더 이상 사용하지 않는 템플릿을 삭제합니다.

### 요청 예제

```typescript
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    | 필수    |

### 응답 예시

```json
{
  "code": 200,
  "message": "성공"
}
```

## 알림톡 템플릿 검수 요청

### 설명

생성한 템플릿을 카카오에 검수 요청합니다.

### 요청 예제

```typescript
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    | 필수    |

### 응답 예시

```json
{
  "code": 200,
  "message": "성공"
}
```

## 알림톡 템플릿 검수 취소

### 설명

검수 중인 템플릿의 검수 요청을 취소합니다.

### 요청 예제

```typescript
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    | 필수    |

### 응답 예시

```json
{
  "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. **템플릿 개수 제한**
   * 하나의 채널당 생성 가능한 템플릿 수는 제한되어 있습니다.
   * 사용하지 않는 템플릿은 삭제하여 관리하는 것이 좋습니다.

## 관련 링크

* [카카오 알림톡 발송하기](https://sdk.sendon.io/docs/카카오-알림톡-발송하기)
* [카카오 채널 연동하기](https://sdk.sendon.io/docs/카카오-채널-연동하기)
* [카카오 채널 관리하기](https://sdk.sendon.io/docs/카카오-채널-관리하기)
* [카카오 비즈니스 메시지 가이드](https://business.kakao.com/info/bizmessage/)