WhatsApp AI 에이전트: 제로 의존성으로 구현한 다국어 리드 자격 검증

English, Hindi, Hinglish로 채팅하며 리드를 자격 검증(이름 → 니즈 → 예산 → 타임라인)하고, 자주 묻는 질문에 답하며, 약속을 예약하는 오픈 소스 WhatsApp 비즈니스 에이전트입니다. 무료 LLM 모드와 완전히 스크립팅된 폴백 기능을 갖추고 있습니다. 표준 라이브러리만 사용하므로 pip 설치가 필요 없습니다.

요약: 이 에이전트는 네 개의 Python 파일과 하나의 HTML 파일로 구성된 작동 가능한 WhatsApp 에이전트입니다. agent.py (~38KB)는 핵심 로직을 담당합니다: 발신자별 세션 관리, 고객의 작성 방식과 유사한 3개 국어 언어 감지, 이름/니즈/예산/타임라인에 대한 정규표현식(regex) 기반 추출, 날짜 및 시간 파싱, FAQ 감지, 그리고 스크립팅된 대화 상태 머신을 갖추고 있습니다. 여기에 선택적 무료 LLM 계층(Groq, Gemini, Mistral, OpenRouter 또는 로컬 Ollama)이 추가되어 응답 품질을 향상시키지만, 추출 과정은 신뢰성을 위해 규칙 기반으로 유지됩니다. webhook.py는 표준 라이브러리 HTTP 서버를 사용하여 이 에이전트를 Meta의 WhatsApp Cloud API, Twilio, JSON 채팅 API 및 실시간 리드 패널이 있는 데모 채팅 UI에 연결합니다. 어떠한 API 키도 필요 없이 전체 시스템은 규칙 기반 모드로 로컬에서 실행됩니다.

문제점: 고객들은 WhatsApp에 있는데, 도구는 그렇지 못하다

WhatsApp은 30억 명이 넘는 사용자를 보유하고 있으며, 인도와 같은 시장에서는 단순한 메시징 앱이 아니라 비즈니스 채널 그 자체입니다. 고객들은 가격을 문의하고, 운영 시간을 확인하며, 밤 11시에도 답변을 기대합니다. 일반적인 해결책들은 소규모 비즈니스에 모두 적합하지 않습니다: 직원을 고용해 전화기를 지켜보게 하거나, 값비싼 챗봇 플랫폼을 구매하거나, 메시지를 아침까지 답장 없이 방치하는 것입니다.

이 레포지토리는 네 번째 대안입니다: 오후 안에 읽고 이해할 수 있는 자체 호스팅 에이전트입니다. 플랫폼 종속성 없음, 메시지당 SaaS 비용 없음, 블랙박스도 없습니다. 고객의 언어로 반복적인 80% 작업(인사하기, 자격 검증, FAQ 처리, 예약)을 처리하며, 자신이 무엇을 하지 않는지에 대해서도 명확하게 밝힙니다 (Meta의 승인 절차를 우회한다고 주장하는 일은 절대 없으며, README에 따르면 그렇지 않다고 말하는 사람은 무언가를 팔고 있다는 뜻입니다).

작동 방식: 브레인(뇌), 제공자(Provider), 서버, UI

고객과 유사한 언어 감지

detect_language()는 각 메시지를 영어, 힌디어(데바나가리), 또는 힌글리시로 분류하며, 에이전트는 감지된 언어로 응답합니다. 구현은 두 가지 확인 절차를 거칩니다: 힌디어 스크립트를 위한 데바나가리 유니코드 범위 정규식([ऀ-ॿ])과 로마자로 작성된 90개 이상의 힌디어 단어 목록(namaste, chahiye, kal, baje, haan, kitna…)을 이용한 어휘집입니다. 두 개 이상의 어휘집 일치 또는 짧은 메시지에서의 한 번의 일치는 힌글리시로 분류됩니다. 이는 휴리스틱(heuristic)적이며 투명하고 디버깅이 가능하여, 이 작업에서는 블랙박스 분류기보다 우수합니다.

리드 추출: 인도 상거래를 이해하는 정규식

추출 계층은 이 저장소의 시장성을 보여주는 부분입니다. extract_name()은

각 발신자에게는 감지된 언어, 네 가지 리드 필드(이름, 니즈, 예산, 일정), 진행 중인 예약 정보, 현재 대화 단계, 그리고 메시지 기록을 담은 세션 딕셔너리가 제공됩니다. 이 기록은 메모리 제한을 위해 마지막 20턴으로 제한됩니다. 언어는 모든 메시지에서 재감지되지만, 메시지가 영어가 아니거나 첫 번째 턴일 경우에만 세션 기본값을 덮어쓰므로, 대화 중간의 영어 설명이 힌디어 사용자 세션을 변경하는 것을 방지합니다. 단계 머신은 인사 → 자격 검증 → 예약 → 확인 순서로 진행되지만, 추출기(extractor)도 기회적으로 작동합니다. 예를 들어, 사용자가 첫 메시지에서 예산을 자발적으로 언급하면, 다시 요청하지 않아도 포착됩니다. 이러한 기회적 추출이 에이전트가 폼을 채우는 느낌이 아니라 인간처럼 대화하게 만드는 요소입니다. 즉, 에이전트는 먼저 경청하고 빠진 것만 질문합니다.

두 가지 응답 모드, 하나의 추출 파이프라인

handle_message()는 스크립트된 상태 머신을 먼저 실행한 다음, 더 나은 답변을 위해 LLM(대규모 언어 모델)에 요청합니다. — 이는 설정되어 있고 도달 가능한 경우에만 해당됩니다:

reply, llm_used = self._scripted(s, text)

if not llm_used:
...

이러한 순서가 이 아키텍처의 최적의 결정입니다. 스크립트된 흐름은 정확하고 정해진 경로상의 답변을 보장하며, LLM은 의존성이 아니라 업그레이드 경로 역할을 합니다. 또한 리드 추출은 두 모드 모두에서 동일하게 실행됩니다. 따라서 리드 패널의 수치는 모델 출력에 절대 의존하지 않습니다. llm_provider.chat()는 오류 발생 시 예외를 발생시키는 대신 None을 반환하므로, 만료된 API 키가 대화를 중단시키기보다 스크립트된 모드로 조용히 전환됩니다. 세션 기록은 발신자당 20턴으로 제한되어 메모리를 관리합니다.

서버: Meta, Twilio, 그리고 데모 API

webhook.py는 다섯 개의 라우트(route)를 가진 stdlib ThreadingHTTPServer입니다: GET /webhook은 Meta의 인증 핸드셰이크(verification handshake)에 응답하며 (모드 + verify 토큰 + 챌린지 에코); POST /webhook은 Meta의 중첩된 entry → changes → messages 페이로드를 파싱하고 Graph API (v19.0)를 통해 응답하거나, WhatsApp 자격 증명(credentials)이 설정되지 않은 경우 [DRY-RUN] 라인을 기록합니다; POST /twilio는 폼 인코딩된 Twilio 수신 데이터를 받아 XML 이스케이프 처리된 TwiML을 반환하며; POST /api/chat은 에이전트를 JSON 형식으로 노출합니다 (reply, lead, booking, language, stage, llm); GET /api/status는 LLM 모드와 세션 수를 보고합니다. GET /는 데모 채팅 UI를 제공합니다.

직접 실행해보기 (Run it yourself)

python3 webhook.py
# http://localhost:8000/ 를 열어 — UI에서 채팅하고 리드 패널이 채워지는 것을 확인하세요

pip 설치는 필요 없습니다. 무료 LLM으로 응답을 업그레이드하려면 (선택 사항):

# Groq — 무료 티어, 신용카드 불필요: https://console.groq.com
export LLM_PROVIDER=groq
export LLM_MODEL=openai/gpt-oss-120b
...

무료 티어를 제공하는 다른 대안으로는 gemini (AI Studio), mistral, openrouter (:free 모델), ollama (로컬, 키 불필요)가 있습니다. 환경 변수는 브랜딩(BUSINESS_NAME/AGENT_NAME, 기본값은 VisionQuantech/Arjun), Meta 인증 토큰, 그리고 WhatsApp 자격 증명을 제어합니다. 유효성 검사(Sanity checks): python3 -m py_compile agent.py webhook.py llm_provider.py를 실행하고, Meta 핸드셰이크 및 채팅 API에 대한 README의 curl 레시피를 사용하세요.

솔직한 상태와 한계 (Honest status and limits)

상태: 로컬 데모 작동; 통합 준비 완료. 광고된 모든 기능이 작동합니다 — README의 주장은

• 실제 WhatsApp 사용을 위해서는 Meta의 승인이 필요합니다. 테스트 번호는 샌드박스 환경에서 즉시 작동하지만, 실제 운영(production) 단계에서는 WhatsApp Business Account와 승인된 표시 이름(display name), 그리고 Meta 검토가 필요하며, 무료 등급(~월 1,000회 대화)을 초과하는 경우 대화당 비용이 발생합니다. README에 이 내용이 명시되어 있어 임의로 처리하지 않습니다.
• 규칙 기반 추출은 한계가 있습니다. 정규 표현식(Regexes)은 일반적인 사례는 잘 처리하며, 문제가 생기면 눈에 띄게 실패하는 경향이 있어 미묘하게 놓치는 일은 적지만, 특이한 구문은 놓칠 수 있습니다. LLM 모드는 추출 품질보다는 답변의 질을 높이는 데 도움이 됩니다.
• 세션은 메모리 기반입니다. 서버를 재시작하면 대화 상태가 사라집니다. 운영 환경에서는 영구 저장소(persistent store)가 필요합니다.
• 검증 토큰을 변경하세요. 기본값(visionquantech123)이 리포에 있으며, README에서 이를 알려주고 있습니다.

로드맵 (Roadmap)

• 영구 세션(Persistent sessions): 재시작해도 대화가 손실되지 않도록 SQLite를 사용합니다.
• 캘린더 통합(Calendar integration): 예약 내용을 단순히 요약하는 것을 넘어 Google Calendar에 직접 기록합니다.
• 인간 인계(Human handoff): 상담원에게 전달할 때 대화 요약을 포함한 명시적인 에스컬레이션 경로를 제공합니다.
• 템플릿 메시징(Template messaging): Meta의 24시간 창 규칙에 맞춰 지원합니다.
• 분석(Analytics): 자격 검증 깔때기(qualification funnel), 이탈 단계, 채널별 예약 전환율 등을 분석합니다.
• 음성 메모(Voice notes): WhatsApp 오디오 메시지에 대한 음성 인식(speech-to-text) 기능을 지원합니다.

자주 묻는 질문 (Frequently asked questions)

WhatsApp AI 에이전트는 무엇을 하나요?

영어, 힌디어 또는 링글리시(Hinglish)로 고객과 채팅하며, 이름, 필요 사항, 예산, 일정 등을 수집하여 잠재 고객(leads)의 자격을 검증합니다. 또한 FAQ(가격, 영업시간, 위치, 서비스 등)에 답변하고 확인 요약과 함께 약속을 예약해 줍니다. 이는 Meta의 WhatsApp Cloud API, Twilio 또는 데모 웹 UI를 통해 작동합니다.

LLM 비용을 지불해야 하나요?

아닙니다. 키가 없어도 완전히 규칙 기반 스크립트 모드로 실행됩니다. 무료 등급 키(Groq, Gemini, Mistral, OpenRouter 또는 로컬 Ollama)를 사용하면 답변은 LLM이 생성하지만, 신뢰성을 위해 잠재 고객 추출은 규칙 기반으로 유지됩니다.

오늘 제 실제 WhatsApp 번호로 메시지를 보낼 수 있나요?

Meta의 샌드박스 테스트 번호는 즉시 작동합니다. 실제 운영 환경에서 자체 비즈니스 번호를 사용하려면 WhatsApp Business Account와 승인된 표시 이름(display name), 그리고 Meta의 검토가 필요하며, README에 그 과정이 솔직하게 설명되어 있습니다.

정말로 의존성이 제로인가요?

예 — 전체 앱은 Python 표준 라이브러리(http.server, urllib, re, json)만으로 구성되어 있습니다. pip install 단계가 존재하지 않습니다.

핵심 요약

이것은 실제로 읽을 수 있는 희귀한 'AI 에이전트' 저장소입니다: 약 38KB 분량의 투명한 대화 로직, 안전하게 실패하는(fails safe) 제공자 클라이언트, 그리고 Meta와 Twilio 모두와 통신할 수 있는 서버가 포함되어 있습니다. 또한 Meta가 요구하는 사항과 무료 등급이 무엇을 커버하는지에 대한 솔직한 문서도 갖추고 있습니다. 만약 고객들이 WhatsApp을 사용한다면, 이것은 오늘 밤 실행하고 내일 확장할 수 있는 신뢰할 만한 출발점입니다.

사용해 보세요: github.com/Shivay00001/whatsapp-ai-app — Shivam Kumar, VisionQuantech가 구축했습니다. 귀사의 비즈니스를 위해 WhatsApp 에이전트를 구축하고 배포하기를 원하십니까? [email protected]에 문의하세요.

저장소(Repo): showcase-whatsapp-ai-app — 오픈 소스, Shivam Kumar (VisionQuantech) 제공.