whatsapp/README_LABORATORIO.md

# 🏥 Sistema de Chatbot WhatsApp - Laboratorio Ximena Caicedo

## 📋 Descripción

Sistema completo de chatbot para WhatsApp diseñado específicamente para el Laboratorio Ximena Caicedo en Cúcuta, Colombia. Incluye flujos conversacionales inteligentes, detección de horarios, gestión de estados, respuestas automáticas y mucho más.

## ✨ Características Principales

### 🤖 Bot Inteligente
- ✅ Procesamiento de Lenguaje Natural (NLP) básico
- ✅ Detección de palabras clave y sinónimos
- ✅ Respuestas automáticas contextuales
- ✅ Detección de sentimientos y frustración
- ✅ Escalamiento automático a asesores humanos

### 📅 Gestión de Horarios
- ✅ Detección automática de horario de atención
- ✅ Mensajes diferentes dentro/fuera de horario
- ✅ Configuración por día de la semana
- ✅ Soporte para horarios partidos (7-12, 14-17)

### 🗂️ Sistema de Menús
- ✅ Menú principal con 5 opciones
- ✅ Submenú de exámenes con información detallada
- ✅ Navegación intuitiva con números
- ✅ Opción de volver al menú anterior

### 🔄 Gestión de Estados
- ✅ Tracking del estado de cada conversación
- ✅ Flujos de agendamiento paso a paso
- ✅ Validación de datos del paciente
- ✅ Timeout automático de estados inactivos

### 💬 Respuestas Automáticas
- ✅ Más de 15 triggers configurados
- ✅ Respuestas por palabras clave
- ✅ Información de precios, horarios, ubicación
- ✅ Instrucciones para exámenes específicos

### 📸 Procesamiento de Multimedia
- ✅ Recepción de órdenes médicas
- ✅ Fotos de documentos de identidad
- ✅ Validación de imágenes
- ✅ Almacenamiento seguro

## 🚀 Instalación

### Requisitos Previos
- PHP 8.0 o superior
- MySQL 5.7 o superior
- Servidor web (Apache/Nginx)
- Cuenta de WhatsApp Business API

### Paso 1: Clonar/Descargar Archivos
Asegúrate de tener todos los archivos en tu servidor.

### Paso 2: Configurar Base de Datos
1. Crea una base de datos MySQL
2. Importa las tablas base si no existen:
```sql
-- Ejecutar los scripts SQL en este orden:
1. create_tables.sql (tablas base)
2. migrations/add_conversation_states.sql (tabla de estados)
3. setup_laboratorio_ximena.sql (datos del laboratorio)
```

### Paso 3: Configurar Credenciales
Edita `config/config.php` con tus credenciales:
```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'whatsapp_bot');
define('DB_USER', 'tu_usuario');
define('DB_PASS', 'tu_password');
```

### Paso 4: Ejecutar Instalación Automática
Visita en tu navegador:
```
http://tu-dominio.com/install_laboratorio.php
```

Este script:
- ✅ Verifica la conexión a la base de datos
- ✅ Crea la tabla de estados
- ✅ Importa menús y respuestas automáticas
- ✅ Verifica los servicios del sistema
- ✅ Muestra estadísticas finales

### Paso 5: Configurar WhatsApp API
1. Ve al panel de administración: `http://tu-dominio.com/index.php`
2. Navega a la pestaña "Configuración"
3. Ingresa:
   - Token de Acceso de WhatsApp Business API
   - Phone Number ID
   - Webhook Verify Token
   - API URL (por defecto: https://graph.facebook.com/v22.0/)

### Paso 6: Configurar Webhook
1. En Meta for Developers, configura el webhook:
   - URL: `https://tu-dominio.com/api/webhook.php`
   - Verify Token: El mismo que configuraste en el paso anterior
   - Suscripciones: `conversations`, `message_status`

## 📚 Estructura de Archivos

```
whatsapp/
├── services/
│   ├── BusinessHoursService.php      # Gestión de horarios
│   ├── ConversationStateService.php   # Estados de conversación
│   ├── NLPService.php                 # Procesamiento de lenguaje
│   ├── MenuService.php                # Gestión de menús
│   ├── PatientDataValidator.php      # Validación de datos
│   ├── BotServiceLab.php             # Servicio principal del bot
│   └── WhatsAppService.php           # Integración con WhatsApp API
├── api/
│   └── webhook.php                    # Recepción de mensajes
├── migrations/
│   └── add_conversation_states.sql   # Migración de tabla de estados
├── setup_laboratorio_ximena.sql      # Setup completo del laboratorio
├── install_laboratorio.php           # Instalador automático
└── README_LABORATORIO.md             # Este archivo
```

## 🎯 Flujos Implementados

### 1. Menú Principal
```
1️⃣ Agendar toma a domicilio
2️⃣ Consultar resultados
3️⃣ Información sobre exámenes
4️⃣ Ubicación y horarios
5️⃣ Hablar con un asesor
```

### 2. Submenú de Exámenes
```
1️⃣ Pruebas de embarazo
2️⃣ Prueba de paternidad
3️⃣ Helicobacter pylori (en aliento)
4️⃣ Orina de 24 horas
5️⃣ Solicitar cotización
0️⃣ Volver al menú principal
```

### 3. Palabras Clave Automáticas
- **"precio", "costo", "cuánto"** → Información de precios
- **"resultado", "resultados"** → Instrucciones para descargar
- **"horario", "cuando"** → Horarios de atención
- **"domicilio", "casa"** → Servicio a domicilio
- **"embarazo"** → Pruebas de embarazo
- **"paternidad", "ADN"** → Prueba de paternidad
- **"ubicación", "donde"** → Dirección y mapa
- **"asesor", "ayuda", "persona"** → Transferir a humano
- **"gracias"** → Mensaje de despedida
- **"menú", "inicio"** → Mostrar menú principal

## ⚙️ Configuración Avanzada

### Horarios de Atención
Edita en la base de datos o desde el panel:
```sql
UPDATE system_config 
SET config_value = '7:00-12:00,14:00-17:00'
WHERE config_key = 'business_hours_weekday';

UPDATE system_config 
SET config_value = '8:00-11:00'
WHERE config_key = 'business_hours_saturday';
```

### Agregar Nueva Respuesta Automática
Desde el panel de administración:
1. Ve a "Respuestas Automáticas"
2. Click en "Nueva Respuesta"
3. Configura:
   - Tipo de trigger (keyword, contains, exact, etc.)
   - Palabras clave (separadas por comas)
   - Texto de respuesta
   - Prioridad (1-100, mayor = más prioridad)

### Personalizar Menús
1. Ve a "Menús Configurados"
2. Click en el menú que quieres editar
3. Modifica el mensaje de bienvenida o las opciones
4. Guarda los cambios

## 🔧 Personalización

### Cambiar Nombre del Laboratorio
Edita `setup_laboratorio_ximena.sql` antes de instalar, reemplaza:
```sql
'Laboratorio Ximena Caicedo' → 'Tu Laboratorio'
```

### Modificar Valores de Exámenes
Edita los mensajes en la tabla `menu_options` o `autoresponses`:
```sql
UPDATE menu_options 
SET response_text = REPLACE(response_text, '$28.000', '$30.000')
WHERE response_text LIKE '%$28.000%';
```

### Agregar Nuevo Examen al Submenú
```sql
INSERT INTO menu_options (menu_id, option_key, option_order, option_text, response_type, response_text, is_active) 
VALUES 
(
    (SELECT id FROM menus WHERE menu_key = 'lab_menu_examenes'),
    '6',
    6,
    'Nuevo Examen',
    'text',
    'Información del nuevo examen...',
    1
);
```

## 📊 Monitoreo y Logs

### Ver Conversaciones Recientes
```sql
SELECT phone_number, message_text, direction, created_at 
FROM conversations 
ORDER BY created_at DESC 
LIMIT 50;
```

### Ver Estados Activos
```sql
SELECT phone_number, state, state_data, updated_at 
FROM user_states 
WHERE updated_at > DATE_SUB(NOW(), INTERVAL 1 HOUR);
```

### Ver Logs de Webhook
```sql
SELECT * FROM webhook_logs 
ORDER BY created_at DESC 
LIMIT 20;
```

## 🐛 Solución de Problemas

### El bot no responde
1. Verifica que el webhook esté configurado correctamente
2. Revisa los logs de webhook: `SELECT * FROM webhook_logs ORDER BY created_at DESC LIMIT 1`
3. Verifica las credenciales de WhatsApp API en "Configuración"

### Mensajes fuera de horario no funcionan
1. Verifica la zona horaria del servidor: `date_default_timezone_get()`
2. Revisa la configuración de horarios en `system_config`
3. Asegúrate de que `BusinessHoursService.php` existe

### Estados no se guardan
1. Verifica que la tabla `user_states` existe:
```sql
SHOW TABLES LIKE 'user_states';
```
2. Si no existe, ejecuta: `migrations/add_conversation_states.sql`

### NLP no detecta palabras clave
1. Revisa que las palabras estén en minúsculas en la BD
2. Verifica que `autoresponses` tiene registros activos:
```sql
SELECT COUNT(*) FROM autoresponses WHERE is_active = 1;
```
3. Aumenta la prioridad de la respuesta automática

## 📞 Soporte

Para soporte técnico o consultas:
- 📧 Email: soporte@ejemplo.com
- 📱 WhatsApp: +57 XXX XXX XXXX
- 💻 GitHub: [repositorio]

## 📝 Changelog

### Versión 1.0.0 (13 de enero de 2026)
- ✅ Implementación completa del sistema
- ✅ Menús del laboratorio
- ✅ 15+ respuestas automáticas
- ✅ Detección de horarios
- ✅ Gestión de estados
- ✅ NLP básico
- ✅ Validación de datos de pacientes
- ✅ Instalador automático

## 📜 Licencia

Este sistema fue desarrollado específicamente para Laboratorio Ximena Caicedo.
Todos los derechos reservados © 2026

---

**¡Sistema listo para producción! 🚀**

Para comenzar, ejecuta `install_laboratorio.php` y sigue las instrucciones.