DataFirefly WhatsApp: documentazione

Benvenuto nella documentazione del modulo DataFirefly WhatsApp. Questa guida copre tutto ciò che ti serve per installare, configurare e sfruttare al massimo il tuo pulsante WhatsApp flottante multi-agente su PrestaShop 8 e 9.

Installazione

Il modulo si installa come qualsiasi altro modulo PrestaShop, in pochi clic.

Requisiti

• PrestaShop 8.0.x o 9.0.x
• PHP 8.0 o superiore (consigliato 8.1+)
• MySQL 5.6+ o MariaDB 10.3+
• Almeno un numero WhatsApp (personale o Business)

Passaggi di installazione

1. Scarica il file dfwhatsapp-v1.0.0.zip dalla tua area cliente DataFirefly
2. Nel back office PrestaShop, vai su Moduli > Gestore moduli
3. Clicca su Carica un modulo in alto a destra
4. Seleziona il file ZIP e conferma
5. Clicca su Installa quando il modulo compare
6. Clicca su Configura per aprire la schermata dei parametri

Configurazione generale

La pagina di configurazione del modulo è organizzata in 6 schede per permetterti di impostare tutto senza perderti.

Scheda Generale

• Attiva il modulo: interruttore principale, disattiva il pulsante su tutto il negozio
• Modalità di selezione dell’agente: round-robin, casuale, primo disponibile o manuale
• Attiva il tracking: necessario per alimentare la dashboard analytics
• QR code desktop: mostra un QR code invece di aprire WhatsApp Web sulle postazioni fisse

Scheda Aspetto

• Posizione: quattro angoli possibili (basso a destra, basso a sinistra, alto a destra, alto a sinistra)
• Colore: per impostazione predefinita il verde WhatsApp #25D366
• Dimensione dell’icona: in pixel (predefinito 60)
• Scostamento X / Y: distanza dal bordo dello schermo
• Animazione: pulse, bounce, shake o nessuna
• Etichetta testuale: etichetta opzionale mostrata accanto al pulsante

Scheda Messaggi

Un messaggio precompilato distinto per ogni tipo di pagina (prodotto, carrello, categoria, CMS, ordine, home), tradotto nelle 4 lingue incluse.

Scheda Orari

• Modalità fuori orario:
  • hide: il pulsante scompare completamente
  • show_offline: il pulsante resta visibile in grigio con un messaggio di attesa
  • callback: un modulo di richiamata sostituisce la conversazione diretta
• Messaggio fuori orario: testo mostrato quando tutti gli agenti sono offline

Scheda GDPR

• Attiva il consenso: mostra un testo di consenso prima di ogni apertura di WhatsApp
• Testo del consenso: personalizzabile per lingua

Scheda Esclusioni

• Pagine escluse: elenco di controller (ad esempio checkout, identity)
• Categorie escluse: ID di categorie separati da virgole
• Prodotti esclusi: ID di prodotti separati da virgole

Gestione degli agenti

Il cuore del modulo: qui aggiungi le persone che riceveranno i messaggi WhatsApp.

Aggiungere un agente

1. Vai su Vendi > Catalogo > Agenti WhatsApp
2. Clicca su Aggiungi
3. Compila:
   • Nome: nome mostrato al cliente (ad esempio “Alex”)
   • Telefono: in formato internazionale senza spazi (ad esempio 33604525981)
   • Reparto: libero (Supporto, Vendite, Tecnico…)
   • Avatar: immagine opzionale (png, jpg, svg, webp)
   • Posizione: ordine di visualizzazione in modalità manuale
   • Ruolo: testo tradotto nelle 4 lingue (ad esempio “Supporto tecnico”)
   • Messaggio personalizzato: sovrascrittura opzionale dei messaggi contestuali

Configurare gli orari di un agente

Direttamente nel modulo dell’agente, una tabella settimanale ti permette di definire:

• Più fasce orarie al giorno (ad esempio 9:00-12:30 e 14:00-18:30)
• Un giorno vuoto significa agente offline quel giorno
• Un agente senza alcuna fascia definita è considerato sempre online (modalità 24/7)

Aggiungere un’eccezione (festività, ferie)

1. Nel modulo dell’agente, sezione Eccezioni
2. Inserisci una data di inizio e una data di fine
3. Aggiungi un’etichetta opzionale (ad esempio “Ferie estive”)

Variabili contestuali

I messaggi precompilati supportano 12 variabili che vengono sostituite al volo in base alla pagina in cui si trova il cliente:

• {product_name}: nome del prodotto (pagina prodotto)
• {product_url}: URL completo del prodotto
• {product_price}: prezzo formattato con valuta
• {product_ref}: riferimento prodotto
• {customer_name}: nome del cliente se connesso
• {cart_id}: ID del carrello
• {cart_total}: totale del carrello formattato
• {cart_summary}: elenco degli articoli nel carrello
• {order_ref}: riferimento dell’ordine
• {order_total}: totale dell’ordine
• {category_name}: nome della categoria corrente
• {shop_name}: nome del negozio

Modalità di instradamento degli agenti

Round-robin

Il modulo alterna gli agenti disponibili a ogni nuova apertura, bilanciando naturalmente il carico.

Casuale

Un agente viene estratto a sorte tra quelli online. Utile quando l’equità tra agenti non è critica.

Primo disponibile

Viene selezionato il primo agente dell’elenco (secondo la posizione) che è attualmente online.

Manuale

Al cliente viene mostrato un popup con l’elenco degli agenti disponibili (avatar, nome, ruolo, stato). Il cliente sceglie da sé il proprio interlocutore.

Analytics e GDPR

La dashboard

Accessibile da Vendi > Catalogo > WhatsApp Analytics, mostra:

• Totale dei clic nel periodo
• Numero di visitatori unici (tramite hash IP)
• Rapporto clic per visitatore
• Ripartizione per giorno, per tipo di pagina, per agente
• Top 20 dei prodotti che innescano conversazioni

Protezione dei dati

QR code su desktop

Sui computer desktop, invece di aprire WhatsApp Web (che richiede al cliente una scansione sistematica del QR code), puoi attivare la modalità QR code diretta:

• Il modulo genera un QR code contenente il link wa.me con il messaggio precompilato
• Il cliente lo scansiona con il telefono
• WhatsApp si apre direttamente sul suo cellulare con il messaggio pronto da inviare

Questa modalità mantiene la conversazione sul canale preferito dal cliente senza attrito aggiuntivo.

Modulo di richiamata

Quando tutti i tuoi agenti sono offline e hai scelto la modalità callback:

1. Il cliente vede un modulo al posto della conversazione abituale
2. Inserisce nome, telefono e un messaggio opzionale
3. La richiesta viene salvata nella tabella ps_dfwhatsapp_callback con stato pending
4. Puoi consultare le richieste tramite phpMyAdmin o creare un report personalizzato

Multilingua

Il modulo è fornito con 4 lingue complete: francese, inglese, spagnolo, tedesco. Tutti i testi visibili lato cliente sono tradotti:

• Messaggi contestuali per pagina
• Testo del consenso GDPR
• Messaggio del popup di benvenuto
• Etichette degli agenti (ruolo, stato)
• Interfaccia del modulo di richiamata
• Messaggio fuori orario

Puoi anche definire un ruolo e un messaggio personalizzato diversi per ogni lingua e per ogni agente, direttamente dal modulo dell’agente cambiando la scheda della lingua.

Compatibilità

• PrestaShop 8.0.x, 8.1.x, 8.2.x, 9.0.x
• PHP da 8.0 a 8.3
• Multinegozio sì (configurazioni distinte per negozio)
• Multilingua sì (Polylang non richiesto)
• Cache compatibile (Hummingbird, LSCache, Redis)
• Override di classi core: nessuno

Risoluzione dei problemi

Il pulsante non compare

1. Verifica che il modulo sia attivo in Generale
2. Verifica che esista almeno un agente con stato Attivo
3. Verifica che la pagina corrente non sia nell’elenco delle esclusioni
4. Svuota la cache di PrestaShop (Parametri avanzati > Prestazioni)
5. Svuota la cache del browser (Ctrl+Shift+R)

Il clic sul pulsante non fa nulla

1. Apri la console del browser (F12) e verifica che non ci siano errori JavaScript
2. Verifica che nessun altro modulo blocchi il JS del modulo
3. Verifica che dfwhatsapp.js sia effettivamente caricato nell’HTML

Le statistiche non aumentano

1. Verifica che il tracking sia attivo in Generale
2. Verifica che nessun blocco pubblicità lato cliente filtri l’URL module/dfwhatsapp/track
3. Consulta la tabella ps_dfwhatsapp_click per vedere se gli eventi arrivano

Errore SQL “LIMIT 1 LIMIT 1”

Corretto nella versione 1.0.1. Aggiorna il modulo all’ultima versione dalla tua area cliente DataFirefly.

Supporto e aggiornamenti

• Supporto via email: hello@datafirefly.com
• Aggiornamenti inclusi per 12 mesi dalla tua area cliente
• Compatibilità da PS 8 a PS 9 garantita senza sovrapprezzo

Changelog

1.0.0, 13 maggio 2026, lancio

• Prima versione pubblica
• Multi-agente con quattro modalità di instradamento
• Orari settimanali per agente con eccezioni
• Popup di benvenuto, QR code desktop, modulo di richiamata
• Consenso GDPR nativo e analytics con IP sottoposto a hash
• Quattro lingue: FR, EN, ES, DE
• Compatibile con PrestaShop 8.0+ e 9.0+