================================================================================ DOCUMENTACIÓN COMPLETA WhatsApp Bot Manager ================================================================================ Versión: 1.2.0 PHP: 8.2+ Estado: Producción Sistema completo de gestión de conversaciones de WhatsApp Business Desarrollado por U-Site.app ================================================================================ ÍNDICE ================================================================================ 1. Introducción 2. Manual de Usuario 3. Documentación Técnica 4. API REST Completa 5. Guía de Implementación 6. Casos de Uso 7. Entregables del Proyecto 8. Mantenimiento y Soporte ================================================================================ 1. INTRODUCCIÓN ================================================================================ ¿Qué es WhatsApp Bot Manager? ------------------------------- WhatsApp Bot Manager es una plataforma web completa para gestionar comunicaciones de WhatsApp Business. Permite a empresas automatizar respuestas, gestionar conversaciones en tiempo real, enviar mensajes masivos y mantener un control total sobre las interacciones con clientes. Características Principales ----------------------------- GESTIÓN DE CONVERSACIONES - Interfaz tipo WhatsApp Web responsive - Notificaciones en tiempo real con SSE (Server-Sent Events) - Soporte completo para multimedia (imágenes, videos, audio, documentos) - Búsqueda y filtrado de conversaciones - Indicadores de estado de mensajes (enviado, entregado, leído) AUTOMATIZACIÓN INTELIGENTE - Bot con respuestas automáticas configurables - Plantillas de mensaje aprobadas por WhatsApp - Menús interactivos con botones - Mensajes masivos con segmentación - Quick replies para respuestas rápidas SEGURIDAD Y CONTROL - Autenticación basada en base de datos - Protección contra ataques de fuerza bruta - Registro completo de actividades (logs) - Sistema de sesiones seguras - Configuración granular de permisos ANÁLISIS Y REPORTES - Dashboard con estadísticas en tiempo real - Gráficos de mensajes por día/hora - Estado de conversaciones (activas, resueltas, pendientes) - Exportación de datos a CSV - Métricas de rendimiento del bot Tecnologías Utilizadas ------------------------ Tecnología Versión Uso ------------------------------------------------------------------------ PHP 8.2+ Backend y lógica de negocio MariaDB 10.11+ Base de datos principal Redis 7.0+ Cache y gestión de colas JavaScript ES6+ Frontend interactivo Bootstrap 5.3.0 UI/UX responsive Docker 24.0+ Contenedorización Nginx 1.25+ Servidor web WhatsApp API v22.0 Integración con WhatsApp ================================================================================ 2. MANUAL DE USUARIO ================================================================================ 2.1. Acceso al Sistema ------------------------ Inicio de Sesión ---------------- 1. Accede a la URL de tu instalación (ej: https://tudominio.com) 2. Haz clic en "Iniciar Sesión" 3. Ingresa tus credenciales: - Usuario: admin (por defecto) - Contraseña: password123 (cámbiala tras el primer acceso) Recuperación de Contraseña --------------------------- 1. Haz clic en "¿Olvidaste tu contraseña?" 2. Ingresa tu correo electrónico registrado 3. Recibirás un enlace para restablecer tu contraseña 4. Crea una nueva contraseña segura (mínimo 8 caracteres) 2.2. Panel Principal (Dashboard) --------------------------------- Vista General ------------- Al iniciar sesión verás el dashboard con: ESTADÍSTICAS GENERALES - Total de usuarios - Mensajes recibidos (24h) - Mensajes enviados (24h) - Conversaciones activas GRÁFICO DE MENSAJES - Visualización por hora/día - Comparativa entrada vs salida - Tendencias de uso MENSAJES RECIENTES - Últimas 10 conversaciones - Vista previa del mensaje - Timestamp relativo 2.3. Gestión de Conversaciones -------------------------------- Interfaz de Chat ---------------- La interfaz principal replica WhatsApp Web con: PANEL IZQUIERDO (Lista de Conversaciones) - Buscar: Campo de búsqueda por nombre o número - Filtros: * Todos los mensajes * Solo no leídos - Lista ordenada por mensaje más reciente - Indicadores: * Punto azul = conversación no leída * Timestamp del último mensaje * Vista previa del contenido PANEL PRINCIPAL (Área de Chat) - Cabecera: * Avatar y nombre del usuario * Número de teléfono * Botones de acción (editar, eliminar) - Área de mensajes: * Mensajes propios (derecha, fondo verde claro) * Mensajes recibidos (izquierda, fondo blanco) * Timestamps en cada mensaje * Estados: checkmark enviado, doble checkmark entregado/leído - Barra de entrada: * Campo de texto para escribir * Botón de adjuntar archivos * Botón de respuestas rápidas * Botón de enviar Enviar Mensajes de Texto ------------------------- 1. Selecciona una conversación de la lista 2. Escribe tu mensaje en el campo inferior 3. Presiona Enter o haz clic en Enviar 4. El mensaje aparecerá inmediatamente en el chat Características de texto: - Soporte para emojis - Formato WhatsApp: * *texto* = negrita * _texto_ = cursiva * ~texto~ = tachado * `código` = monoespaciado - Saltos de línea con Shift + Enter - Envío con Enter Enviar Archivos Multimedia --------------------------- IMÁGENES 1. Haz clic en el botón Adjuntar 2. Selecciona "Imagen" 3. Elige una imagen desde tu dispositivo 4. Opcionalmente agrega un caption (texto) 5. Haz clic en "Enviar" Formatos soportados: JPG, PNG, GIF, WebP Tamaño máximo: 5 MB VIDEOS 1. Clic en Adjuntar > "Video" 2. Selecciona un video (máx 16MB) 3. Agrega caption opcional 4. Envía Formatos soportados: MP4, AVI, MOV, 3GP Tamaño máximo: 16 MB AUDIO Opción A - Grabar nota de voz: - Mantén presionado el botón del micrófono - Habla al micrófono - Suelta para enviar automáticamente - Desliza para cancelar Opción B - Subir archivo de audio: - Clic en Adjuntar > "Audio" - Selecciona archivo MP3, WAV, AAC, OGG - Envía directamente Tamaño máximo audio: 16 MB DOCUMENTOS 1. Clic en Adjuntar > "Documento" 2. Selecciona archivo (PDF, DOC, XLS, etc.) 3. El sistema detecta el tipo automáticamente 4. Envía Formatos soportados: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP Tamaño máximo: 100 MB Respuestas Rápidas (Quick Replies) ----------------------------------- Las respuestas rápidas te permiten enviar mensajes predefinidos con un solo clic: 1. Haz clic en el botón Respuestas Rápidas 2. Se desplegará un panel con dos pestañas: - Texto: Respuestas automáticas simples - Plantillas: Templates aprobados de WhatsApp 3. Selecciona la respuesta deseada 4. Se enviará automáticamente Editar respuestas rápidas: 1. Ve a Configuración > Respuestas Automáticas 2. Haz clic en "Nueva Respuesta" 3. Ingresa: - Palabra clave (trigger) - Mensaje de respuesta - Activa/Desactiva 4. Guarda los cambios Plantillas de WhatsApp ----------------------- Las plantillas son mensajes pre-aprobados por Meta que puedes usar: ENVIAR UNA PLANTILLA 1. En el chat, despliega Respuestas Rápidas 2. Ve a la pestaña "Plantillas" 3. Selecciona una plantilla aprobada 4. Si la plantilla tiene variables, se rellenarán automáticamente 5. La plantilla se envía instantáneamente GESTIONAR PLANTILLAS 1. Ve a Configuración > Plantillas de Mensaje 2. Verás una lista con: - Nombre de la plantilla - Estado: Aprobada | Pendiente | Rechazada - Idioma - Fecha de creación 3. Crear nueva plantilla: - Clic en "Nueva Plantilla" - Completa el formulario: * Nombre: identificador único (sin espacios) * Categoría: MARKETING, UTILITY, AUTHENTICATION * Idioma: es (Español) * Encabezado: Título opcional * Cuerpo: Mensaje principal (puede incluir variables {{1}}, {{2}}) * Pie: Texto al final opcional * Botones: Opcionales (CALL_TO_ACTION, QUICK_REPLY) - Enviar para aprobación - Meta revisará la plantilla (puede tardar 24-48h) IMPORTANTE: Solo puedes enviar plantillas APROBADAS por WhatsApp. Notificaciones en Tiempo Real ------------------------------- El sistema usa SSE (Server-Sent Events) para actualizaciones en tiempo real: - Nuevos mensajes: Aparecen automáticamente sin recargar - Notificaciones de escritura: "Usuario está escribiendo..." - Estados de mensaje: Cambios en tiempo real (entregado -> leído) - Toasts informativos: Alertas visuales en la esquina superior derecha Estados de conexión: - Verde: Conectado - Amarillo: Reconectando - Rojo: Desconectado Si pierdes conexión, el sistema intentará reconectar automáticamente cada 5 segundos. 2.4. Gestión de Usuarios -------------------------- Listar Usuarios --------------- 1. Ve a "Usuarios" en el menú principal 2. Verás una tabla con: - ID del usuario - Nombre - Número de teléfono - Estado (in_service, on_hold, completed) - Última interacción - Acciones (editar, eliminar, ver chat) Crear/Editar Usuario --------------------- 1. Haz clic en "Nuevo Usuario" 2. Completa el formulario: - Nombre: Nombre completo o identificador - Teléfono: Número con código de país (ej: 573001234567) - Email: Opcional - Notas: Información adicional 3. Guarda Editar: Haz clic en el icono de edición en la fila del usuario. Eliminar Usuario ---------------- 1. Haz clic en el icono de eliminar 2. Confirma la acción 3. ADVERTENCIA: Esto eliminará también todo el historial de conversaciones Exportar Usuarios ----------------- 1. Haz clic en "Exportar CSV" 2. Se descargará un archivo con todos los usuarios y sus datos 2.5. Mensajes Masivos (Broadcast) ----------------------------------- Enviar Mensaje Masivo ---------------------- 1. Ve a "Envío Masivo" en el menú 2. Configura el mensaje: - Tipo: Texto o Plantilla - Contenido: Escribe el mensaje o selecciona plantilla - Filtro de destinatarios: * Todos los usuarios * Solo usuarios activos (últimas 24h) * Lista personalizada (importar CSV) 3. Vista previa: Revisa cómo se verá el mensaje 4. Haz clic en "Enviar a todos" 5. El sistema procesará los envíos en segundo plano Limitaciones de WhatsApp: - Solo puedes enviar plantillas aprobadas a usuarios que no te han escrito en 24h - Respeta la ventana de 24 horas para mensajes libres - El sistema controlará automáticamente estos límites Seguimiento de Envíos ---------------------- En la sección "Historial de Envíos" puedes ver: - Fecha y hora del envío - Total de destinatarios - Enviados exitosos - Fallidos (con motivo) - Estado general 2.6. Bot Automatizado ---------------------- Configurar el Bot ----------------- 1. Ve a Configuración > Bot Automático 2. Activa/Desactiva el bot con el interruptor 3. Configura: - Mensaje de bienvenida: Primer mensaje al nuevo usuario - Mensaje de ausencia: Respuesta fuera de horario - Horario de atención: Define días y horas - Palabras clave: Triggers que activan respuestas Respuestas Automáticas ----------------------- CREAR RESPUESTA AUTOMÁTICA 1. Ve a Configuración > Respuestas Automáticas 2. Clic en "Nueva Respuesta" 3. Configura: - Trigger: Palabra o frase que activa la respuesta - Mensaje: Respuesta automática - Activo: On/Off - Prioridad: Orden de evaluación (1 = más alta) 4. Guarda Ejemplos de uso: - Trigger: hola, buenos días, buenas tardes Respuesta: ¡Hola! Bienvenido a [Empresa]. ¿En qué puedo ayudarte? - Trigger: horario, horarios, cuando abren Respuesta: Nuestro horario de atención es: Lunes a Viernes 9am-6pm - Trigger: precio, cuanto cuesta, costo Respuesta: Para información sobre precios, por favor visita [URL] TIPS PARA RESPUESTAS AUTOMÁTICAS EFECTIVAS - Usa múltiples triggers: hola,buenos días,buenas tardes,hey - Sé claro y conciso: Respuestas cortas son más efectivas - Incluye opciones: "Responde 1 para ventas, 2 para soporte" - Usa emojis: Hacen la conversación más amigable - Escalamiento: Indica cuándo un humano tomará la conversación Menús Interactivos ------------------ Los menús interactivos permiten crear flujos de conversación estructurados: CREAR MENÚ 1. Ve a Configuración > Menús Interactivos 2. Clic en "Nuevo Menú" 3. Configura: - Nombre del menú: Identificador interno - Mensaje principal: Texto que verá el usuario - Opciones (hasta 10): * ID: Número o letra * Texto: Descripción de la opción * Acción: Respuesta o submenu 4. Guarda Ejemplo de menú principal: --------------------------- Bienvenido a [Empresa] Por favor selecciona una opción: 1. Ventas 2. Soporte técnico 3. Información general 4. Hablar con un asesor Responde con el número de tu opción. 2.7. Configuración del Sistema -------------------------------- Configuración de WhatsApp -------------------------- 1. Ve a Configuración > WhatsApp API 2. Completa los campos: Datos de Meta Business: - App ID: ID de tu aplicación de Facebook - App Secret: Secreto de la aplicación - Business Account ID: ID de tu cuenta de negocio - Phone Number ID: ID del número de teléfono de WhatsApp - Access Token: Token de acceso permanente - Webhook Verify Token: Token para verificar el webhook URLs: - API URL: https://graph.facebook.com/v22.0/ - Webhook URL: https://tudominio.com/api/webhook.php 3. Haz clic en "Verificar Configuración" 4. Si todo está correcto, verás checkmarks en todos los checks 5. Guarda los cambios Configuración General --------------------- 1. Ve a Configuración > General 2. Ajusta: - Nombre de la empresa: Aparece en mensajes automáticos - Zona horaria: América/Bogota (por defecto) - Idioma: Español (es) - Límite de mensajes por minuto: Control de rate limiting - Retención de logs: Días que se guardan los registros - Activar notificaciones sonoras: Sonido al recibir mensaje 3. Guarda Gestión de Administradores --------------------------- 1. Ve a Configuración > Administradores 2. Lista de usuarios admin actuales 3. Crear nuevo admin: - Clic en "Nuevo Administrador" - Ingresa: * Nombre de usuario * Email * Contraseña (mínimo 8 caracteres) * Permisos: - Admin completo: Acceso total - Operador: Solo gestión de conversaciones - Visualizador: Solo lectura - Guarda 4. Eliminar admin: Clic en icono eliminar junto al usuario 2.8. Logs y Auditoría ---------------------- Ver Logs del Sistema -------------------- 1. Ve a Logs en el menú principal 2. Filtros disponibles: - Nivel: Error, Warning, Info, Debug - Fecha: Rango de fechas - Módulo: API, Bot, Webhook, Sistema 3. Tabla de logs muestra: - Timestamp - Nivel de severidad - Mensaje - Contexto (datos adicionales) Logs de Webhook ---------------- Los logs de webhook muestran cada interacción con WhatsApp: 1. Ve a Logs > Webhook 2. Cada entrada muestra: - Timestamp de recepción - Tipo de evento (message, status, etc.) - Datos del mensaje (JSON) - Respuesta del sistema - Tiempo de procesamiento Útil para: - Depurar problemas de recepción de mensajes - Ver mensajes duplicados - Auditar interacciones Exportar Logs ------------- 1. Selecciona los filtros deseados 2. Clic en "Exportar" 3. Descarga archivo CSV con los logs Limpiar Logs ------------ Para liberar espacio: 1. Ve a Logs > Limpieza 2. Selecciona: - Logs más antiguos de X días - Tipo específico 3. Confirma la eliminación ================================================================================ 3. DOCUMENTACIÓN TÉCNICA ================================================================================ 3.1. Arquitectura del Sistema ------------------------------- DIAGRAMA DE COMPONENTES ------------------------ FRONTEND +----------+ +-------------+ +----------------+ |conversations| chat_window | inicio.html | | .php | | .php | (landing) | +----------+ +-------------+ +----------------+ | v API REST (42 Endpoints) +-------------+ +-------------+ +----------------+ |send_message | |get_messages | | upload_media | |send_template| | get_users | | webhook | |send_broadcast| | get_stats | | sse_events | +-------------+ +-------------+ +----------------+ | v CAPA DE SERVICIOS +-----------------+ +-------------------+ | WhatsAppService | | BotService | | (comunicación | | (automatización) | | con WhatsApp) | | | +-----------------+ +-------------------+ | v CAPA DE DATOS +------------+ +------------+ +---------------+ | Database | | Redis | | Filesystem | | (MariaDB) | | (cache) | | (uploads/) | +------------+ +------------+ +---------------+ | v INTEGRACIONES EXTERNAS +------------------------------------------------------+ | WhatsApp Business API (Meta Graph API) | | https://graph.facebook.com/v22.0/ | +------------------------------------------------------+ FLUJO DE MENSAJES ----------------- Mensaje Entrante (Incoming): 1. Usuario envía mensaje por WhatsApp 2. WhatsApp envía webhook POST a /api/webhook.php 3. Webhook valida firma de Meta 4. Procesa evento (message, status, etc.) 5. Guarda mensaje en BD (tabla: conversations) 6. BotService evalúa si debe responder automáticamente 7. Si hay respuesta automática -> Envía por WhatsAppService 8. SSE notifica a frontend conectado 9. Frontend actualiza UI en tiempo real Mensaje Saliente (Outgoing): 1. Usuario escribe mensaje en interfaz web 2. Frontend llama a /api/send_message.php (POST) 3. API valida sesión y datos 4. WhatsAppService envía mensaje a Graph API 5. Graph API retorna ID del mensaje 6. Se guarda mensaje en BD con estado 'sent' 7. Respuesta JSON al frontend 8. Frontend muestra mensaje instantáneamente 9. Webhook recibe confirmación de entrega/lectura 10. Actualiza estado en BD y notifica por SSE 3.2. Estructura de Archivos ----------------------------- whatsapp/ |-- api/ (API REST Endpoints) | |-- webhook.php (Recibe eventos de WhatsApp) | |-- send_message.php (Enviar mensaje individual) | |-- send_media_message.php (Enviar multimedia) | |-- send_template.php (Enviar plantilla) | |-- send_broadcast.php (Envío masivo) | |-- get_conversations.php (Listar conversaciones) | |-- get_user_messages.php (Mensajes de un usuario) | |-- get_users.php (Listar usuarios) | |-- update_user.php (Actualizar usuario) | |-- delete_user.php (Eliminar usuario) | |-- upload_media.php (Subir archivos) | |-- get_media.php (Obtener URL temporal de media) | |-- get_templates.php (Listar plantillas) | |-- save_template.php (Guardar plantilla) | |-- get_autoresponses.php (Respuestas automáticas) | |-- save_autoresponse.php (Guardar respuesta automática) | |-- get_stats.php (Estadísticas dashboard) | |-- sse_events.php (Server-Sent Events) | +-- ... (42 endpoints totales) | |-- assets/ (Recursos estáticos) | |-- css/ | | +-- main.css | |-- js/ | | |-- chat-common.js (Funciones compartidas de chat) | | |-- dashboard.js (Dashboard stats) | | +-- admin.js | +-- images/ | |-- classes/ (Clases PHP) | +-- Database.php (Clase singleton de DB) | |-- config/ (Configuración) | |-- config.php (Configuración principal) | +-- .env.example (Plantilla variables de entorno) | |-- database/ (Scripts SQL) | |-- migrations/ | | |-- 001_initial_schema.sql | | |-- 002_add_media_fields.sql | | +-- ... | +-- backups/ (Backups automáticos) | |-- docker/ (Configuración Docker) | |-- nginx/ | | +-- default.conf | |-- php/ | | +-- Dockerfile | +-- supervisor/ | +-- supervisord.conf | |-- services/ (Servicios) | |-- WhatsAppService.php (Cliente WhatsApp Business API) | |-- BotService.php (Lógica del bot automático) | +-- MediaService.php (Gestión multimedia) | |-- uploads/ (Archivos subidos) | |-- images/ | |-- videos/ | |-- audio/ | +-- documents/ | |-- logs/ (Logs del sistema) | |-- app.log | |-- webhook.log | +-- error.log | |-- tests/ (Tests) | |-- ApiTest.php | |-- WhatsAppServiceTest.php | +-- ... | |-- conversations.php (Interfaz principal de chat) |-- chat_window.php (Ventana de chat) |-- inicio.html (Landing page) |-- index.php (Dashboard / Redirect) |-- login.php (Login) |-- logout.php (Logout) |-- worker.php (Worker de colas) |-- composer.json (Dependencias PHP) |-- docker-compose.yml (Orquestación containers) |-- .env (Variables de entorno) +-- README.md (Documentación básica) 3.3. Base de Datos ------------------- TABLA: users Almacena información de usuarios/contactos de WhatsApp. Campo Tipo Descripción ------------------------------------------------------------------------ id INT ID único autoincremental phone_number VARCHAR(50) Número con código de país name VARCHAR(255) Nombre del contacto email VARCHAR(255) Email (opcional) profile_pic_url TEXT URL foto de perfil in_service TINYINT(1) 1 si está en conversación activa advisor_requested TINYINT(1) 1 si solicitó asesor humano on_hold TINYINT(1) 1 si está en espera attended_by INT ID del admin que atiende last_message_at TIMESTAMP Timestamp último mensaje created_at TIMESTAMP Fecha de registro updated_at TIMESTAMP Última actualización Índices: - idx_phone (phone_number) - idx_last_message (last_message_at) - idx_in_service (in_service) TABLA: conversations Almacena todos los mensajes (entrantes y salientes). Campo Tipo Descripción ------------------------------------------------------------------------ id INT ID único autoincremental user_id INT ID del usuario message_id VARCHAR(255) ID único de WhatsApp content TEXT Contenido del mensaje direction ENUM 'incoming' o 'outgoing' message_type VARCHAR(50) text, image, video, audio, etc. status VARCHAR(50) sent, delivered, read, failed media_url TEXT URL original de WhatsApp whatsapp_media_id VARCHAR(255) ID del media en WhatsApp local_file VARCHAR(500) Ruta local del archivo local_thumb VARCHAR(500) Ruta de thumbnail filename VARCHAR(255) Nombre del archivo mime_type VARCHAR(100) Tipo MIME media_url_external TEXT URL proxy persistente reply_to_message_id VARCHAR(255) ID mensaje al que responde reaction_emoji VARCHAR(10) Emoji de reacción reaction_to_message_id VARCHAR(255) ID mensaje al que reacciona created_at TIMESTAMP Fecha de creación Índices: - idx_user_id (user_id) - idx_message_id (message_id) - idx_direction (direction) - idx_created_at (created_at) - idx_user_created (user_id, created_at) TABLA: message_templates Plantillas de WhatsApp aprobadas por Meta. Campo Tipo Descripción ------------------------------------------------------------------------ id INT ID único autoincremental template_name VARCHAR(255) Nombre de la plantilla language_code VARCHAR(10) Código de idioma (es, en) category VARCHAR(50) MARKETING, UTILITY, AUTHENTICATION header_text TEXT Texto del encabezado body_text TEXT Texto del cuerpo footer_text TEXT Texto del pie buttons TEXT Botones (JSON) status VARCHAR(50) pending, approved, rejected created_at TIMESTAMP Fecha de creación updated_at TIMESTAMP Última actualización Índices: - idx_status (status) TABLA: autoresponses Respuestas automáticas del bot. Campo Tipo Descripción ------------------------------------------------------------------------ id INT ID único autoincremental trigger_keywords TEXT Palabras clave (separadas por comas) response_message TEXT Mensaje de respuesta is_active TINYINT(1) 1 si está activa priority INT Orden de evaluación created_at TIMESTAMP Fecha de creación updated_at TIMESTAMP Última actualización Índices: - idx_active (is_active) TABLA: system_config Configuración dinámica del sistema. Campo Tipo Descripción ------------------------------------------------------------------------ id INT ID único autoincremental config_key VARCHAR(255) Clave de configuración config_value TEXT Valor config_type VARCHAR(50) string, int, boolean, json description TEXT Descripción created_at TIMESTAMP Fecha de creación updated_at TIMESTAMP Última actualización Índices: - idx_key (config_key) TABLA: admin_users Usuarios administradores del panel. Campo Tipo Descripción ------------------------------------------------------------------------ id INT ID único autoincremental username VARCHAR(100) Nombre de usuario password VARCHAR(255) Contraseña hash email VARCHAR(255) Email role VARCHAR(50) super_admin, admin, operator, viewer is_active TINYINT(1) 1 si está activo last_login TIMESTAMP Último inicio de sesión created_at TIMESTAMP Fecha de creación updated_at TIMESTAMP Última actualización Índices: - idx_username (username) TABLA: webhook_logs Auditoría de webhooks recibidos. Campo Tipo Descripción ------------------------------------------------------------------------ id INT ID único autoincremental event_type VARCHAR(100) Tipo de evento payload TEXT Datos del evento (JSON) processed TINYINT(1) 1 si fue procesado processing_time_ms INT Tiempo de procesamiento error_message TEXT Mensaje de error (si aplica) created_at TIMESTAMP Fecha de recepción Índices: - idx_event_type (event_type) - idx_processed (processed) - idx_created_at (created_at) 3.4. Servicios Principales ---------------------------- WhatsAppService.php Clase que encapsula toda la comunicación con WhatsApp Business API. MÉTODOS PRINCIPALES: 1. sendTextMessage($to, $message) Envía un mensaje de texto simple. Parámetros: - $to: Número de destino con código de país - $message: Contenido del mensaje (máx 4096 caracteres) Retorna: [ 'success' => true|false, 'message_id' => 'wamid.XXX...', 'error' => null|string ] 2. sendTemplateMessage($to, $templateName, $language, $bodyParameters) Envía una plantilla de mensaje aprobada. Parámetros: - $to: Número destino - $templateName: Nombre de la plantilla - $language: Código de idioma (es) - $bodyParameters: Array de variables 3. sendImageMessage($to, $imageUrl, $caption, $isLocalFile) Envía una imagen. Formatos soportados: JPG, JPEG, PNG Tamaño máximo: 5 MB 4. sendVideoMessage($to, $videoUrl, $caption, $isLocalFile) Envía un video. Formatos soportados: MP4, 3GPP Tamaño máximo: 16 MB 5. sendAudioMessage($to, $audioUrl, $isLocalFile) Envía audio. Formatos soportados: AAC, MP3, AMR, OGG Tamaño máximo: 16 MB 6. sendDocumentMessage($to, $documentUrl, $filename, $caption, $isLocalFile) Envía un documento. Formatos soportados: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP Tamaño máximo: 100 MB 7. uploadMedia($filePath, $mimeType) Sube un archivo a los servidores de WhatsApp. Retorna: media_id para usar en envíos 8. downloadMedia($mediaId) Descarga un archivo multimedia de WhatsApp. Retorna: ruta local del archivo descargado 9. sendInteractiveMessage($to, $bodyText, $buttons, $header, $footer) Envía un mensaje con botones interactivos (hasta 3 botones). 10. sendListMessage($to, $bodyText, $buttonText, $sections) Envía un mensaje con lista interactiva (hasta 10 opciones). BotService.php Servicio de automatización de respuestas. MÉTODOS PRINCIPALES: 1. processIncomingMessage($userId, $message) Procesa un mensaje entrante y decide si el bot debe responder. Lógica: - Verifica si el bot está activado - Comprueba si el usuario está siendo atendido por humano - Busca respuesta automática que coincida - Ejecuta lógica de menús si aplica - Envía respuesta si corresponde 2. findAutoResponse($message) Busca una respuesta automática que coincida con el mensaje. Retorna: Objeto con response_message o null 3. sendWelcomeMessage($userId) Envía el mensaje de bienvenida configurado. 4. isBusinessHours() Verifica si está dentro del horario de atención. Retorna: true si está en horario, false fuera de horario MediaService.php Servicio para gestión de archivos multimedia. MÉTODOS PRINCIPALES: 1. downloadAndSaveMedia($mediaId, $userId) Descarga un media de WhatsApp y lo guarda localmente. Proceso: - Obtiene URL temporal del media - Descarga el contenido - Detecta tipo MIME - Genera nombre único - Guarda en carpeta correspondiente - Genera thumbnail para imágenes/videos - Actualiza registro en BD 2. generateThumbnail($imagePath, $maxWidth, $maxHeight) Genera un thumbnail para imágenes. 3. getMediaProxy($messageId) Obtiene URL proxy persistente para un media. 3.5. Server-Sent Events (SSE) ------------------------------- El sistema usa SSE para notificaciones en tiempo real sin WebSockets. FLUJO SSE: 1. Frontend se conecta a /api/sse_events.php 2. El backend mantiene la conexión HTTP abierta 3. Cuando hay un nuevo evento: a. Se guarda en Redis (canal: sse_notifications) b. worker.php o webhook.php publica evento en canal 4. sse_events.php lee de Redis y envía al cliente 5. Frontend recibe evento y actualiza UI 6. Conexión se mantiene viva con heartbeat cada 15s TIPOS DE EVENTOS SSE: 1. new_message Nuevo mensaje recibido. Datos: { "type": "new_message", "user_id": 123, "message_id": "wamid.XXX", "content": "Hola", "direction": "incoming", "created_at": "2024-01-27 14:30:45" } 2. message_status Cambio de estado de mensaje. Datos: { "type": "message_status", "message_id": "wamid.XXX", "status": "read", "timestamp": "2024-01-27 14:31:00" } 3. conversation_update Actualización de conversación en lista. Datos: { "type": "conversation_update", "user_id": 123, "last_message": "Hola", "unread_count": 1 } 4. notification Notificación general. Datos: { "type": "notification", "title": "Nuevo mensaje", "message": "Juan te ha enviado un mensaje", "severity": "info" } ================================================================================ 4. API REST COMPLETA ================================================================================ AUTENTICACIÓN ------------- Todos los endpoints (excepto webhook) requieren autenticación mediante sesión PHP. Headers requeridos: Cookie: PHPSESSID=abc123... Respuesta de error de autenticación: { "error": "Acceso denegado. Inicia sesión.", "code": 401 } ENDPOINTS DE MENSAJERÍA ------------------------ POST /api/send_message.php Envía un mensaje de texto individual. Request Body: { "recipient": "573001234567", "message": "Hola, este es un mensaje de prueba", "reply_to": "wamid.XXX" // Opcional } Response Success: { "success": true, "message_id": "wamid.HBgNNTczMDA...", "timestamp": "2024-01-27 14:35:20" } Response Error: { "success": false, "error": "Recipient not on WhatsApp" } POST /api/send_template.php Envía una plantilla de mensaje. Request Body: { "recipient": "573001234567", "template_name": "welcome_message", "language": "es", "parameters": { "body": ["Juan Pérez", "2024-01-27"], "header": [] } } Response: { "success": true, "message_id": "wamid.XXX..." } POST /api/send_media_message.php Envía un mensaje multimedia. Request Body: { "recipient": "573001234567", "media_type": "image", "media_url": "https://ejemplo.com/imagen.jpg", "caption": "Mira esta imagen", "filename": "imagen.jpg" // Requerido para documentos } Tipos de media: image, video, audio, document Response: { "success": true, "message_id": "wamid.XXX...", "media_id": "123456789" } POST /api/send_broadcast.php Envía mensaje masivo. Request Body: { "message": "Hola a todos, este es un anuncio importante", "filter": "active", "template_name": null } Filtros disponibles: - all: Todos los usuarios - active: Usuarios activos (< 24h) - inactive: Usuarios inactivos - custom: Lista personalizada (requiere user_ids array) Response: { "success": true, "total_sent": 150, "failed": 2, "details": [ {"phone": "573001234567", "status": "sent"}, {"phone": "573009876543", "status": "failed", "error": "Not on WhatsApp"} ] } ENDPOINTS DE CONVERSACIONES ---------------------------- GET /api/get_conversations.php Lista todas las conversaciones. Query Params: - page (int): Número de página (default: 1) - limit (int): Conversaciones por página (default: 50, max: 100) - filter (string): all | unread | active Ejemplo: GET /api/get_conversations.php?page=1&limit=20&filter=unread Response: { "success": true, "data": [ { "user_id": 123, "name": "Juan Pérez", "phone_number": "573001234567", "last_message": "Hola, necesito ayuda", "last_message_time": "2024-01-27 14:30:45", "last_message_direction": "incoming", "unread_count": 2, "in_service": 1, "attended_by": null } ], "pagination": { "current_page": 1, "total_pages": 5, "total_items": 98, "per_page": 20 } } GET /api/get_user_messages.php Obtiene mensajes de un usuario específico. Query Params: - user_id (int): ID del usuario (requerido) - limit (int): Número de mensajes (default: 50) - before (timestamp): Cargar mensajes anteriores (scroll infinito) Ejemplo: GET /api/get_user_messages.php?user_id=123&limit=50 Response: { "success": true, "data": [ { "id": 456, "message_id": "wamid.XXX", "user_id": 123, "content": "Hola, necesito ayuda", "direction": "incoming", "message_type": "text", "status": "read", "media_url": null, "local_file": null, "reply_to_message_id": null, "reaction_emoji": null, "created_at": "2024-01-27 14:30:45" } ], "has_more": true } POST /api/mark_conversation_read.php Marca una conversación como leída. Request Body: { "user_id": 123 } Response: { "success": true, "message": "Conversación marcada como leída" } ENDPOINTS DE USUARIOS ---------------------- GET /api/get_users.php Lista todos los usuarios. Query Params: - page (int): Número de página - limit (int): Usuarios por página - search (string): Buscar por nombre o teléfono Response: { "success": true, "data": [ { "id": 123, "phone_number": "573001234567", "name": "Juan Pérez", "email": "juan@example.com", "in_service": 1, "advisor_requested": 0, "last_message_at": "2024-01-27 14:30:45", "created_at": "2024-01-20 10:00:00" } ], "pagination": {...} } POST /api/update_user.php Actualiza información de un usuario. Request Body: { "user_id": 123, "name": "Juan Pérez García", "email": "juan.perez@example.com" } Response: { "success": true, "message": "Usuario actualizado correctamente" } DELETE /api/delete_user.php Elimina un usuario y todo su historial. Request Body: { "user_id": 123 } Response: { "success": true, "message": "Usuario eliminado correctamente" } GET /api/export_users.php Exporta usuarios a CSV. Response: Archivo CSV descargable ENDPOINTS DE MULTIMEDIA ------------------------ POST /api/upload_media.php Sube un archivo multimedia. Request: multipart/form-data - file (file): Archivo a subir Response: { "success": true, "media_id": "123456789", "media_url": "https://graph.facebook.com/v22.0/123456789", "local_file": "uploads/images/20240127_143520_abc123.jpg", "mime_type": "image/jpeg", "file_size": 245678 } GET /api/get_media.php Obtiene URL temporal de un media de WhatsApp. Query Params: - id (string): Media ID de WhatsApp Response: { "success": true, "url": "https://lookaside.fbsbx.com/whatsapp_business/...", "mime_type": "image/jpeg", "file_size": 245678, "sha256": "abc123...", "expires_at": "2024-01-27 15:30:00" } ENDPOINTS DE PLANTILLAS ------------------------ GET /api/get_templates.php Lista plantillas de mensaje. Query Params: - approved_only (0|1): Solo plantillas aprobadas - limit (int): Límite de resultados Response: { "success": true, "data": [ { "id": 1, "template_name": "welcome_message", "language_code": "es", "category": "MARKETING", "body_text": "Hola {{1}}, bienvenido...", "status": "approved", "created_at": "2024-01-20 10:00:00" } ] } POST /api/save_template.php Crea o actualiza una plantilla. Request Body: { "template_name": "new_template", "language_code": "es", "category": "MARKETING", "header_text": "Oferta Especial", "body_text": "Hola {{1}}, tenemos una oferta...", "footer_text": "Válido hasta fin de mes", "buttons": [ {"type": "QUICK_REPLY", "text": "Me interesa"} ] } Response: { "success": true, "template_id": 5, "message": "Plantilla creada. Pendiente de aprobación." } ENDPOINTS DE RESPUESTAS AUTOMÁTICAS ------------------------------------- GET /api/get_autoresponses.php Lista respuestas automáticas. Response: { "success": true, "data": [ { "id": 1, "trigger_keywords": "hola,buenos días,hey", "response_message": "¡Hola! Bienvenido...", "is_active": 1, "priority": 1 } ] } POST /api/save_autoresponse.php Crea o actualiza respuesta automática. Request Body: { "id": null, "trigger_keywords": "precio,costo,cuanto cuesta", "response_message": "Nuestros precios varían...", "is_active": 1, "priority": 5 } Response: { "success": true, "id": 3, "message": "Respuesta automática guardada" } ENDPOINTS DE ESTADÍSTICAS --------------------------- GET /api/get_stats.php Obtiene estadísticas del dashboard. Response: { "success": true, "data": { "total_users": 1250, "messages_received_24h": 340, "messages_sent_24h": 285, "active_conversations": 45, "messages_by_hour": [ {"hour": "00:00", "incoming": 5, "outgoing": 2}, ... ], "messages_by_day": [ {"date": "2024-01-21", "incoming": 120, "outgoing": 95}, ... ], "top_users": [ {"user_id": 123, "name": "Juan Pérez", "message_count": 45} ] } } ENDPOINT DE WEBHOOK ------------------- POST /api/webhook.php Recibe eventos de WhatsApp Business API. Verificación (GET): GET /api/webhook.php?hub.mode=subscribe&hub.challenge=123456&hub.verify_token=token Response: 123456 (echo del challenge) Eventos recibidos (POST): Nuevo mensaje: { "object": "whatsapp_business_account", "entry": [{ "changes": [{ "value": { "messaging_product": "whatsapp", "messages": [{ "from": "573001234567", "id": "wamid.XXX", "timestamp": "1706367000", "type": "text", "text": { "body": "Hola, necesito ayuda" } }] } }] }] } Estado de mensaje: { "entry": [{ "changes": [{ "value": { "statuses": [{ "id": "wamid.XXX", "status": "read", "timestamp": "1706367100", "recipient_id": "573001234567" }] } }] }] } Tipos de status: - sent: Enviado - delivered: Entregado - read: Leído - failed: Fallido ENDPOINTS SSE ------------- GET /api/sse_events.php Conexión de Server-Sent Events para notificaciones en tiempo real. Headers: Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive Eventos enviados: event: message data: {"type":"new_message","user_id":123,"content":"Hola"} event: heartbeat data: {"timestamp":"2024-01-27 14:35:00"} CÓDIGOS DE ESTADO HTTP ----------------------- Código Significado ------------------------------------------------------------------------ 200 Éxito 201 Creado 400 Petición inválida 401 No autenticado 403 Sin permisos 404 No encontrado 405 Método no permitido 429 Demasiadas peticiones (rate limit) 500 Error del servidor 503 Servicio no disponible ================================================================================ 5. GUÍA DE IMPLEMENTACIÓN ================================================================================ 5.1. Instalación desde Cero ----------------------------- REQUISITOS DEL SERVIDOR ------------------------ Mínimos: - CPU: 2 cores - RAM: 4 GB - Disco: 20 GB SSD - SO: Ubuntu 22.04 LTS, Debian 11+, CentOS 8+ Recomendados para producción: - CPU: 4+ cores - RAM: 8+ GB - Disco: 50+ GB SSD - SO: Ubuntu 22.04 LTS OPCIÓN 1: Docker (Recomendado) ------------------------------- 1. Instalar Docker y Docker Compose Ubuntu/Debian: sudo apt update sudo apt install -y docker.io docker-compose Verificar instalación: docker --version docker-compose --version 2. Clonar Repositorio git clone https://github.com/tu-usuario/whatsapp.git cd whatsapp 3. Configurar Variables de Entorno cp .env.example .env nano .env Editar .env: # Base de datos DB_HOST=db DB_PORT=3306 DB_NAME=whatsapp_bot DB_USER=whatsapp_user DB_PASS=tu_password_seguro # WhatsApp Business API WHATSAPP_TOKEN=tu_access_token WHATSAPP_PHONE_ID=tu_phone_id WHATSAPP_BUSINESS_ACCOUNT_ID=tu_business_account_id WHATSAPP_APP_ID=tu_app_id WHATSAPP_APP_SECRET=tu_app_secret # Webhook WEBHOOK_VERIFY_TOKEN=tu_token_verificacion_webhook # Sistema APP_ENV=production APP_DEBUG=false APP_TIMEZONE=America/Bogota 4. Levantar Contenedores Desarrollo: docker-compose -f docker-compose.dev.yml up -d Producción: docker-compose -f docker-compose.prod.yml up -d 5. Verificar Estado docker-compose ps Deberías ver: NAME STATUS whatsapp-app Up whatsapp-db Up whatsapp-redis Up whatsapp-worker Up whatsapp-nginx Up 6. Acceder a la Aplicación App: http://tu-servidor:8080 (dev) o http://tu-dominio (prod) phpMyAdmin: http://tu-servidor:8084 (dev) 7. Configurar en el Panel 1. Accede con las credenciales por defecto: Usuario: admin Password: password123 2. Cambia la contraseña inmediatamente 3. Ve a Configuración > WhatsApp API y completa los datos 4. Verifica la configuración OPCIÓN 2: Instalación Manual ------------------------------ 1. Instalar Stack LAMP Ubuntu 22.04: sudo apt update sudo apt install -y apache2 mariadb-server php8.2 php8.2-mysql \ php8.2-curl php8.2-mbstring php8.2-xml php8.2-gd php8.2-zip \ php8.2-redis redis-server Verificar PHP: php -v 2. Configurar MariaDB sudo mysql_secure_installation Crear base de datos: sudo mysql -u root -p SQL: CREATE DATABASE whatsapp_bot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'whatsapp_user'@'localhost' IDENTIFIED BY 'tu_password_seguro'; GRANT ALL PRIVILEGES ON whatsapp_bot.* TO 'whatsapp_user'@'localhost'; FLUSH PRIVILEGES; EXIT; 3. Clonar y Configurar Aplicación cd /var/www/html sudo git clone https://github.com/tu-usuario/whatsapp.git cd whatsapp Permisos: sudo chown -R www-data:www-data /var/www/html/whatsapp sudo chmod -R 755 /var/www/html/whatsapp sudo chmod -R 777 /var/www/html/whatsapp/uploads sudo chmod -R 777 /var/www/html/whatsapp/logs Configurar .env: cp .env.example .env sudo nano .env 4. Importar Base de Datos mysql -u whatsapp_user -p whatsapp_bot < \ database/migrations/001_initial_schema.sql mysql -u whatsapp_user -p whatsapp_bot < \ database/migrations/002_add_media_fields.sql 5. Configurar Apache sudo nano /etc/apache2/sites-available/whatsapp.conf Contenido: ServerName tudominio.com DocumentRoot /var/www/html/whatsapp Options -Indexes +FollowSymLinks AllowOverride All Require all granted ErrorLog ${APACHE_LOG_DIR}/whatsapp_error.log CustomLog ${APACHE_LOG_DIR}/whatsapp_access.log combined Habilitar sitio: sudo a2ensite whatsapp.conf sudo a2enmod rewrite sudo systemctl restart apache2 6. Configurar SSL con Let's Encrypt sudo apt install -y certbot python3-certbot-apache sudo certbot --apache -d tudominio.com 7. Configurar Worker (Supervisor) sudo apt install -y supervisor sudo cp supervisor-whatsapp-worker.conf \ /etc/supervisor/conf.d/whatsapp-worker.conf sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start whatsapp-worker:* 8. Configurar Cron Jobs sudo crontab -e Agregar: # Limpiar logs antiguos (diario a las 3am) 0 3 * * * cd /var/www/html/whatsapp && \ php scripts/clean_old_logs.php # Backup de base de datos (diario a las 2am) 0 2 * * * /usr/bin/mysqldump -u whatsapp_user \ -p'tu_password' whatsapp_bot > \ /var/www/html/whatsapp/database/backups/backup_$(date +\%Y\%m\%d_\%H\%M\%S).sql # Limpiar backups antiguos (mantener últimos 7 días) 0 4 * * * find /var/www/html/whatsapp/database/backups \ -name "backup_*.sql" -mtime +7 -delete 5.2. Configuración de Producción ---------------------------------- OPTIMIZACIÓN DE PHP ------------------- Editar /etc/php/8.2/apache2/php.ini: memory_limit = 256M post_max_size = 100M upload_max_filesize = 100M max_execution_time = 300 max_input_time = 300 ; Para SSE (Server-Sent Events) output_buffering = Off implicit_flush = On ; Seguridad expose_php = Off display_errors = Off log_errors = On error_log = /var/log/php/error.log ; Zona horaria date.timezone = America/Bogota OPTIMIZACIÓN DE MariaDB ------------------------ Editar /etc/mysql/mariadb.conf.d/50-server.cnf: [mysqld] # Memoria innodb_buffer_pool_size = 2G innodb_log_file_size = 256M # Conexiones max_connections = 200 # Charset character-set-server = utf8mb4 collation-server = utf8mb4_unicode_ci # Logs slow_query_log = 1 slow_query_log_file = /var/log/mysql/slow-query.log long_query_time = 2 # Índices innodb_flush_log_at_trx_commit = 2 innodb_flush_method = O_DIRECT Reiniciar: sudo systemctl restart mariadb FIREWALL -------- UFW (Ubuntu): sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable sudo ufw status MONITOREO --------- Instalar Monit: sudo apt install -y monit sudo nano /etc/monit/monitrc Configurar: set daemon 60 set logfile /var/log/monit.log check process apache2 with pidfile /var/run/apache2/apache2.pid start program = "/usr/sbin/service apache2 start" stop program = "/usr/sbin/service apache2 stop" if failed host localhost port 80 protocol http then restart if 5 restarts within 5 cycles then timeout check process mysql with pidfile /var/run/mysqld/mysqld.pid start program = "/usr/sbin/service mysql start" stop program = "/usr/sbin/service mysql stop" if failed host localhost port 3306 protocol mysql then restart if 5 restarts within 5 cycles then timeout check process redis with pidfile /var/run/redis/redis-server.pid start program = "/usr/sbin/service redis-server start" stop program = "/usr/sbin/service redis-server stop" if failed host localhost port 6379 protocol redis then restart Iniciar: sudo systemctl enable monit sudo systemctl start monit 5.3. Actualización del Sistema -------------------------------- PROCESO DE ACTUALIZACIÓN ------------------------- 1. Backup completo ./scripts/backup_all.sh 2. Modo mantenimiento touch maintenance.lock 3. Actualizar código git pull origin main 4. Ejecutar migraciones php scripts/run_migrations.php 5. Limpiar cache php scripts/clear_cache.php 6. Reiniciar servicios sudo systemctl restart apache2 sudo supervisorctl restart whatsapp-worker:* 7. Verificar funcionamiento php scripts/check_health.php 8. Desactivar modo mantenimiento rm maintenance.lock ================================================================================ 6. CASOS DE USO ================================================================================ CASO 1: Atención al Cliente Automatizada ------------------------------------------ Escenario: Una empresa de e-commerce quiere automatizar respuestas a preguntas frecuentes. Implementación: 1. Configurar respuestas automáticas con triggers específicos 2. Crear menú interactivo de opciones principales 3. Configurar horario de atención para transferencia a humano 4. Resultado: Reducción de 70% en consultas repetitivas CASO 2: Campañas de Marketing ------------------------------- Escenario: Lanzamiento de nueva colección, enviar anuncio a clientes activos. Implementación: 1. Crear plantilla en Meta con variables dinámicas 2. Enviar broadcast con filtro de usuarios activos 3. Seguimiento de métricas (enviados, leídos, interacciones) 4. Resultado: 300% ROI, 36% tasa de apertura, 9% conversión CASO 3: Soporte Técnico con Tickets ------------------------------------- Escenario: Empresa de software que recibe consultas técnicas. Implementación: 1. Crear sistema de tickets automático 2. Escalamiento automático según palabras clave 3. Vinculación de respuestas a tickets 4. Sistema de calificación de servicio 5. Resultado: Tiempo de respuesta 15 minutos, satisfacción 4.5/5 CASO 4: Reservas y Citas -------------------------- Escenario: Clínica médica permite agendar citas por WhatsApp. Implementación: 1. Menú de especialidades 2. Sistema de calendario con disponibilidad 3. Confirmación automática de citas 4. Recordatorios 24h antes 5. Resultado: 80% de citas agendadas fuera de horario CASO 5: Encuestas y Feedback ------------------------------ Escenario: Recopilar feedback post-compra. Implementación: 1. Envío automático de encuesta 24h después de compra 2. Procesamiento inteligente de respuestas 3. Escalamiento de casos negativos 4. Dashboard de resultados y análisis 5. Resultado: 350 respuestas en 1 semana, NPS de 72 ================================================================================ 7. ENTREGABLES DEL PROYECTO ================================================================================ 1. CÓDIGO FUENTE COMPLETO - Código PHP backend (42 APIs, servicios, clases) - Frontend (HTML, CSS, JavaScript) - Configuración Docker (dev y prod) - Scripts SQL (esquema, migraciones) - Tests automatizados 2. DOCUMENTACIÓN COMPLETA - README.md - DOCUMENTACION_COMPLETA.md (este documento) - REPORTE_SISTEMA_COMPLETO.md - DEPLOYMENT_GUIDE.md - DOCKER_README.md - SSE_REALTIME_DOCS.md - API_REFERENCE.md 3. BASE DE DATOS - Esquema completo (schema_complete.sql) - Migraciones ordenadas - Scripts de mantenimiento 4. CONFIGURACIÓN DE SERVIDOR - Nginx configuration - Apache vhost configuration - Supervisor configuration - Cron jobs 5. SCRIPTS DE UTILIDAD - install.php (Instalador interactivo) - run_migrations.php - clean_old_logs.php - backup_database.sh - restore_backup.sh - check_health.php - test_whatsapp_connection.php - generate_report.php 6. TESTS AUTOMATIZADOS - Tests unitarios - Tests de integración - Coverage reports 7. DOCKER COMPOSE - docker-compose.dev.yml (Desarrollo) - docker-compose.prod.yml (Producción) 8. MANUALES DE USUARIO - Manual de usuario final (PDF) - Manual de administrador (PDF) 9. VIDEO TUTORIALES - Instalación y configuración inicial (15 min) - Configurar WhatsApp Business API (10 min) - Gestión de conversaciones (8 min) - Crear respuestas automáticas (7 min) - Enviar mensajes masivos (6 min) - Crear plantillas de WhatsApp (12 min) - Administración de usuarios (5 min) - Interpretar estadísticas (8 min) - Solución de problemas comunes (10 min) - Actualización del sistema (7 min) 10. LICENCIA Y GARANTÍA - 30 días de soporte post-entrega - Corrección de bugs sin costo - Actualizaciones de seguridad durante 1 año - Consultoría técnica (10 horas incluidas) 11. ACCESOS Y CREDENCIALES - Credenciales de admin por defecto - Accesos a servidor (SSH) - Credenciales de base de datos - Tokens de WhatsApp Business API 12. CHECKLIST DE ENTREGA - Pre-Entrega - Entrega - Post-Entrega ================================================================================ 8. MANTENIMIENTO Y SOPORTE ================================================================================ 8.1. Tareas de Mantenimiento ------------------------------ DIARIO (Automatizado) ---------------------- 1. Backup de base de datos (2:00 AM, retención 7 días) 2. Limpieza de logs (3:00 AM, retención 30 días) 3. Verificación de salud (cada hora) SEMANAL ------- 1. Optimización de base de datos 2. Revisión de logs de error 3. Actualización de dependencias MENSUAL ------- 1. Auditoría de seguridad 2. Análisis de uso y optimización 3. Backup completo 8.2. Monitoreo --------------- MÉTRICAS CLAVE -------------- Métrica Umbral Acción ------------------------------------------------------------------------ CPU > 80% 5 min Escalar recursos RAM > 90% 5 min Revisar memory leaks Disco > 85% - Limpiar archivos antiguos Respuesta API > 2s - Optimizar queries Errores > 10/min - Investigar logs 8.3. Solución de Problemas Comunes ------------------------------------ 1. MENSAJES NO SE ENVÍAN Síntomas: API retorna error 401 o 403 Solución: - Verificar token de acceso - Regenerar token si expiró - Verificar permisos del token en Meta 2. WEBHOOK NO RECIBE EVENTOS Síntomas: No llegan mensajes nuevos Solución: - Verificar URL del webhook en Meta - Revisar logs de webhook - Verificar suscripción a eventos - Probar manualmente con curl 3. SSE NO FUNCIONA Síntomas: No hay notificaciones en tiempo real Solución: - Verificar que Redis esté corriendo - Revisar configuración PHP (output_buffering=Off) - Verificar soporte SSE en navegador - Revisar logs del navegador 4. MULTIMEDIA NO SE DESCARGA Síntomas: Imágenes/videos no se muestran Solución: - Verificar permisos de carpeta uploads/ - Verificar espacio en disco - Revisar logs de descarga - Verificar permisos del token 5. ALTO USO DE CPU/RAM Síntomas: Sistema lento, timeouts Solución: - Identificar procesos pesados con top - Optimizar consultas lentas - Aumentar recursos del servidor - Activar cache (Redis/Memcached) - Optimizar tablas de base de datos 8.4. Contacto de Soporte -------------------------- Desarrollado por: U-Site.app Canales de soporte: - Email: soporte@u-site.app - WhatsApp: +57 XXX XXX XXXX - Portal: https://u-site.app/soporte - Telegram: @usiteapp_soporte Horario de soporte: - Lunes a Viernes: 9:00 AM - 6:00 PM (GMT-5) - Emergencias críticas: 24/7 (solo clientes premium) Niveles de soporte: - Básico (incluido): Email, respuesta en 24-48h - Estándar: Email + WhatsApp, respuesta en 12h - Premium: Email + WhatsApp + Teléfono, respuesta en 2h, atención 24/7 ================================================================================ LICENCIA ================================================================================ © 2024-2026 U-Site.app. Todos los derechos reservados. Este software es propiedad de U-Site.app y está protegido por las leyes de derechos de autor. Permisos: - Uso en producción para el cliente que adquirió la licencia - Modificaciones para uso interno - Despliegue en múltiples instancias del mismo cliente Prohibido: - Redistribución del código fuente - Reventa o sublicencia - Uso en proyectos de terceros sin autorización Para consultas sobre licenciamiento, contacta: licencias@u-site.app ================================================================================ CONCLUSIÓN ================================================================================ Este sistema de WhatsApp Bot Manager representa una solución completa y profesional para gestión de comunicaciones empresariales vía WhatsApp Business. CARACTERÍSTICAS DESTACADAS: - 42 endpoints API REST documentados - Interfaz moderna y responsive - Tiempo real con SSE - Bot inteligente y configurable - Soporte multimedia completo - Seguridad robusta - Docker ready - Escalable y mantenible CASOS DE USO VALIDADOS: - Atención al cliente automatizada - Campañas de marketing masivas - Soporte técnico con tickets - Reservas y citas - Encuestas y feedback PRÓXIMOS PASOS SUGERIDOS: 1. Revisar la documentación completa 2. Seguir la guía de instalación 3. Configurar WhatsApp Business API 4. Personalizar respuestas automáticas 5. Capacitar al equipo 6. Lanzar en producción 7. Monitorear y optimizar ¿Necesitas ayuda? Contacta al equipo de U-Site.app: Website: u-site.app Email: contacto@u-site.app WhatsApp: +57 XXX XXX XXXX ================================================================================ Desarrollado con amor por U-Site.app Simplificando la comunicación empresarial ================================================================================