# 카카오톡 연동 가이드

SmallClaw를 카카오톡 채널 챗봇 + "나에게 보내기" 알림으로 연동하는 방법입니다.

## 구조

```
사용자 → 카카오톡 채널 → 카카오 i 오픈빌더 → SmallClaw 서버
                                                  ↓
                                          AI 처리 (비동기)
                                                  ↓
                                       카카오 callbackUrl로 응답
```

- **REST API 키** — 앱 하나에 하나, 서버에 한 번만 설정
- **채널 주소** — 하나, 모든 사용자가 동일한 주소 사용
- **userId** — 카카오가 사용자마다 다른 값을 웹훅에 포함하여 전송

---

## 1단계: 카카오 개발자 앱 설정

1. [developers.kakao.com](https://developers.kakao.com) → **내 애플리케이션 → 앱 추가**
2. **앱 키 → REST API 키** 복사
3. **카카오 로그인 → 활성화** ON
4. **카카오 로그인 → 동의항목** → `talk_message` 필수 동의 활성화
5. **카카오 로그인 → Redirect URI** 추가:
   ```
   https://{서버주소}/api/kakao/auth/callback
   ```
6. **플랫폼 → Web** → 사이트 도메인 등록

---

## 2단계: SmallClaw 채널 설정

1. SmallClaw 웹 UI → **설정 → 채널 → 카카오톡** 선택
2. **REST API 키** 입력
3. **🟡 카카오 로그인** 버튼 클릭 → 브라우저 팝업에서 로그인 및 동의
4. **챗봇 채널 활성화** 체크
5. **저장**

---

## 3단계: 카카오 i 오픈빌더 설정

1. [i.kakao.com](https://i.kakao.com) → 챗봇 생성
2. **스킬** → **생성** → URL 입력:
   ```
   https://{서버주소}/api/kakao/webhook
   ```
3. 스킬 편집 → **대기 메시지** 입력 (예: `잠시 기다려 주세요...`)
4. **시나리오 → 폴백 블록 → 봇 응답 → 스킬데이터 사용** → 위 스킬 선택
5. **배포**

---

## 4단계: 카카오톡 채널 생성

1. [center-pf.kakao.com](https://center-pf.kakao.com) → 채널 생성
2. **채널 관리 → 1:1 채팅 활성화**
3. 오픈빌더 → **배포 → 운영채널** 에서 이 채널 연결

---

## 사용자 계정 매핑

채널 주소는 하나지만 SmallClaw 계정별로 연결 가능합니다.

1. 사용자가 채널(`pf.kakao.com/_{채널ID}/chat`)에서 메시지 전송
2. 서버 로그에서 userId 확인:
   ```
   [KakaoChannel] 웹훅 수신 userId=f4e1b2324f39...
   ```
3. SmallClaw 설정 → 채널 → 카카오톡 → **사용자 매핑 (userMap)** 에 입력:
   ```json
   {
     "f4e1b2324f39...": "papa",
     "다른userId": "cherry"
   }
   ```
4. 저장

매핑되지 않은 userId는 기본 admin 계정으로 연결됩니다.

---

## "나에게 보내기" 알림

OAuth 로그인 완료 후 서버 이벤트(AI 응답, 시스템 알림 등)를 본인 카카오톡으로 수신할 수 있습니다.

채널 설정 → **테스트 전송** 버튼으로 동작 확인 가능합니다.

---

## 동작 원리 (콜백 방식)

오픈빌더의 5초 제한을 우회하기 위해 비동기 콜백 방식을 사용합니다:

1. 카카오가 웹훅 요청 전송 (`callbackUrl` 포함)
2. SmallClaw가 즉시 `{ useCallback: true }` 응답
3. 백그라운드에서 AI 처리
4. 처리 완료 후 `callbackUrl`로 응답 전송 (최대 5분 유효)