Agente IA Assistenza Clienti — Documentazione completa

Guida completa all’installazione, configurazione e utilizzo del plugin DataFirefly AI Customer Service Agent — un agente IA di assistenza clienti per WooCommerce che comprende il contesto, chiama strumenti in sola lettura sul tuo negozio, ed esegue l’escalation intelligente dei casi complessi a Slack ed email.

1. Prerequisiti

• WordPress 6.4 o superiore
• WooCommerce 8.0 o superiore
• PHP 8.1, 8.2 o 8.3
• Una chiave API di Anthropic (Claude) o OpenAI (consigliato: Claude Sonnet 4.5)
• Opzionale: un webhook Slack per l’escalation in tempo reale
• Opzionale: Polylang Pro o WPML se il tuo negozio è multilingue

2. Installazione

Installazione dello ZIP

1. Dal tuo account DataFirefly, scarica il file df-ai-customer-service.zip
2. In WordPress, vai a Plugin → Aggiungi nuovo → Carica plugin
3. Seleziona lo ZIP e clicca su Installa ora
4. Clicca su Attiva una volta completata l’installazione

Cosa succede all’attivazione?

Il plugin crea automaticamente 5 tabelle nel database prefissate wp_dfaics_: conversations, messages, escalations, faq, analytics. Dichiara anche la compatibilità HPOS e i blocchi Gutenberg cart/checkout, e pianifica un task cron giornaliero per pulire le conversazioni scadute.

3. Configurazione del provider IA

Il plugin supporta due provider IA. Scegli quello preferito in AI Support → Impostazioni → IA. Porti la tua chiave API — DataFirefly non fa da proxy e non trattiene nulla dal tuo consumo.

Opzione A: Claude (consigliato)

1. Crea un account su console.anthropic.com
2. Genera una chiave API in Settings → API Keys
3. Copia la chiave (inizia con sk-ant-...)
4. In WordPress, vai a AI Support → Impostazioni → IA
5. Seleziona il provider Anthropic (Claude)
6. Incolla la tua chiave nel campo Chiave API Anthropic
7. Modello predefinito: claude-sonnet-4-5 (eccellente rapporto qualità / prezzo)
8. Clicca su Testa chiave per validare
9. Salva

Opzione B: OpenAI

1. Crea un account su platform.openai.com
2. Genera una chiave API in API Keys
3. Copia la chiave (inizia con sk-...)
4. In WordPress, seleziona il provider OpenAI
5. Modello predefinito: gpt-4o-mini (il più economico con tool calling affidabile)

Costo indicativo

Una conversazione tipica di 5-10 turni con tool calling costa:

• Circa 0,01 a 0,05 USD con Claude Sonnet 4.5
• Circa 0,005 a 0,02 USD con GPT-4o mini

La dashboard mostra il totale dei token input/output consumati nel periodo.

4. Configurazione del widget

Il widget di chat appare di default in basso a destra su tutte le pagine del frontend. Personalizzalo in AI Support → Impostazioni → Widget.

Opzioni di aspetto

• Colore principale — Colore del pulsante flottante e dell’header (default #0073aa)
• Colore del testo — Colore del testo dell’header (default bianco)
• Posizione — In basso a destra o a sinistra
• Titolo widget — Es. «Hai bisogno di aiuto?»
• Messaggio di benvenuto — Primo messaggio mostrato all’apertura
• Placeholder — Testo del campo di input
• Mostra badge DataFirefly — Piccola menzione a piè di widget

Visualizzazione condizionale

Nella scheda Widget, puoi limitare dove appare il widget:

• Tutte le pagine — Comportamento predefinito
• Solo pagine prodotto — Per supporto mirato sulle schede
• Eccetto carrello e checkout — Evitare distrazioni durante l’acquisto
• Nascondi su questi ID di contenuto — Lista di ID da escludere

Shortcode

Puoi anche integrare la chat in una pagina o articolo con lo shortcode:

[dfaics_chat]

Questo mostra il widget in modalità integrata (non flottante), utile per una pagina «Contattaci» dedicata.

5. I 6 strumenti dell’agente

L’agente dispone di 6 strumenti che sceglie di chiamare o meno in base alla domanda. Tutti sono rigorosamente in sola lettura. Li attivi o disattivi individualmente in Impostazioni → Comportamento.

lookup_order

Recupera lo stato di un ordine WooCommerce. Richiede la verifica email obbligatoria prima della divulgazione: l’agente chiede l’email al cliente e la confronta con quella dell’ordine. Restituisce numero, stato, importo, data, metodo di spedizione, numero di tracking se disponibile.

search_products

Cerca nel catalogo per nome, categoria, tag, disponibilità, fascia di prezzo. Restituisce fino a 5 risultati di default con titolo, SKU, prezzo, URL, giacenza. Utile per rispondere a «lo avete in blu?» o «qual è il prezzo di X?».

get_shipping_info

Restituisce le zone e i metodi di spedizione configurati in WooCommerce, con costi e tempi. L’agente può rispondere precisamente a «spedite in Belgio?» o «quanto costa l’express?».

get_returns_policy

Restituisce il contenuto della tua politica dei resi (che configuri nelle impostazioni). L’agente può spiegare tempi, procedura e condizioni.

search_faq

Cerca nelle tue FAQ personalizzate (gestite in AI Support → FAQ). I risultati sono scoped per lingua della conversazione. Ogni voce trovata incrementa un contatore d’uso per aiutarti a identificare le domande più frequenti.

escalate_to_human

L’agente chiama questo strumento quando determina che un caso richiede un umano (frustrazione cliente, caso complesso, fallimenti ripetuti di strumenti). Attiva le notifiche Slack e/o email configurate. Vedi la sezione Escalation più avanti.

6. Gestione FAQ

Crea voci FAQ personalizzate che l’agente può cercare durante una conversazione. Ogni voce è scoped per lingua.

Creare una voce

1. Vai a AI Support → FAQ
2. Clicca su Aggiungi voce
3. Scegli la lingua
4. Redigi domanda e risposta in linguaggio naturale
5. Aggiungi parole chiave separate da virgole (opzionale, migliora la ricerca)
6. Scegli una categoria (es. spedizione, taglie, garanzia)
7. Salva

Buone pratiche FAQ

• Formula le domande come le farebbe un cliente, non come un copywriter SEO
• Risposte brevi e azionabili (2-4 frasi bastano, l’agente riformula)
• Crea una voce per lingua principale della tua clientela
• Consulta regolarmente il contatore d’uso per identificare domande da arricchire

7. Escalation a un umano

L’escalation si configura in Impostazioni → Escalation. Due canali sono supportati in parallelo: Slack e email.

Configurazione Slack

1. In Slack, crea una nuova app su api.slack.com/apps
2. Attiva Incoming Webhooks
3. Crea un webhook al canale desiderato (es. #support-escalations)
4. Copia l’URL del webhook
5. In WordPress, incollalo in Webhook Slack
6. Clicca su Testa webhook per inviare un messaggio di test

Ogni escalation invia a Slack un messaggio in blocchi ricchi con: estratto degli ultimi 3 messaggi, motivo dell’escalation, metadati cliente (email verificata, lingua, pagina di origine) e un pulsante Apri in admin che punta direttamente al dettaglio della conversazione.

Configurazione email

In Email di escalation, indica uno o più indirizzi separati da virgole. Ogni escalation invia un’email HTML con la trascrizione completa, i dati cliente e un link all’admin.

Trigger di escalation

L’agente esegue l’escalation in 3 situazioni:

1. Parole chiave sensibili — Lista configurabile (default: rimborso, avvocato, rotto, reclamo, refund, lawyer, broken, complaint)
2. Soglia di sentimento — Rilevamento di frustrazione o insoddisfazione (regolabile da -1 a 0)
3. Fallimento ripetuto di strumenti — Dopo 6 turni senza risoluzione, escalation forzata

8. Dashboard e analytics

La dashboard AI Support → Dashboard mostra 4 indicatori chiave:

• Volume — Numero totale di conversazioni negli ultimi 7, 30 o 90 giorni
• Tasso di auto-risoluzione — % di conversazioni che terminano senza escalation
• Soddisfazione media — Valutazione in stelle data dai clienti dopo l’escalation
• Token consumati — Input + output cumulativi per stimare il costo IA

La pagina Conversazioni lista tutte le sessioni con filtri (lingua, stato, escalation sì/no). Clicca su una riga per vedere la trascrizione completa con i tool call dettagliati in JSON.

9. Multilingue

Il plugin supporta nativamente 5 lingue: francese, inglese, spagnolo, tedesco, italiano. La lingua della conversazione viene risolta automaticamente in questo ordine:

1. Lingua Polylang della pagina dove è mostrato il widget (se Polylang installato)
2. Lingua WPML della pagina (se WPML installato)
3. Locale del browser del visitatore
4. Lingua di fallback configurata nelle impostazioni (default: inglese)

Il system prompt dell’agente indica esplicitamente al modello la lingua di risposta attesa. Questo garantisce che un visitatore francese riceva una risposta in francese, anche se il tuo negozio è prevalentemente inglese.

10. Sicurezza e privacy

Cifratura chiavi API

Le chiavi Anthropic, OpenAI e il webhook Slack sono cifrati in AES-256-CBC al momento del salvataggio, con una chiave derivata da AUTH_KEY + AUTH_SALT. Il campo di input non rivisualizza mai il valore: lasciando il campo vuoto e salvando, il valore precedente viene preservato.

Verifica email per ordini

Lo strumento lookup_order richiede obbligatoriamente verifica: l’agente chiede al cliente la sua email e la confronta con quella associata all’ordine. Senza corrispondenza, nessun dato viene divulgato. Questo comportamento non è disattivabile — protegge dallo scraping degli ordini via l’agente.

Rate limiting

Viene applicato un rate limit anti-spam lato server di 5 messaggi al minuto per sessione. Il numero massimo di messaggi per conversazione è 25 di default (configurabile). Oltre, l’agente propone un’escalation umana.

Ritenzione e GDPR

Le conversazioni sono conservate 30 giorni di default, poi eliminate automaticamente da un cron giornaliero. Puoi ridurre questa durata in Impostazioni → Privacy. L’IP del visitatore e l’user agent possono essere registrati o meno secondo la tua policy.

Il plugin offre anche un’opzione Anonimizza PII nei log che maschera email e numeri di telefono nei log tecnici (WooCommerce logger).

11. Compatibilità HPOS e blocchi checkout

Il plugin dichiara ufficialmente compatibilità con:

• HPOS (High-Performance Order Storage) — Tutte le query sugli ordini passano per i CRUD ufficiali di WooCommerce (wc_get_order, wc_get_orders), quindi funzionano sia sulle tabelle legacy che HPOS
• Blocchi Gutenberg cart e checkout — Nessuna interferenza con i nuovi blocchi di pagamento
• WordPress Multisite — Attivazione di rete supportata, opzioni scoped per sito

12. Hook e filtri per sviluppatori

Il plugin espone diversi hook per personalizzare il comportamento senza modificare il codice sorgente.

Filtri disponibili

// Modifica il system prompt prima dell'invio al modello
apply_filters('dfaics_system_prompt', $prompt, $context);

// Aggiungi o rimuovi strumenti dinamicamente
apply_filters('dfaics_tools_available', $tools, $conversation);

// Modifica soglia max messaggi prima di escalation forzata
apply_filters('dfaics_max_messages', 25, $conversation);

// Personalizza il corpo dell'email di escalation
apply_filters('dfaics_escalation_email_body', $html, $conversation);

// Arricchisci i metadati Slack
apply_filters('dfaics_slack_metadata', $metadata, $conversation);

Azioni disponibili

// Dopo la creazione di una conversazione
do_action('dfaics_conversation_created', $conversation_id, $session);

// Dopo l'invio di un messaggio dall'agente
do_action('dfaics_message_sent', $message_id, $conversation_id);

// Dopo un'escalation
do_action('dfaics_escalated', $conversation_id, $reason, $channel);

// Dopo pulizia cron delle conversazioni scadute
do_action('dfaics_cleanup_done', $deleted_count);

Aggiungere uno strumento personalizzato

Crea una classe che estende ToolBase e registrala tramite il filtro dfaics_tools_available. Il namespace è DataFirefly/AiCustomerService/Agent/Tools (qui con slash per leggibilità; nel tuo codice usa il separatore backslash standard di PHP). Ogni strumento dichiara il suo schema JSON, la descrizione, e implementa un metodo execute() che restituisce un array associativo serializzabile.

13. Risoluzione problemi

Il widget non appare

• Verifica che il widget sia attivato in Impostazioni → Widget → Attiva widget
• Verifica la regola di visualizzazione condizionale (pagine autorizzate)
• Apri la console del browser (F12) e cerca errori JS
• Svuota la cache se usi un plugin di cache (WP Rocket, W3 Total Cache…)

L’agente non risponde

• Verifica che la chiave API sia valida tramite il pulsante Testa chiave
• Verifica il tuo credito / quota sull’account Anthropic o OpenAI
• Consulta i log WooCommerce in WooCommerce → Stato → Log, fonte df-ai-customer-service

L’escalation Slack non arriva

• Verifica il webhook tramite il pulsante Testa webhook
• Rigenera il webhook lato Slack se necessario
• Verifica che il canale target esista e che il bot abbia accesso

Ripristinare completamente il plugin

In Impostazioni → Privacy, spunta Elimina tutti i dati alla disinstallazione. Poi disattiva e disinstalla il plugin: le 5 tabelle e le opzioni vengono rimosse.

14. FAQ tecnica

Posso cambiare provider IA senza perdere le conversazioni?

Sì, il passaggio Claude ↔ OpenAI è immediato e non influisce sulla cronologia. Le nuove conversazioni useranno il nuovo provider.

Il plugin funziona in modalità headless?

L’API REST del plugin (/wp-json/dfaics/v1/) è utilizzabile da qualsiasi frontend (Next.js, Vue, mobile). Il widget nativo è in vanilla JS e può essere sostituito dalla tua implementazione che chiami la stessa API.

Si può collegare il plugin a Zendesk o Freshdesk?

Non nativamente in 1.0.0: l’escalation è limitata a Slack ed email. Puoi però usare l’hook dfaics_escalated per attivare la tua integrazione.

L’agente impara dalle mie conversazioni?

No. Nessun fine-tuning viene effettuato. L’agente usa solo il system prompt + gli strumenti + il contesto della conversazione in corso. I tuoi dati non sono usati per migliorare i modelli Anthropic o OpenAI (entrambi i provider offrono un’opzione di opt-out attiva di default sulle loro API professionali).

15. Supporto

Per qualsiasi domanda o segnalazione di bug, scrivi a support chiocciola datafirefly.com indicando il tuo numero di licenza. Rispondiamo entro 48 ore lavorative.