# WhatsApp Commerce Suite Shopware — Guida di installazione e configurazione
> Prerequisiti Shopware 6.5, 6.6 o 6.7 (un unico codice), PHP 8.1 minimo Un account WhatsApp Business con un numero verificato in Meta Business Suite Un'app Meta di tipo Business con…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-08-06
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfwhatsappcommerce-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsappcommerce-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsappcommerce-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsappcommerce-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsappcommerce-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsappcommerce-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsappcommerce-shopware/index.md)
- Indice:
## Prerequisiti
- Shopware 6.5, 6.6 o 6.7 (un unico codice), PHP 8.1 minimo
- Un account **WhatsApp Business** con un numero verificato in Meta Business Suite
- Un'app Meta di tipo **Business** con il prodotto WhatsApp attivato
- Il worker delle code e il runner delle attività pianificate di Shopware attivi (`messenger:consume` e `scheduled-task:run`)
## Installazione
1. Copiate la cartella `DfWhatsAppCommerce` in `custom/plugins/` (o caricate lo zip via Estensioni → Le mie estensioni).
2. Installate e attivate: ``` bin/console plugin:refresh bin/console plugin:install --activate DfWhatsAppCommerce bin/console cache:clear ```
3. Compilate l'amministrazione e lo storefront: ``` bin/build-administration.sh bin/build-storefront.sh ```
L'installazione crea 5 tabelle dedicate con prefisso `df_wac_` e 2 attività pianificate (promemoria carrello ogni 15 min, batch catalogo orario). Tutto viene rimosso in modo pulito alla disinstallazione, a meno che non selezioniate «conserva i dati».
## Configurazione Meta Cloud API
### 1. Ottenere le credenziali
Su [developers.facebook.com](https://developers.facebook.com), create un'app Business e aggiungete il prodotto WhatsApp. Ottenete: il **token permanente** (utente di sistema con permessi `whatsapp_business_messaging` e `catalog_management`), il **Phone number ID**, il **WABA ID** e l'**App secret** (Impostazioni app → Di base).
### 2. Creare il catalogo
In Meta Commerce Manager, create un catalogo e collegatelo al vostro account WhatsApp Business. Annotate l'**ID del catalogo**.
### 3. Configurare il webhook
Nell'app Meta → WhatsApp → Configurazione:
- URL di callback: `https://vostronegozio.tld/df-wac/webhook`
- Token di verifica: il valore inserito nella configurazione del plugin (campo «Webhook verify token»)
- Iscrivetevi al campo `messages`
Inserite l'**App secret** nella configurazione del plugin: senza di esso, la firma `X-Hub-Signature-256` dei webhook non viene validata.
### 4. Inserire la configurazione in Shopware
Impostazioni → Sistema → Plugin → DataFirefly WhatsApp Commerce Suite. Compilate la scheda «Meta Cloud API», poi testate dalla dashboard (Marketing → WhatsApp Commerce): pulsante **Testa connessione API** e invio di un messaggio di prova.
## I 4 moduli
### Catalogo Meta
Tre modalità: tempo reale (a ogni salvataggio del prodotto), batch orario, o manuale. Le varianti vengono inviate singolarmente con il `retailer_id` `sw_{numero articolo}`. Escludete categorie se necessario. La risincronizzazione completa (batch da 100) si avvia dalla dashboard.
### Ordini conversazionali
Macchina a stati a 6 livelli. Parole chiave riconosciute (FR/EN/DE): `menu`, `cart`, `pay`, `human`, `reset`, `help`. La lingua del cliente viene rilevata automaticamente. Il trasferimento umano invia un'e-mail all'indirizzo configurato con il link della conversazione.
### Recupero carrelli abbandonati
3 promemoria configurabili (60 min, 24 h, 72 h di default) inviati dall'attività pianificata ogni 15 minuti ai clienti di cui è noto il telefono di fatturazione. Il codice promo inserito nella configurazione viene allegato al 3° promemoria e applicato automaticamente al carrello ripristinato.
Rendete obbligatorio il campo telefono in Impostazioni → Negozio → Accesso / registrazione per massimizzare la copertura dei promemoria.
### Link di pagamento firmato e notifiche
I link di checkout e di recupero carrello sono firmati HMAC SHA-256 con scadenza configurabile (72 h di default). Notifiche automatiche: conferma ordine, spedizione (con numero di tracking), pagamento fallito.
## Template HSM da creare in Meta Business Suite
| Template | Variabili del corpo | Pulsante |
| --- | --- | --- |
| Promemoria 1 e 2 | {{1}} nome cliente, {{2}} totale carrello | URL dinamico (suffisso = token) |
| Promemoria 3 | {{1}} nome, {{2}} totale, {{3}} codice promo | URL dinamico (suffisso = token) |
| Conferma | {{1}} nome, {{2}} n° ordine, {{3}} totale | — |
| Spedizione | {{1}} nome, {{2}} n° ordine, {{3}} n° tracking | CTA tracking (opzionale) |
| Pagamento fallito | {{1}} nome, {{2}} n° ordine | CTA riprova (opzionale) |
Per i promemoria, il pulsante URL del template deve avere come base `https://vostronegozio.tld/df-wac/cart/restore?token=` con suffisso dinamico `{{1}}`. Inserite i nomi dei template approvati nella configurazione del plugin.
## Amministrazione
Marketing → WhatsApp Commerce: dashboard KPI (conversazioni, non letti, carrelli, tasso di recupero, errori), pagina **Conversazioni** (thread in stile WhatsApp Web, risposta diretta), **Carrelli abbandonati**, **Catalogo** (registro di sincronizzazione) e **Log** (filtri per livello/canale).
Regola Meta: le risposte libere dall'admin vengono consegnate solo entro 24 h dall'ultimo messaggio del cliente. Oltre, utilizzate un template HSM.
## Risoluzione dei problemi
- **Non appare nulla nel frontend**: verificate che il «Numero WhatsApp pubblico» sia impostato (il pulsante flottante e i CTA ne dipendono), poi `bin/console cache:clear`.
- **Webhook 403**: token di verifica diverso tra Meta e il plugin, o App secret errato.
- **Promemoria non inviati**: verificate che `scheduled-task:run` e `messenger:consume` siano attivi, che il modulo sia abilitato e che i template HSM siano approvati.
- **Prodotti non sincronizzati**: consultate la pagina Catalogo (stati pending/synced/error) e i Log, canale `catalog`.
## GDPR
Nessun dato viene inviato a terzi al di fuori della Meta WhatsApp Cloud API. Le conversazioni e i numeri sono memorizzati localmente nelle tabelle `df_wac_` e rimossi alla disinstallazione.