# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/dfwhatsapp/>
- Lingua: it
- Aggiornato il: 2026-08-02
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfwhatsapp/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsapp/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsapp/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsapp/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsapp/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsapp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsapp/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

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

**Consiglio:** il modulo crea automaticamente 6 tabelle nel tuo database e aggiunge due voci di menu in **Vendi > Catalogo** per la gestione degli agenti e la dashboard analytics.

## 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")

**Da notare:** puoi anche aggiungere eccezioni _globali_ che si applicano a tutti gli agenti lasciando l'ID agente a 0 nel database.

## 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

**Conformità GDPR:**

- Consenso esplicito mostrato prima di ogni apertura di WhatsApp
- IP dei visitatori sottoposto a hash **SHA-256** con un sale specifico del tuo negozio (`PS_SHOP_DOMAIN` più `_COOKIE_KEY_`)
- Nessun dato personale diretto memorizzato
- Nessun cookie di terze parti depositato

## 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](mailto: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+