# 친구톡 플러그인 (Friendtalk)

카카오 친구톡을 큐 기반으로 발송합니다. 알림톡과 달리 사전 등록 템플릿 코드 없이 자유 형식으로 발송 가능합니다.

---

## 목차

- [개요](#개요)
- [알림톡 vs 친구톡](#알림톡-vs-친구톡)
- [설정](#설정)
- [환경변수](#환경변수)
- [API](#api)
- [운영 팁](#운영-팁)

---

## 개요

| 항목       | 내용                                |
| ---------- | ----------------------------------- |
| 발송 방식  | 큐 기반 비동기 발송 (dispatch loop) |
| 프로바이더 | 카카오 비즈 (알리고 등 중계사 경유) |
| 템플릿     | 자유 형식 (사전 카카오 검수 불필요) |

> 기본 비활성화(`enabled: false`) 상태입니다. 카카오 비즈니스 채널 설정 후 활성화하세요.

---

## 알림톡 vs 친구톡

| 항목      | 알림톡                | 친구톡                         |
| --------- | --------------------- | ------------------------------ |
| 템플릿    | 카카오 사전 등록 필수 | 자유 작성                      |
| 수신 대상 | 카카오톡 사용자 전체  | 채널 친구 추가한 사용자만      |
| 광고 여부 | 정보성만 허용         | 정보성·광고성 모두 가능        |
| 발송 비용 | 상대적으로 저렴       | 상대적으로 비쌈                |
| 본문 형식 | 텍스트 · 버튼         | 텍스트 · 이미지 · 카드 등 다양 |

---

## 설정

`config.json`:

```json
{
    "enabled": false,
    "workers": 2,
    "ad_prefix": "(광고)",
    "default_ad": true
}
```

### 설정 항목

| 항목         | 기본값   | 설명                                |
| ------------ | -------- | ----------------------------------- |
| `enabled`    | `false`  | 플러그인 활성화 여부                |
| `workers`    | `2`      | 병렬 발송 워커 수                   |
| `ad_prefix`  | `(광고)` | 광고 메시지 앞에 자동 추가되는 문구 |
| `default_ad` | `true`   | 기본으로 광고 접두사 포함 여부      |

---

## 환경변수

친구톡 발송은 알림톡과 동일한 알리고 계정을 공유합니다.

```env
ALIMTALK_SENDER_KEY=카카오_채널_발신프로필_키
ALIGO_API_KEY=알리고_API_키
ALIGO_USER_ID=알리고_사용자_아이디
```

---

## API

기본 경로: `/v1/friendtalk`

| 메서드 | 경로    | 인증        | 설명        |
| ------ | ------- | ----------- | ----------- |
| `POST` | `/send` | 로그인 필요 | 친구톡 발송 |

### POST /send 요청 바디

```json
{
    "receiver": "01012345678",
    "content": "안녕하세요! 이번 주 특가 상품을 소개합니다.",
    "ad": true,
    "buttons": [
        {
            "name": "자세히 보기",
            "type": "WL",
            "url_mobile": "https://example.com/event"
        }
    ]
}
```

---

## 운영 팁

- 채널 친구 추가를 하지 않은 사용자에게는 발송 불가 → `failed` 처리
- 광고성 메시지는 `ad: true`로 설정하고 `(광고)` 접두사가 자동 추가됨
- 야간(오후 9시 ~ 오전 8시) 광고 메시지 발송 금지 (법적 규정)
- 정보성 메시지는 `ad: false`로 설정 시 야간 발송 가능