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:

-- 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:

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: messages, 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:

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:

'Laboratorio Ximena Caicedo' → 'Tu Laboratorio'

Modificar Valores de Exámenes

Edita los mensajes en la tabla menu_options o autoresponses:

UPDATE menu_options 
SET response_text = REPLACE(response_text, '$28.000', '$30.000')
WHERE response_text LIKE '%$28.000%';

Agregar Nuevo Examen al Submenú

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

SELECT phone_number, message_text, direction, created_at 
FROM conversations 
ORDER BY created_at DESC 
LIMIT 50;

Ver Estados Activos

SELECT phone_number, state, state_data, updated_at 
FROM user_states 
WHERE updated_at > DATE_SUB(NOW(), INTERVAL 1 HOUR);

Ver Logs de Webhook

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:

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:

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.