카카오톡 챗봇에 Claude API 연동하기 (2026)

카카오톡 챗봇은 채널 → 챗봇 빌더 → 스킬 서버를 통해 외부 API와 연동합니다. 스킬 서버에서 Claude API를 호출하면 자연어 응답이 가능한 카카오 챗봇을 만들 수 있고, Haiku 4.5 사용 시 월 1만 대화에 약 $13의 비용입니다. 이 가이드는 채널 셋업부터 배포까지 전체 흐름을 다룹니다.

다른 채널 통합 가이드: Slack 봇, Discord 봇. 한국어 챗봇 일반 패턴은 한국어 챗봇 만들기를 참고.

카카오 챗봇 구조 이해

카카오톡 챗봇 = 카카오 채널 + 챗봇 빌더 + 외부 스킬 서버.

사용자 메시지
   ↓
카카오톡 채널
   ↓
카카오 챗봇 빌더 (블록 매칭)
   ↓
스킬 서버 (당신의 백엔드)
   ↓
Claude API
   ↓
응답 (카카오 응답 형식)
   ↓
사용자

카카오 챗봇 빌더는 단순 응답을 GUI로 만들 수 있지만, 자연어 처리는 외부 스킬 서버 필요. Claude API를 스킬 서버에서 호출.

1단계: 카카오 채널 + 챗봇 셋업

1. https://center-pf.kakao.com/login 접속 → 채널 생성 (무료)
2. https://i.kakao.com/login 카카오 i 오픈빌더 접속 → 봇 생성
3. 채널 연결 → 자동응답 활성화

자세한 채널 셋업은 카카오 공식 가이드 참고. 여기서는 스킬 서버 + Claude 통합에 집중합니다.

2단계: 스킬 서버 (Python FastAPI)

카카오는 스킬 서버에 POST 요청을 보내고 5초 이내 응답 요구. Claude API 평균 응답 시간 1-2초이므로 OK.

from fastapi import FastAPI
from anthropic import Anthropic
import os

app = FastAPI()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

SYSTEM = """당신은 친절한 한국어 고객 지원 챗봇입니다.

규칙:
- 항상 존댓말 사용
- 응답은 200자 이내
- 모르는 내용은 "확인 후 답변드리겠습니다" 라고 응답
- 이모지는 사용하지 않음
"""

@app.post("/skill")
async def skill(payload: dict):
    """카카오 스킬 서버 endpoint."""
    user_text = payload["userRequest"]["utterance"]

    # Claude 호출 (Haiku 4.5 — 5초 SLA에 안전)
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=400,  # 200자 ≈ 400 tokens
        system=[
            {
                "type": "text",
                "text": SYSTEM,
                "cache_control": {"type": "ephemeral"},  # 90% 캐시 절감
            }
        ],
        messages=[{"role": "user", "content": user_text}],
    )

    answer = response.content[0].text

    # 카카오 응답 형식
    return {
        "version": "2.0",
        "template": {
            "outputs": [
                {
                    "simpleText": {
                        "text": answer
                    }
                }
            ]
        }
    }

배포: Vercel, Railway, Fly.io 등 무료 tier로 충분. HTTPS 필수 (카카오 요구사항).

3단계: 카카오 빌더에 스킬 등록

1. 오픈빌더 → 스킬 → 스킬 생성
2. URL: https://your-server.vercel.app/skill
3. 메서드: POST
4. 챗봇 시나리오 → 폴백 블록(자연어 처리) → 스킬 연결

이제 사용자가 메시지를 보내면 → 카카오가 스킬 서버 호출 → Claude 응답 → 사용자에게 반환.

4단계: 5초 SLA 안전 처리

카카오는 5초 이내 응답 못 받으면 timeout. 안전 패턴:

import asyncio

@app.post("/skill")
async def skill(payload: dict):
    user_text = payload["userRequest"]["utterance"]

    try:
        response = await asyncio.wait_for(
            call_claude(user_text),
            timeout=4.5  # 5초 안전 마진
        )
    except asyncio.TimeoutError:
        # 즉시 임시 응답 + 콜백
        return {
            "version": "2.0",
            "useCallback": True,  # 카카오 콜백 모드
            "data": {"text": "잠시만요, 답변 준비 중입니다..."}
        }

    return format_kakao_response(response.content[0].text)

카카오 콜백 모드: 5초 안에 임시 응답 후, 1분 안에 callback URL로 최종 응답. 긴 답변에 권장.

5단계: 비용 분석 (월 1만 대화)

평균 입력 50자 + 출력 200자 (≈ 100 + 400 tokens):

Without 최적화 (Sonnet 4.5)

• 1대화 = 100 input + 400 output
• 월 1만 = 1M input + 4M output
• 비용: (1 × $3) + (4 × $15) = $63/월

With 최적화 (Haiku 4.5 + 캐싱)

• Haiku 4.5: $0.80 / $4.00
• System prompt 캐시 hit-rate 80%
• 1대화 비용: 약 $0.0013
• 월 1만 = $13/월 (-79%)

With Batch (배치 분석/요약 시)

회원 분석, FAQ 자동 분류 등 야간 처리는 Batch API 50% 할인:

• 1만 대화 야간 분석 = $6.50/월

Claude API Cost Calculator에서 본인 트래픽 시뮬레이션.

자주 발생 4가지 문제

1. 5초 timeout 자주 발생

원인: Sonnet 4.5 사용 + max_tokens 너무 큼 해결: Haiku로 전환 + max_tokens=400 cap + asyncio timeout

2. 카카오 인증 실패

원인: 스킬 서버 URL이 HTTPS 아님 해결: Vercel/Railway 배포 (HTTPS 자동) 또는 자체 서버는 Let's Encrypt

3. 응답이 한국어가 아님

원인: System prompt가 영어 해결: System을 한국어로 통일. "한국어로만 답변" 명시.

4. 동일 사용자 대화 history 사라짐

원인: 카카오는 대화 컨텍스트 자동 유지 안 함 해결: userRequest.user.id를 키로 Redis/DB에 history 저장

import redis
r = redis.Redis()

async def call_claude_with_history(user_id: str, message: str):
    history_key = f"kakao:history:{user_id}"
    history = json.loads(r.get(history_key) or "[]")
    history.append({"role": "user", "content": message})

    response = await client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=400,
        system=[{"type": "text", "text": SYSTEM, "cache_control": {"type": "ephemeral"}}],
        messages=history[-12:],  # 최근 6턴만
    )

    answer = response.content[0].text
    history.append({"role": "assistant", "content": answer})
    r.setex(history_key, 3600, json.dumps(history))  # 1시간 TTL
    return answer

자주 묻는 질문

카카오 챗봇 빌더 단독으로 자연어 처리 가능한가?

부분적으로 가능. 챗봇 빌더의 "폴백 블록"이 키워드 매칭으로 처리하지만, 진짜 자연어 응답은 외부 스킬 서버 필요. Claude는 그 스킬 서버에서 호출.

카카오 챗봇 운영비 어디서 발생?

3곳: (1) 카카오 채널 무료 (월 메시지 수 따라 유료 tier), (2) Claude API 비용 (위 분석), (3) 스킬 서버 호스팅 (Vercel free tier 충분, 트래픽 많으면 ~$5-10/월).

카카오 비즈니스 채널 가입 필요한가?

개인 채널로도 챗봇 가능. 비즈니스 채널은 푸시 메시지나 광고 기능 사용 시 필요.

Slack/Discord 대비 카카오 챗봇이 나은 점은?

한국 사용자 도달률. Slack/Discord는 개발자 커뮤니티 한정, 카카오는 한국 거의 모든 사용자. B2C 한국 서비스에 적합.

한 번에 여러 사용자 처리 가능한가?

네. FastAPI는 비동기, Claude API는 분당 50 req tier 1 제한. 동시 50명 처리 가능. 더 필요하면 `429 rate_limit_error 가이드 참고.

다음 단계

• Claude API 슬랙봇 만들기
• Claude API 디스코드봇 만들기
• Claude API 비용 모니터링
• 10 Cost Quick Wins
• 한국어 챗봇 만들기 (일반)

Claude API Cost Optimization Masterclass ($59) — 카카오톡 챗봇 운영비 90% 절감 패턴 + 5초 SLA 안전 처리 + retry 미들웨어 + Pydantic 검증 코드. → Gumroad 구매 (₩77,000)

30일 환불 보장.