Manual de Usuario

1. Acceso y Seguridad

El ingreso y autenticación al panel se encuentra protegido mediante sesiones seguras de servidor.

• Inicio de Sesión: Introduzca su nombre de usuario y contraseña. La sesión tiene una vigencia predeterminada de 24 horas.
• Renovación de Contraseña Obligatoria: Si un administrador activa este atributo en su ficha de usuario, la aplicación le bloqueará la navegación mostrando una ventana emergente. Deberá definir y confirmar una nueva contraseña antes de poder operar en la aplicación.

2. Roles de Usuario (RBAC)

La aplicación restringe las funcionalidades según el rol asignado a cada usuario en la base de datos:

3. Barra Lateral (Sidebar)

La barra izquierda organiza las interacciones principales en tres pestañas:

• Pestaña Chats: Muestra las conversaciones en curso. La lista se ordena automáticamente de forma descendente por la hora del último mensaje (el chat activo más reciente se ubica arriba).
• Buscador y Búsqueda Global: Filtre su lista de contactos escribiendo en la barra superior. Al escribir, la lista de la izquierda se filtrará por nombre/número, y a la derecha se abrirá automáticamente un Panel de Búsqueda Global de mensajes que muestra todas las coincidencias del texto en las burbujas de conversación, con el nombre del remitente y fecha/hora.
• Icono de Ojo (Mostrar/Ocultar Búsqueda): Junto al buscador, el botón de ojo permite mostrar u ocultar manualmente este panel lateral de resultados de búsqueda. El panel también se oculta de forma automática al seleccionar un chat.
• Filtrar por Lote: Debajo del buscador, un selector desplegable le permite filtrar la lista de contactos para mostrar únicamente a los destinatarios que pertenezcan al lote de campaña seleccionado. Seleccione "Todos los lotes" para restablecer la vista.
• Badge Circular de Mensajes sin Leer: Cuando un cliente envía un mensaje, se muestra un círculo verde indicando la cantidad de mensajes recibidos sin leer. Al hacer clic sobre el chat, la marca se borra automáticamente.
• Avatares con Iniciales y Edición de Contacto: En lugar de imágenes genéricas, cada chat muestra la inicial del nombre sobre un círculo de color personalizable. Si hace clic directamente sobre este círculo de inicial, además de abrir el chat, aparecerá un cuadro de diálogo flotante (draggable) para editar el nombre a visualizar, el teléfono (ID de chat) y los colores de fondo y texto del círculo.

4. Chat Activo y Envío

La pantalla central permite el intercambio interactivo de mensajes:

• Desplazamiento al Final (Auto-Scroll): Al abrir cualquier conversación de forma normal, el visor de chat se desplaza automáticamente hacia el último mensaje para permitir una lectura rápida del flujo actual.
• Actualizaciones Optimistas (Optimistic Updates): Para evitar demoras al enviar mensajes de texto, plantillas o archivos adjuntos, el mensaje aparece instantáneamente en pantalla con un icono de reloj (🕒). Tan pronto como el servidor o el canal de eventos en tiempo real (SSE) confirman la acción, el reloj cambia automáticamente a un tick de enviado o entregado, sin requerir recargar la página. Si ocurre un fallo, el reloj cambia a una advertencia (⚠️).
• Resaltado y Navegación desde Búsqueda: Al hacer clic en un mensaje coincidente dentro del panel de Búsqueda Global, la aplicación cargará el chat correcto, se desplazará suavemente hasta dicho mensaje, y aplicará un parpadeo/destello amarillo temporal durante 3 segundos para que lo identifique al instante.
• Tildes de Estado de Mensaje: Un reloj gris (🕒) indica enviando; un tilde gris (✓) indica enviado; dos tildes grises (✓✓) indican entregado; dos tildes azules (✓✓) indican leído; una advertencia naranja (⚠️) indica error de API (puede poner el cursor encima para leer el error detallado de Meta).
• Adjuntar Archivo e Iconos de Documento: Utilice el clip para enviar imágenes, videos, audios o documentos. Al cargarse, se habilitará una previsualización con barra de progreso. Si el archivo es un documento (PDF, Word, Excel, etc.), se representará en el chat y en el preview mediante un icono de hoja escrita (📄) en vez del icono de carpeta genérica.
• Recuperación de Archivos Borrados (Hostinger Fallback): Si los archivos multimedia locales son borrados del disco físico del servidor por limpiezas de despliegue en Hostinger, el sistema volverá a descargarlos automáticamente desde los servidores de Meta al vuelo en cuanto se necesiten ver en pantalla o reenviar por correo.
• Eliminar Mensajes: Puede eliminar un mensaje localmente haciendo clic en la papelera en la burbuja del mensaje. Se le solicitará confirmación mediante un modal antes de proceder.
• Buscador de Conversación: Pulse la lupa en la cabecera del chat para buscar palabras en el historial actual. Las coincidencias se realzarán en amarillo y podrá desplazarse con las flechas de dirección.

5. Reenvío de Mensajes por Correo Electrónico

La aplicación permite seleccionar múltiples mensajes de una conversación y enviarlos estructurados a una dirección de email.

• Modo de Selección: Haga clic en el botón de sobre de carta (✉️) en la cabecera del chat activo. Se desplegarán checkboxes al lado de cada mensaje.
• Barra de Acciones: Marque los mensajes que desea reenviar. Una barra inferior le mostrará el total seleccionado y habilitará el botón "Siguiente".
• Formulario de Envío: Complete los campos en el modal:
  • Dirección de Envío: Campo con autocompletado inteligente. Busca las cuentas de los usuarios del sistema y las direcciones usadas anteriormente en el historial de reenvíos. Admite navegación con las flechas del teclado y confirmación por Enter.
  • Asunto: Pre-completado por defecto con el nombre del contacto de origen.
• Despacho por SMTP: El sistema construye un correo en formato HTML que simula el diseño de la conversación, e incluye cualquier archivo multimedia (imágenes, documentos, audios) como adjuntos reales dentro del email (las imágenes se renderizan directamente inline con CID).

6. Gestión de Plantillas

Las plantillas son fundamentales para iniciar conversaciones después de 24 horas de inactividad del cliente.

• Creación (Administradores): El administrador puede definir plantillas completando el nombre en minúsculas sin espacios, categoría, idioma y contenido del mensaje.
• Sincronización: Si hay credenciales de Meta válidas, las plantillas se sincronizan directamente con su cuenta de Meta Cloud API. Si no están configuradas, se mantendrán en caché local para simulación de flujos de prueba.

7. Envío por Lotes (Pestaña Contacto)

Los envíos estructurados se asocian bajo un ID numérico de Lote (idlote) para fines de control de campañas.

• Asignación: Al enviar una plantilla, defina un número de lote en la caja de configuración respectiva.
• Acordeón de Contactos: En la pestaña "Contacto", expanda los acordeones numéricos de cada lote para visualizar, con nombre y avatar, a qué destinatarios pertenecen los mensajes de campaña.

8. Ajustes de Configuración (WhatsApp API y SMTP)

Los administradores pueden abrir el modal de ajustes (ícono de engranaje) el cual presenta una disposición en dos columnas:

• WhatsApp API (Lado Izquierdo):
  • Access Token: Credencial de autenticación de Meta.
  • Phone Number ID & WABA ID: Identificadores de su número de teléfono y cuenta comercial.
  • Verify Token: Token de verificación local para el enlace seguro de Webhooks.
  • Carga de Logo General: Carga de un logotipo corporativo que actualiza la imagen superior izquierda y se almacena persistente como Base64 en base de datos.
• Servidor de Correo SMTP (Lado Derecho):
  • Servidor SMTP & Puerto: Datos del host de salida y su puerto (ej: mail.servidor.com, puerto 465).
  • Seguridad: SSL, TLS o Ninguno.
  • Usuario y Contraseña: Credenciales del correo de salida. Las contraseñas se guardan encriptadas de forma segura con AES-256-CBC y se ocultan en la pantalla.
  • Remitente visible: Cuenta de correo remitente.

9. Bitácora de Actividad

Todas las acciones de seguridad (logins/logouts), modificación de configuraciones generales o de correo, reenvíos de chats por email (incluyendo destinatario y asunto), envíos de plantillas por lotes y eliminaciones de registros se escriben detalladamente en la base de datos en la tabla wapp_actividad, relacionando la hora exacta, tipo de acción y el usuario que realizó la operación para auditorías internas.

10. Asistente de Inteligencia Artificial (Gemini)

El sistema cuenta con una integración avanzada de IA (utilizando la API REST de Google Gemini) para automatizar el servicio de atención al cliente y responder preguntas comunes basadas en este manual de usuario de forma autónoma.

Configuración (Solo Admin): El usuario con nombre de usuario exacto admin visualizará un botón con un icono de robot al lado de la rueda de configuración en la barra lateral del operador. Al hacer clic, se despliega un panel de ajustes draggable donde se puede configurar:

• Habilitar respuestas IA: Casilla de verificación para activar o desactivar las respuestas del bot.
• Modelo de IA: Permite ingresar el modelo a usar (por defecto gemini-2.5-flash).
• Gemini API Key: La clave de API de Gemini, almacenada de forma encriptada y segura.
• Teléfono de Asistencia Humana: Número de contacto de soporte (por defecto +5493364536143).
• Instrucciones del Sistema (Prompt): Instrucciones que dictan el comportamiento y tono del bot. Si el bot detecta que no puede ayudar o que el usuario solicita hablar con un humano, el bot referirá al cliente a este número mediante el marcador {HUMAN_PHONE}.

Funcionamiento en tiempo real: Cuando llega un mensaje del contacto, si las respuestas automáticas de la IA están habilitadas, el sistema extrae el historial de los últimos 15 mensajes, los formatea cumpliendo la alternancia estricta de roles y realiza una llamada HTTP asíncrona a Gemini. El bot genera la respuesta basada en el manual de usuario, envía el mensaje de WhatsApp a través de la API oficial de Meta y actualiza el chat del operador web instantáneamente.