DataFirefly WhatsApp — Documentación

Bienvenido a la documentación del módulo DataFirefly WhatsApp. Esta guía cubre todo lo que necesitas para instalar, configurar y sacar el máximo partido a tu botón de WhatsApp flotante multi-agente en PrestaShop 8 y 9.

Instalación

El módulo se instala como cualquier otro módulo de PrestaShop, en unos pocos clics.

Requisitos

• PrestaShop 8.0.x o 9.0.x
• PHP 8.0 o superior (8.1+ recomendado)
• MySQL 5.6+ o MariaDB 10.3+
• Al menos un número de WhatsApp (personal o Business)

Pasos de instalación

1. Descarga el archivo dfwhatsapp-v1.0.0.zip desde tu área de cliente DataFirefly
2. En el back-office de PrestaShop, ve a Módulos > Gestor de Módulos
3. Haz clic en Subir un módulo arriba a la derecha
4. Selecciona el archivo ZIP y confirma
5. Haz clic en Instalar cuando aparezca el módulo
6. Haz clic en Configurar para abrir la pantalla de ajustes

Configuración general

La página de configuración del módulo está organizada en 6 pestañas para ayudarte a configurarlo todo sin perderte.

Pestaña General

• Activar módulo: interruptor principal, desactiva el botón en toda la tienda
• Modo de selección de agente: round-robin, aleatorio, primer disponible o manual
• Activar tracking: necesario para alimentar el panel de analíticas
• Código QR de escritorio: muestra un código QR en lugar de abrir WhatsApp Web en ordenadores fijos

Pestaña Apariencia

• Posición: cuatro esquinas posibles (abajo-derecha, abajo-izquierda, arriba-derecha, arriba-izquierda)
• Color: por defecto el verde de WhatsApp #25D366
• Tamaño del icono: en píxeles (por defecto 60)
• Desplazamiento X / Y: distancia desde el borde de la pantalla
• Animación: pulse, bounce, shake o ninguna
• Etiqueta de texto: etiqueta opcional mostrada junto al botón

Pestaña Mensajes

Un mensaje pre-rellenado distinto para cada tipo de página (producto, carrito, categoría, CMS, pedido, inicio), traducido a los 4 idiomas incluidos.

Pestaña Horario

• Modo fuera de horario:
  • hide — el botón desaparece completamente
  • show_offline — el botón sigue visible en gris con un mensaje de espera
  • callback — un formulario de rellamada reemplaza la conversación directa
• Mensaje fuera de horario: texto mostrado cuando todos los agentes están fuera de línea

Pestaña RGPD

• Activar consentimiento: muestra un texto de consentimiento antes de cada apertura de WhatsApp
• Texto del consentimiento: personalizable por idioma

Pestaña Exclusiones

• Páginas excluidas: lista de controladores (por ej. checkout, identity)
• Categorías excluidas: IDs de categorías separados por comas
• Productos excluidos: IDs de productos separados por comas

Gestión de agentes

El corazón del módulo: aquí es donde añades las personas que recibirán los mensajes de WhatsApp.

Añadir un agente

1. Ve a Vender > Catálogo > Agentes WhatsApp
2. Haz clic en Añadir
3. Rellena:
   • Nombre — nombre mostrado al cliente (ej. «Alex»)
   • Teléfono — formato internacional sin espacios (ej. 33604525981)
   • Departamento — libre (Soporte, Ventas, Técnico…)
   • Avatar — imagen opcional (png, jpg, svg, webp)
   • Posición — orden de visualización en modo manual
   • Rol — texto traducido en 4 idiomas (ej. «Soporte técnico»)
   • Mensaje personalizado — sobreescritura opcional de los mensajes contextuales

Configurar el horario de un agente

Directamente en el formulario del agente, una tabla semanal te permite definir:

• Múltiples franjas por día (por ej. 9:00-12:30 + 14:00-18:30)
• Un día vacío = agente fuera de línea ese día
• Un agente sin ninguna franja definida se considera siempre en línea (modo 24/7)

Añadir una excepción (festivo, vacaciones)

1. En el formulario del agente, sección Excepciones
2. Introduce una fecha de inicio y una fecha de fin
3. Añade una etiqueta opcional (ej. «Vacaciones de verano»)

Variables contextuales

Los mensajes pre-rellenados admiten 12 variables que se reemplazan al vuelo según la página en la que se encuentra el cliente:

• {product_name} — nombre del producto (ficha de producto)
• {product_url} — URL completa del producto
• {product_price} — precio formateado con la divisa
• {product_ref} — referencia del producto
• {customer_name} — nombre del cliente si está conectado
• {cart_id} — ID del carrito
• {cart_total} — total del carrito formateado
• {cart_summary} — lista de artículos del carrito
• {order_ref} — referencia del pedido
• {order_total} — total del pedido
• {category_name} — nombre de la categoría actual
• {shop_name} — nombre de la tienda

Modos de enrutamiento de agentes

Round-robin

El módulo alterna entre los agentes disponibles en cada nueva apertura, equilibrando naturalmente la carga.

Aleatorio

Se elige un agente al azar de los que están en línea. Útil cuando la equidad entre agentes no es crítica.

Primer disponible

Se selecciona el primer agente de la lista (según su posición) que esté actualmente en línea.

Manual

Aparece un popup al cliente con la lista de agentes disponibles (avatar, nombre, rol, estado). El cliente elige él mismo con quién hablar.

Analíticas y RGPD

El panel

Accesible desde Vender > Catálogo > Analíticas WhatsApp, te muestra:

• Total de clics en el período
• Número de visitantes únicos (mediante hashing de IP)
• Ratio de clics por visitante
• Reparto por día, por tipo de página, por agente
• Top 20 de productos que disparan conversaciones

Protección de datos

Código QR en escritorio

En ordenadores de sobremesa, en lugar de abrir WhatsApp Web (que requiere un escaneo sistemático del código QR por parte del cliente), puedes activar el modo QR directo:

• El módulo genera un código QR que contiene el enlace wa.me con el mensaje pre-rellenado
• El cliente lo escanea con su teléfono
• WhatsApp se abre directamente en su móvil con el mensaje listo para enviar

Este modo mantiene la conversación en el canal preferido del cliente sin fricción adicional.

Formulario de rellamada

Cuando todos tus agentes están fuera de línea y has elegido el modo callback:

1. El cliente ve un formulario en lugar de la conversación habitual
2. Introduce su nombre, su teléfono y un mensaje opcional
3. La solicitud se almacena en la tabla ps_dfwhatsapp_callback con estado pending
4. Puedes consultar las solicitudes mediante phpMyAdmin o construir un informe personalizado

Multilingüe

El módulo viene con 4 idiomas completos: francés, inglés, español, alemán. Todos los textos visibles del lado del cliente están traducidos:

• Mensajes contextuales por página
• Texto de consentimiento RGPD
• Mensaje del popup de bienvenida
• Etiquetas de agentes (rol, estado)
• Interfaz del formulario de rellamada
• Mensaje fuera de horario

También puedes definir un rol y un mensaje personalizado diferentes para cada idioma y cada agente, directamente desde el formulario del agente cambiando la pestaña de idioma.

Compatibilidad

• PrestaShop 8.0.x, 8.1.x, 8.2.x, 9.0.x
• PHP 8.0 a 8.3
• Multitienda sí (configuraciones distintas por tienda)
• Multi-idioma sí (Polylang no requerido)
• Caché compatible (Hummingbird, LSCache, Redis)
• Override de clase core: ninguno

Resolución de problemas

El botón no aparece

1. Comprueba que el módulo está activado en General
2. Comprueba que existe al menos un agente con estado Activo
3. Comprueba que la página actual no está en la lista de exclusiones
4. Vacía la caché de PrestaShop (Parámetros avanzados > Rendimiento)
5. Vacía la caché del navegador (Ctrl+Shift+R)

El clic en el botón no hace nada

1. Abre la consola del navegador (F12) y comprueba que no hay errores de JavaScript
2. Comprueba que ningún otro módulo bloquea el JS del módulo
3. Comprueba que dfwhatsapp.js está bien cargado en el HTML

Las estadísticas no se incrementan

1. Comprueba que el tracking está activado en General
2. Comprueba que ningún bloqueador de anuncios del lado del cliente filtra la URL module/dfwhatsapp/track
3. Consulta la tabla ps_dfwhatsapp_click para ver si los eventos están llegando

Error SQL «LIMIT 1 LIMIT 1»

Corregido en la versión 1.0.1. Actualiza tu módulo a la última versión desde tu área de cliente DataFirefly.

Soporte y actualizaciones

• Soporte por email: hello@datafirefly.com
• Actualizaciones incluidas durante 12 meses desde tu área de cliente
• Compatibilidad PS 8 → 9 garantizada sin coste adicional

Changelog

1.0.0 — 13 de mayo de 2026 — Lanzamiento

• Versión inicial pública
• Multi-agente con cuatro modos de enrutamiento
• Horario semanal por agente con excepciones
• Popup de bienvenida, código QR en escritorio, formulario de rellamada
• Consentimiento RGPD nativo y analíticas con IP cifrada
• Cuatro idiomas: FR, EN, ES, DE
• Compatible con PrestaShop 8.0+ y 9.0+