Chatbot in React: aggiungi un chatbot IA alla tua app React (Vite, CRA, SPA)

Prima di toccare il codice ti servono due cose:

• Un account Nexoply e la chiave del tuo chatbot. Registrati gratis (il piano Gratuito include 50 conversazioni al mese, senza carta di credito), poi apri Chatbot nella dashboard. Il codice di installazione che trovi lì contiene già la tua chiave. La chiave è pubblica: non è un segreto e non dà accesso all’account, quindi può stare tranquillamente nel codice lato client.
• Le informazioni sull’attività da cui l’assistente attinge le risposte: servizi e prezzi, FAQ, politiche, orari di apertura e zone servite. Il modo più rapido è inserire l’indirizzo del sito e lasciare che Nexoply importi le pagine pubbliche, comprese quelle costruite con JavaScript, quindi funziona anche con un sito React. Non viene aggiunto nulla finché non lo approvi.

Crea src/components/Chatbot.tsx. Il componente non renderizza nulla di suo: aggiunge una sola volta lo script di Nexoply alla pagina, e il widget disegna il pulsante e la finestra della chat.

// src/components/Chatbot.tsx
import { useEffect } from "react";

type ChatbotProps = { chatbotKey: string };

export function Chatbot({ chatbotKey }: ChatbotProps) {
  useEffect(() => {
    // Nessuna chiave, o lo script è già nella pagina: non c’è niente da fare.
    if (!chatbotKey || document.querySelector("script[data-chatbot]")) return;
    const s = document.createElement("script");
    s.src = "https://nexoply.com/widget.js";
    s.async = true;
    s.dataset.chatbot = chatbotKey;
    document.body.appendChild(s);
  }, [chatbotKey]);

  return null;
}

Renderizzalo una sola volta, nel componente che resta montato per tutta la visita (di solito App). Con Vite, inserisci VITE_NEXOPLY_KEY=YOUR-KEY in un file .env:

// src/App.tsx
import { Chatbot } from "./components/Chatbot";

export default function App() {
  return (
    <>
      {/* il tuo layout e le tue route */}
      <Chatbot chatbotKey={import.meta.env.VITE_NEXOPLY_KEY} />
    </>
  );
}

Il componente funziona così com’è in un progetto TypeScript con Vite o Create React App. In JavaScript semplice, chiama il file Chatbot.jsx e togli il tipo ChatbotProps. Create React App non ha import.meta.env: passa invece process.env.REACT_APP_NEXOPLY_KEY. Essendo un normale componente, puoi anche renderizzarlo in modo condizionale, per esempio {hasConsent && <Chatbot chatbotKey={key} />}, per caricare la chat solo dopo che il visitatore ha accettato il banner dei cookie.

• Perché non c’è una funzione di cleanup. Il widget non ha un’API per rimuoverlo una volta caricato e vive fuori dall’albero React, quindi quando il componente viene smontato non c’è nulla da annullare.
• Perché StrictMode non è un problema. In sviluppo, React StrictMode esegue gli effect due volte. Il controllo con querySelector salta la seconda esecuzione, e anche se lo script venisse aggiunto due volte, il widget si monta una sola volta per chiave del chatbot. Per lo stesso motivo l’hot reload è sicuro.
• Mantieni l’attributo. Il widget legge le impostazioni dal proprio tag script, quindi il tag deve mantenere l’attributo data-chatbot e un src che contenga widget.js. Impostare s.dataset.chatbot crea proprio quell’attributo.

Se non ti serve controllare il caricamento dal codice, salta il componente. Ogni SPA React ha una pagina HTML di base: con Vite è index.html nella radice del progetto; con Create React App è public/index.html. Incolla il codice subito prima del tag di chiusura </body>:

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>

  <!-- Chatbot IA di Nexoply -->
  <script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>
</body>

Sostituisci YOUR-KEY con la chiave della pagina Chatbot. Lo script si carica in modo asincrono, quindi non blocca mai il rendering della tua app. Aggiungi data-open="true" al tag se vuoi che la finestra della chat si apra al caricamento. L’installazione è tutta qui: ricompila, pubblica, e il pulsante compare su tutte le route.

Cercando un chatbot per React si trovano due tipi di strumenti, che risolvono problemi diversi:

• Una libreria di UI per chatbot ti fornisce i componenti React della chat: elenco dei messaggi, campo di testo, fumetti, a volte passaggi di conversazione predefiniti. Tutto ciò che sta dietro l’interfaccia lo costruisci tu: script fissi, oppure un backend che chiama un modello IA con la tua chiave API, più i contenuti da cui risponde, l’archiviazione delle conversazioni e la protezione dagli abusi. È adatta quando la chat fa parte del tuo prodotto, per esempio un assistente che lavora con i dati dei tuoi utenti.
• Un chatbot IA in hosting come Nexoply include insieme interfaccia, IA e backend. Risponde alle domande dei visitatori solo in base alle informazioni sull’attività che aggiungi o importi (servizi e prezzi, FAQ, politiche, orari di apertura) e lo dice quando non conosce la risposta. Non servono chiavi IA né codice lato server; conversazioni, domande senza risposta e protezione antispam si gestiscono nella dashboard. È adatto a un sito rivolto ai clienti che deve rispondere a domande sull’attività.

Se vuoi il pieno controllo su interfaccia e modello, parti da una libreria. Se l’obiettivo è rispondere alle domande dei visitatori senza costruire né gestire un backend, il widget in hosting richiede meno lavoro. Scopri come Nexoply risponde in base alle informazioni sulla tua attività.

• Resta fuori dall’albero React. Il widget si monta su document.body, fuori dall’elemento #root, quindi re-render e cambi di route non lo rimuovono né ne cambiano lo stile.
• Shadow DOM in entrambe le direzioni. Il tuo CSS (Tailwind, CSS modules, reset globali) non entra nella chat, e il CSS della chat non entra nella tua app.
• I cambi di route funzionano e basta. Con React Router o qualsiasi router basato sulla history, i visitatori mantengono la conversazione mentre navigano, e le regole per pagina (per esempio una linguetta laterale solo su /pricing) vengono ricontrollate quando cambia l’URL. Nessun codice in più.
• Nessun cookie. Salva un identificativo anonimo del visitatore in localStorage e la conversazione in corso in sessionStorage.

Vuoi un pulsante "Scrivici in chat" nella sezione hero o nella pagina dei prezzi? Invia l’evento nexoply:open-chat su window:

export function ChatButton() {
  return (
    <button onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}>
      Scrivici in chat
    </button>
  );
}

Non serve alcun import: il widget ascolta questo evento su window. Se preferisci mostrare solo il tuo pulsante, imposta il pulsante dei messaggi su "Nessun pulsante" con una regola per pagina nella dashboard.

Prima di pubblicare, controlla queste tre impostazioni:

• Siti web consentiti. Se hai compilato Consenti solo su questi siti web (dashboard → Chatbot), aggiungi l’host di sviluppo con la porta, per esempio localhost:5173 per Vite o localhost:3000 per Create React App, oppure lascia l’elenco vuoto durante i test.
• Content-Security-Policy. Se la tua app invia un header o un meta tag CSP, consenti https://nexoply.com in script-src, connect-src e img-src.
• Verifica tutto il percorso. Avvia l’app, fai clic sul pulsante della chat, fai una domanda vera e cercala in Conversazioni nella dashboard.

Se il pulsante continua a non comparire:

• Chiave vuota. Senza chiave il componente non carica nulla. Stampa nella console import.meta.env.VITE_NEXOPLY_KEY: Vite espone solo le variabili che iniziano con VITE_, e dopo aver modificato .env devi riavviare il server di sviluppo.
• Richiesta bloccata. Controlla la console del browser e la scheda Network per errori CSP o un widget.js bloccato.
• Chatbot disattivato. Verifica che l’interruttore Chatbot attivo sia acceso.
• Ad blocker. Raramente un’estensione del browser blocca i widget di chat. Prova in una finestra privata senza estensioni.

Una volta inserito lo script, non dovrai più toccare il codice: le modifiche fatte nella dashboard arrivano sul sito in circa un minuto. In Chatbot → Personalizza puoi definire lo stile del pulsante dei messaggi (icona o immagine o SVG personalizzati, testo, forma, dimensione, colori, posizione) oppure usare al suo posto una linguetta laterale sul bordo dello schermo. Imposta un aspetto diverso sugli smartphone e usa le regole per pagina per cambiarlo su route specifiche (per esempio /pricing o /services/*). La finestra della chat adotta i tuoi caratteri, colori e logo, e la schermata iniziale può offrire pulsanti come Prenota, Chiama o WhatsApp.

Usi un altro framework? Leggi come aggiungere un chatbot a Next.js con next/script o la guida al chatbot per Vue e Nuxt; per un sito vetrina su WordPress, consulta la guida WordPress. Per il quadro completo, leggi come l’assistente impara a conoscere la tua attività o confronta piani e limiti di conversazioni.