🦷 Asistente Virtual Odontológico con IA Híbrida (FSM + Gemini 2.5 Flash)
Agendamiento Clínico 24/7 sin Alucinaciones
Sistema backend autónomo desarrollado en TypeScript y Node.js para clínicas dentales y consultorios de salud. Automatiza el flujo completo de consulta de disponibilidad, extracción de fechas en lenguaje natural y reserva atómica de citas médicas en tiempo real vía WhatsApp.
- 💻 Repositorio GitHub: github.com/Alecwce/automatizacion-whatsapp-odontologia
- 📄 Licencia: MIT | Lenguaje: TypeScript | Testing: Vitest
🏗️ Arquitectura Híbrida: FSM Determinista + NLP con Gemini
A diferencia de los chatbots convencionales basados exclusivamente en prompts libres (que sufren de alucinación de fechas, lentitud y bucles), este proyecto implementa una arquitectura desacoplada:
flowchart TD User([📱 Paciente en WhatsApp]) <-->|WebSockets Baileys| Gateway[⚡ Event Listener WhatsApp] Gateway <--> Session[🧠 Gestor de Estados FSM] Session -->|Extracción de intención y fecha relativa| Gemini[🤖 Google Gemini 2.5 Flash] Gemini -->|Entidades estructuradas JSON| Session Session -->|Consulta disponibilidad en tiempo real| Calendar[📅 Google Calendar API v3] Calendar -->|Horarios libres sin colisiones| Session Session -->|Persistencia concurrente Promise.all| Storage[☁️ Google Sheets API v4 & Calendar]
- Comprensión de Lenguaje Natural (Google Gemini 2.5 Flash):
- Extrae intenciones y expresiones de tiempo complejas (“el próximo martes a las 4 de la tarde” o “este viernes temprano”).
- System Prompt inyectado con referencia temporal local de Perú (
America/Lima) para evitar desfases de zona horaria.
- Máquina de Estados Finita (FSM en TypeScript):
- Una vez identificada la intención, el flujo conversacional se vuelve 100% determinista. Controla la recolección estricta de: Nombre completo, DNI/identificación y motivo de consulta.
✨ Características Técnicas Destacadas
- 🛡️ Algoritmo Anti-Overbooking: Consulta directa con la API v3 de Google Calendar verificando intervalos libres y ventanas mínimas de separación entre turnos.
- ⚡ Escritura Concurrente y Atómica: Al confirmarse la cita, dispara en paralelo (
Promise.all) la reserva en Google Calendar y la inserción en Google Sheets para el equipo de recepción. - 🕒 Validación de Horario Comercial: Restricciones automatizadas que impiden agendamiento fuera de jornada laboral, feriados o domingos.
- 🔒 Seguridad Zero-Leak: Aislamiento total de credenciales de Google Cloud (
service-account.json) y tokens de sesión de WhatsApp (auth_info_baileys/).
🛠️ Stack Tecnológico
| Componente | Tecnología | Rol en el Proyecto |
|---|---|---|
| Runtime & Lenguaje | Node.js + TypeScript Strict | Tipado estricto y ejecución asíncrona |
| Motor de IA | Google Gemini 2.5 Flash | Comprensión semántica y extracción de entidades |
| Conector WhatsApp | Baileys (@whiskeysockets/baileys) | Conexión WebSocket ligera sin depender de API oficial cara |
| Integraciones Cloud | Google Calendar API + Google Sheets API | Gestión de agenda y CRM en hoja de cálculo |
| Testing | Vitest | Pruebas unitarias de la máquina de estados |