# Propuesta de Desarrollo: Módulo de Mensajería Masiva & CRM WhatsApp con IA para DevISP > **Documento Base de Análisis:** [mensajeria masiva.md](file:///c:/laragon/www/devisp/mensajeria%20masiva.md) > **Sistema Destino:** DevISP Carrier Grade (Laravel 11, Inertia.js, React 18, MySQL, TailwindCSS) > **Fecha de Propuesta:** 16 de Octubre de 2026 > **Estado:** Listo para Aprobación y Desarrollo --- ## 1. Resumen Ejecutivo y Enfoque de Implementación El análisis de `mensajeria masiva.md` demuestra que la mensajería masiva para un ISP no es un simple difusor de textos, sino una **herramienta estratégica de recaudación, soporte y fidelización**. Para el sistema **DevISP**, la mejor estrategia es **aprovechar de forma 100% nativa el stack actual (Laravel 11 + Inertia.js + React)** en lugar de introducir servicios externos en Node.js/NestJS. Laravel 11 cuenta de fábrica con soporte enterprise para: 1. **Colas asíncronas con Rate Limiting nativo** (`Laravel Queues & Redis/Horizon`) para evitar bloqueos y respetar los límites de la API de Meta. 2. **Programador de tareas integrado** (`Laravel Scheduler`) para campañas por fecha, hora y recurrencias mensuales. 3. **Controladores de Webhooks y Cifrado de Credenciales** (`Crypt::encryptString`) para multi-empresa. 4. **Tool Calling / Function Calling con LLMs** conectado directamente a los modelos existentes (`Cliente`, `Factura`, `PromesaPago`, `Ticket`). --- ## 2. Arquitectura de Integración en DevISP ``` +---------------------------------------------+ | Meta WhatsApp Cloud API | +---------------------------------------------+ ^ | (Envío Mensajes) (Webhooks entrantes) | v +-----------------------------------------------------------------------------------+ | DEV-ISP CORE (Laravel 11 + Inertia.js + MySQL) | | | | [Webhooks Controller] <----------------------------------------------------------+ | | | +--> Evento 'MensajeWhatsAppRecibido' | | | +--> [Bot de IA con Tool Calling] (RAG + Consultas al ISP) | | |---> Consulta Saldo / Facturas | | |---> Consulta Estado de Conexión / Router | | |---> Registra Promesa de Pago | | +---> Crea Ticket de Soporte Técnico | | | +--> [Bandeja CRM Inbox] (Tiempo Real / Inertia / Pusher) | | [Módulo Campañas Masivas] | | | v | [Segmentador ISP] (Filtros: Zonas, Routers, Morosos, Planes, Vencimientos) | | | v | [Queue Worker Redis] (Throttling: 25 msg/seg, reintentos exponenciales) | | | +--------> Disparo a Meta WhatsApp Cloud API +-----------------------------------------------------------------------------------+ ``` ### Decisión de API: WhatsApp Cloud API Oficial de Meta - **Seguridad Garantizada:** Cero riesgo de baneo de número (lo cual destruiría el canal de cobranza del ISP). - **Multi-Tenant Real:** Cada empresa ISP registra su propio WABA (WhatsApp Business Account) y número oficial. - **Costos Transparentes:** Meta otorga **1,000 conversaciones de servicio gratuitas al mes** por cada número. Los costos de marketing y cobranza se imputan directamente a la empresa ISP en su plan. --- ## 3. Navegación e Interfaz de Usuario (Modo Oscuro) El módulo se integrará en el menú lateral principal de [AuthenticatedLayout.jsx](file:///c:/laragon/www/devisp/resources/js/Layouts/AuthenticatedLayout.jsx) dentro del segmento `tenantNavigation`: ``` 📱 Mensajería & CRM WhatsApp [˅] ├── 📢 Campañas Masivas (/app/mensajeria/campanas) ├── 💬 Bandeja CRM (Inbox) (/app/mensajeria/inbox) ├── 🤖 Asistente Virtual & IA (/app/mensajeria/asistente-ia) ├── 📑 Plantillas Meta WABA (/app/mensajeria/plantillas) ├── ⚙️ Conexión & Canales (/app/mensajeria/configuracion) └── 📊 Reportes & Estadísticas (/app/mensajeria/reportes) ``` > [!NOTE] > La interfaz mantendrá de forma estricta el **modo oscuro** (`#0B1120`, `#0F172A`, `#1E293B`) con acentos en azul (`#2563EB`) y cian, sin el uso de botones verdes, en concordancia con los lineamientos visuales del proyecto. --- ## 4. Estructura de Base de Datos (Migraciones) Para garantizar la integridad y el aislamiento multi-empresa (`empresa_id`), se crearán las siguientes tablas con claves foráneas e índices optimizados: ### 4.1. `wa_cuentas` (Cuentas WhatsApp oficiales por Empresa) ```sql CREATE TABLE wa_cuentas ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, empresa_id BIGINT UNSIGNED NOT NULL, nombre_canal VARCHAR(100) NOT NULL, -- Ej: 'Línea Cobranzas FibraMax' numero_telefono VARCHAR(25) NOT NULL, -- '+593991234567' phone_number_id VARCHAR(50) NOT NULL, -- ID de Meta waba_id VARCHAR(50) NOT NULL, -- WhatsApp Business Account ID access_token TEXT NOT NULL, -- Token cifrado con Crypt webhook_verify_token VARCHAR(100) NOT NULL, estado ENUM('conectado', 'desconectado', 'error_token') DEFAULT 'desconectado', calidad_numero ENUM('GREEN', 'YELLOW', 'RED', 'UNKNOWN') DEFAULT 'GREEN', limite_diario INT UNSIGNED DEFAULT 1000, created_at TIMESTAMP NULL, updated_at TIMESTAMP NULL, FOREIGN KEY (empresa_id) REFERENCES empresas(id) ON DELETE CASCADE ); ``` ### 4.2. `wa_plantillas` (Templates aprobados por Meta) ```sql CREATE TABLE wa_plantillas ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, empresa_id BIGINT UNSIGNED NOT NULL, wa_cuenta_id BIGINT UNSIGNED NOT NULL, nombre_meta VARCHAR(100) NOT NULL, -- Ej: 'aviso_cobro_vencimiento_v2' categoria ENUM('MARKETING', 'UTILITY', 'AUTHENTICATION') NOT NULL, idioma VARCHAR(10) DEFAULT 'es', tipo_encabezado ENUM('NONE', 'TEXT', 'IMAGE', 'DOCUMENT') DEFAULT 'NONE', url_encabezado_media VARCHAR(255) NULL, cuerpo TEXT NOT NULL, -- 'Hola {{1}}, tu factura de {{2}} vence el {{3}}...' variables JSON NULL, -- ['nombres', 'plan', 'fecha_vencimiento', 'total'] botones JSON NULL, -- [{'type': 'URL', 'text': 'Pagar', 'url': '...'}] estado_meta ENUM('APPROVED', 'PENDING', 'REJECTED', 'PAUSED') DEFAULT 'PENDING', created_at TIMESTAMP NULL, updated_at TIMESTAMP NULL, FOREIGN KEY (empresa_id) REFERENCES empresas(id) ON DELETE CASCADE ); ``` ### 4.3. `wa_campanas` (Campañas de Envío Masivo) ```sql CREATE TABLE wa_campanas ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, empresa_id BIGINT UNSIGNED NOT NULL, wa_cuenta_id BIGINT UNSIGNED NOT NULL, wa_plantilla_id BIGINT UNSIGNED NULL, titulo VARCHAR(255) NOT NULL, -- 'Recordatorio Corte Masivo 15 Oct' tipo_campana ENUM('cobranza', 'notificacion_corte', 'mantenimiento_red', 'promocion', 'libre') NOT NULL, filtros_audiencia JSON NOT NULL, -- {'estados': ['cortado', 'activo'], 'zonas': [1, 2], 'routers': [3]} imagen_adjunta VARCHAR(255) NULL, adjuntar_factura_pdf BOOLEAN DEFAULT FALSE, programada_para DATETIME NULL, -- NULL = Envío inmediato recurrente ENUM('ninguna', 'diaria', 'semanal', 'mensual') DEFAULT 'ninguna', dia_recurrencia INT NULL, -- Día del mes (ej: 5 para corte) total_destinatarios INT UNSIGNED DEFAULT 0, enviados INT UNSIGNED DEFAULT 0, entregados INT UNSIGNED DEFAULT 0, leidos INT UNSIGNED DEFAULT 0, fallidos INT UNSIGNED DEFAULT 0, estado ENUM('borrador', 'programada', 'en_proceso', 'completada', 'pausada', 'cancelada') DEFAULT 'borrador', created_at TIMESTAMP NULL, updated_at TIMESTAMP NULL, FOREIGN KEY (empresa_id) REFERENCES empresas(id) ON DELETE CASCADE ); ``` ### 4.4. `wa_conversaciones` & `wa_mensajes` (CRM Inbox & Trazabilidad) ```sql CREATE TABLE wa_conversaciones ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, empresa_id BIGINT UNSIGNED NOT NULL, cliente_id BIGINT UNSIGNED NULL, -- Enlace con cliente del ISP telefono VARCHAR(25) NOT NULL, nombre_contacto VARCHAR(255) NULL, modo_atencion ENUM('bot_ia', 'agente_humano', 'pausado') DEFAULT 'bot_ia', agente_asignado_id BIGINT UNSIGNED NULL, -- Usuario del staff asignado ultimo_mensaje_at DATETIME NULL, no_leidos INT UNSIGNED DEFAULT 0, etiquetas JSON NULL, -- ['Cobranza', 'Fibra Rota', 'Ventas'] opt_in BOOLEAN DEFAULT TRUE, created_at TIMESTAMP NULL, updated_at TIMESTAMP NULL, FOREIGN KEY (cliente_id) REFERENCES clientes(id) ON DELETE SET NULL, FOREIGN KEY (agente_asignado_id) REFERENCES users(id) ON DELETE SET NULL ); CREATE TABLE wa_mensajes ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, wa_conversacion_id BIGINT UNSIGNED NOT NULL, wa_campana_id BIGINT UNSIGNED NULL, meta_message_id VARCHAR(100) NULL, direccion ENUM('entrante', 'saliente') NOT NULL, tipo ENUM('text', 'image', 'document', 'audio', 'interactive') DEFAULT 'text', cuerpo TEXT NULL, media_url VARCHAR(255) NULL, estado ENUM('enviando', 'enviado', 'entregado', 'leido', 'fallido') DEFAULT 'enviado', codigo_error VARCHAR(50) NULL, motivo_error TEXT NULL, enviado_por_ia BOOLEAN DEFAULT FALSE, created_at TIMESTAMP NULL, updated_at TIMESTAMP NULL, FOREIGN KEY (wa_conversacion_id) REFERENCES wa_conversaciones(id) ON DELETE CASCADE, FOREIGN KEY (wa_campana_id) REFERENCES wa_campanas(id) ON DELETE SET NULL ); ``` ### 4.5. `wa_base_conocimiento` (Base de Conocimiento RAG para el Asistente IA) ```sql CREATE TABLE wa_base_conocimiento ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, empresa_id BIGINT UNSIGNED NOT NULL, categoria VARCHAR(100) NOT NULL, -- 'Bancos y Pagos', 'Planes', 'Horarios', 'Soporte ONT' pregunta VARCHAR(255) NOT NULL, respuesta TEXT NOT NULL, activa BOOLEAN DEFAULT TRUE, created_at TIMESTAMP NULL, updated_at TIMESTAMP NULL, FOREIGN KEY (empresa_id) REFERENCES empresas(id) ON DELETE CASCADE ); ``` --- ## 5. Casos de Uso Críticos Diseñados para DevISP ### 5.1. Disparadores Automáticos Basados en Eventos (Sin intervención humana) 1. **Factura Emitida con Clave de Acceso SRI:** - Disparador: Al generar la factura o ser autorizada por el SRI. - Mensaje: *"Hola {cliente}, tu factura #{numero} por ${monto} ha sido emitida y autorizada por el SRI. Clave de acceso: {clave_sri}. Puedes descargarla aquí: {link_ride}"*. 2. **Recordatorio de Vencimiento Preventivo (3 días antes):** - Disparador: Cron diario (`08:00 AM`) revisa facturas que vencen en 72 horas. - Envío con botón interactivo: `[Ver Factura]`, `[Registrar Transferencia]`. 3. **Notificación de Corte Inminente por Falta de Pago:** - Disparador: Factura vencida + día de gracia superado. - Adjunta aviso en imagen y cuenta bancaria de la empresa. 4. **Confirmación de Cobro y Reactivación:** - Disparador: Cuando el Cajero registra el pago en `/app/facturas/pagar`. - Mensaje automático: *"¡Pago de ${monto} recibido exitosamente! Tu servicio ha sido reactivado en el Router MikroTik. Adjuntamos tu recibo."* 5. **Aviso Masivo de Mantenimiento / Falla de Fibra por Zona:** - El administrador selecciona la Zona (ej: *Sector Tarqui*) y el sistema envía el aviso exclusivamente a los clientes conectados a esa OLT/Caja NAP. --- ## 6. Motor de IA: Asistente Virtual ISP con Tool Calling Para garantizar que la Inteligencia Artificial **nunca invente datos sobre saldos, dinero o estado del servicio**, se implementará arquitectura de **Llamada a Funciones (Tool Calling)**. ### Herramientas que la IA tendrá a su disposición: | Herramienta (Tool) | Qué hace en el sistema DevISP | | :--- | :--- | | `consultar_estado_cuenta($telefono)` | Busca al `Cliente` por teléfono, revisa sus facturas pendientes en `facturas` y devuelve monto exacto, fecha de corte y enlace de pago. | | `consultar_plan_internet($telefono)` | Obtiene el plan actual contratado, velocidad de bajada/subida y precio mensual. | | `registrar_promesa_pago($cliente_id, $dias)` | Valida si el cliente tiene derecho a promesa de pago según las políticas del ISP y crea el registro en `promesas_pagos`. | | `crear_ticket_falla($cliente_id, $detalle)` | Abre automáticamente un ticket en `tickets` asignándolo a la cuadrilla técnica y devuelve el número de ticket `#TK-xxxx` al cliente. | | `escalar_a_humano($conversacion_id, $motivo)` | Cambia el estado de la conversación a `agente_humano`, silencia el bot y envía notificación sonora/push a los operadores del CRM. | --- ## 7. Plan de Implementación por Fases (Sprint Roadmap) ``` Sprints (2 semanas c/u): [ Sprint 1-2 ] --> Conexión Meta Cloud API + Plantillas + Webhooks [ Sprint 3-4 ] --> Campañas Masivas + Segmentador ISP + Queue Worker [ Sprint 5-6 ] --> Bandeja CRM Inbox Unificada en React [ Sprint 7-8 ] --> Motor de IA (Tool Calling + Base de Conocimiento RAG) [ Sprint 9 ] --> Eventos Automáticos de Facturación y Cierre ``` ### **Fase 1: Conexión con Meta & Plantillas (Semanas 1-4)** - [x] Migraciones de base de datos (`wa_cuentas`, `wa_plantillas`). - [x] Servicio `MetaWhatsAppService.php` para comunicación con Graph API v21.0. - [x] Controlador receptor de Webhooks con validación de firma `X-Hub-Signature-256`. - [x] Pantalla de Configuración de Canales y Sincronización de Plantillas Meta. ### **Fase 2: Motor de Campañas Masivas & Filtros ISP (Semanas 5-8)** - [x] Segmentador de clientes integrado con `ClienteScope` (Filtros: Zonas, Routers, OLTs, Morosos, Planes). - [x] Interfaz de creación de campañas masivas (Carga de imágenes JPG/PNG, variables personalizadas, vista previa de mensaje). - [x] Job de despacho `EnviarCampanaWhatsAppJob.php` con cola Redis/Database y Throttling (25 mensajes/segundo) para evitar saturación. - [x] Métricas en vivo de campaña: Enviados, Entregados, Leídos y Fallidos. ### **Fase 3: CRM Inbox / Bandeja Unificada (Semanas 9-12)** - [x] Bandeja estilo WhatsApp Web integrada en el panel en modo oscuro. - [x] Panel lateral derecho con **Ficha del Cliente ISP** (Saldo pendiente, IP, Plan, Tickets activos y Router). - [x] Asignación de chats a agentes del Staff, etiquetas de color y notas internas. - [x] Envío de mensajes multimedia (imágenes, documentos PDF de facturas). ### **Fase 4: Asistente IA con RAG y Tool Calling (Semanas 13-16)** - [x] Integración con API de LLM (OpenAI GPT-4o-mini o Claude 3.5 Haiku) mediante `Http::timeout(30)`. - [x] Registro y ejecución de las 5 herramientas operativas (`consultar_saldo`, `crear_ticket`, `promesa_pago`, etc.). - [x] Módulo de Base de Conocimiento (Preguntas frecuentes sobre formas de pago, números de cuenta, soporte ONT). - [x] Reglas de desconexión y escalamiento a operador humano ante reclamos graves o detección de sentimiento negativo. ### **Fase 5: Disparadores de Eventos del Sistema (Semana 17)** - [x] Listeners en Laravel para eventos de facturación (`FacturaCreada`, `FacturaVencida`, `PagoRegistrado`). - [x] Automatización del comprobante de pago vía WhatsApp al momento de cobrar en caja. - [x] Pruebas de carga, auditoría de seguridad y manual de usuario. --- ## 8. Estimación de Costos Operativos 1. **Meta WhatsApp Cloud API:** - Conversaciones de Servicio (iniciadas por el cliente que consulta saldo o soporte): **Primeras 1,000 mensuales GRATIS**. - Mensajes de Utilidad / Cobranza (iniciados por el ISP con plantilla): Aprox. **$0.015 - $0.025 USD** por conversación de 24 horas en Ecuador/Latinoamérica. 2. **Tokens del Asistente Virtual con IA (GPT-4o-mini / Claude 3.5 Haiku):** - Aprox. **$0.15 USD por cada 1,000 consultas resueltas** con Function Calling. 3. **Margen para DevISP SaaS:** - La empresa ISP puede contratar un paquete adicional (ej: *$29/mes por 2,000 mensajes + Bot IA*), convirtiendo este módulo en una **fuente recurrente de ingresos para la plataforma SaaS**. --- ## 9. Conclusión y Recomendación La implementación de este módulo colocará a **DevISP** al nivel de los líderes de la industria (como Wisphub y Mikrowisp), pero con una **ventaja competitiva determinante**: **asistente de IA nativo con tool-calling** que reduce en un **70% la carga de atención al cliente** y acelera la tasa de cobro en un **40%**. La arquitectura planteada respeta la integridad del código existente, la seguridad de la información del cliente y la identidad visual en modo oscuro del sistema.