Chatbot in Next.js: aggiungi un chatbot IA con next/script (App Router e Pages Router)

• Un account Nexoply. Registrati gratis: il piano Gratuito include 50 conversazioni al mese, senza carta di credito.
• Le informazioni sull’attività in Nexoply: 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 generate con JavaScript); tu controlli i suggerimenti e non viene aggiunto nulla finché non lo approvi.
• La chiave del tuo chatbot. Nella dashboard apri Chatbot (fai clic su Crea chatbot se non l’hai ancora fatto). Il codice di installazione che trovi lì contiene la chiave nell’attributo data-chatbot.

In un sito HTML semplice, basterebbe incollare il codice di installazione prima di </body>:

<script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>

In Next.js non modifichi direttamente l’HTML, quindi aggiungi lo stesso script con il componente integrato next/script. La chiave è pubblica: serve solo a dire al widget a quale attività appartiene.

Il layout principale racchiude ogni pagina, quindi aggiungendo lì lo script la chat compare su tutto il sito. Importa Script da next/script e inseriscilo dentro <body>, dopo {children}:

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Widget di chat Nexoply: si carica nel browser dopo la hydration */}
        <Script
          src="https://nexoply.com/widget.js"
          data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Poi metti la chiave in una variabile d’ambiente. Il prefisso NEXT_PUBLIC_ fa sì che Next.js la includa nel bundle del browser, il che qui va bene perché la chiave non è un segreto:

# .env.local (non viene salvato su git)
NEXT_PUBLIC_NEXOPLY_KEY=YOUR-KEY

Con il Pages Router è pages/_app.tsx a racchiudere ogni pagina, quindi lo stesso <Script> va lì, accanto a <Component {...pageProps} />. Usa la stessa variabile di .env.local:

// pages/_app.tsx
import type { AppProps } from "next/app";
import Script from "next/script";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://nexoply.com/widget.js"
        data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
        strategy="afterInteractive"
      />
    </>
  );
}

Se il tuo progetto usa entrambi i router, aggiungi lo script sia in app/layout.tsx sia in pages/_app.tsx. Caricarlo due volte non crea problemi: il widget si monta una sola volta per chiave del chatbot.

Preferisci un componente <Chatbot />, come nella guida al componente chatbot per React? Sposta lo Script in un file a parte. next/script funziona nei Server Components purché tu non passi gestori di eventi come onLoad, quindi questo file non ha bisogno di "use client":

// components/Chatbot.tsx
import Script from "next/script";

export function Chatbot() {
  return (
    <Script
      src="https://nexoply.com/widget.js"
      data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
      strategy="afterInteractive"
    />
  );
}

Poi renderizza <Chatbot /> dentro <body> in app/layout.tsx, dopo {children}, oppure accanto a <Component {...pageProps} /> in pages/_app.tsx. Renderizzalo nel layout, non in una singola pagina, così si carica su ogni route.

strategy="afterInteractive" carica il widget subito dopo che la pagina diventa interattiva, quindi il pulsante della chat compare presto. strategy="lazyOnload" aspetta che il browser sia inattivo e che tutto il resto sia caricato; sceglila se vuoi mantenere il primo caricamento il più leggero possibile e non ti dispiace che il pulsante compaia un attimo dopo. Entrambe tengono lo script fuori dal percorso critico di rendering. Per i dettagli consulta la documentazione di next/script.

• Navigazione lato client. Il widget mantiene aperta la conversazione mentre i visitatori passano da una pagina all’altra con <Link> o con il router, e ricontrolla le regole per pagina quando cambia l’URL, senza codice in più.
• Sicuro con SSR e hydration. Funziona solo nel browser e si monta su document.body, fuori dal markup che React idrata, quindi non causa mai errori di hydration mismatch.
• Shadow DOM. Tailwind o il tuo CSS globale non entrano nella chat, e gli stili della chat non entrano nella tua app. I re-render non lo rimuovono mai.
• StrictMode e Fast Refresh. Gli effect eseguiti due volte in sviluppo o gli hot reload non possono creare una seconda chat: si monta una volta per chiave.
• Archiviazione. Non imposta cookie; usa localStorage per un identificativo anonimo del visitatore e sessionStorage per la conversazione in corso.

Next.js rende semplice costruire un chatbot tutto tuo, e a volte è la scelta giusta. I due approcci servono a scopi diversi:

• Costruirlo da te con una libreria di UI per chat o con componenti tuoi, più un route handler o una API route che chiama un modello IA con la tua chiave API. Sono a tuo carico anche i contenuti da cui risponde, l’archiviazione delle conversazioni e la protezione dagli abusi. È la strada giusta 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 e nulla gira sul tuo 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, costruiscilo. Se l’obiettivo è rispondere alle domande dei visitatori senza gestire un backend, il widget in hosting richiede meno lavoro. Scopri come Nexoply risponde in base alle informazioni sulla tua attività.

Vuoi un pulsante "Scrivici in chat" nella sezione hero o in quella dei prezzi? Invia l’evento nexoply:open-chat su window. Poiché usa onClick, deve essere un client component:

"use client";
// components/ChatButton.tsx

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

Usa <ChatButton /> in qualsiasi pagina o server component. Non esiste un’API per rimuovere il widget una volta caricato: per nascondere il pulsante dei messaggi su alcune pagine (per esempio /checkout), aggiungi una regola per pagina con "Nessun pulsante" in Chatbot → Personalizza → Pulsante dei messaggi → Diverso su alcune pagine.

Avvia next dev, apri http://localhost:3000 e nell’angolo compare un pulsante della chat. Fai una domanda vera, per esempio "Lavorate anche nel fine settimana?"; nel giro di pochi secondi la conversazione compare in Conversazioni nella dashboard. Le modifiche che fai nella dashboard arrivano sul sito in circa un minuto, senza ripubblicare.

Se la tua app invia un header Content-Security-Policy (per esempio dal middleware o da next.config), consenti Nexoply in:

• script-src https://nexoply.com: per caricare widget.js.
• connect-src https://nexoply.com: per le richieste della chat.
• img-src https://nexoply.com: per immagini come il logo e l’icona del pulsante.

• Nessun pulsante, e data-chatbot è vuoto nel sorgente della pagina. La variabile d’ambiente non è stata letta: controlla il prefisso NEXT_PUBLIC_, riavvia next dev e, sul tuo hosting, aggiungi la variabile e ripubblica.
• Lo script è in una singola pagina invece che nel layout. Spostalo in app/layout.tsx o pages/_app.tsx, così si carica su ogni route.
• Il tag è stato modificato. Deve mantenere l’attributo data-chatbot e un src che contenga widget.js.
• Bloccato dalla CSP o dai siti web consentiti. Cerca errori nella console del browser e controlla le due sezioni qui sopra.
• Chatbot disattivato. Verifica che l’interruttore Chatbot attivo sia acceso.
• Ad blocker. Raramente un’estensione blocca i widget di chat. Prova in una finestra privata senza estensioni.

Quando funziona, adattalo al sito in Chatbot → Personalizza: icona, testo, colori e posizione del pulsante, oppure una linguetta laterale sul bordo dello schermo (come "Aiuto"); un aspetto diverso sugli smartphone; e regole per pagine specifiche (per esempio una linguetta laterale solo su /pricing). Scopri tutte le opzioni di personalizzazione e come l’assistente impara a conoscere la tua attività, confronta piani e limiti di conversazioni, oppure leggi la guida al componente chatbot per React e la guida al chatbot per Vue e Nuxt.