Come incorporare un chatbot in qualsiasi sito web

Hai un chatbot addestrato. Ora devi metterlo sul tuo sito web. Agentkit supporta quattro metodi di embed, e quello giusto dipende dalla tua piattaforma, dalla tua configurazione tecnica e da quanto controllo ti serve. Questa guida copre tutte e quattro le opzioni con esempi di codice, dettagli di configurazione e istruzioni specifiche per piattaforma.

Metodi di embed a colpo d'occhio

La maggior parte degli utenti dovrebbe iniziare con il widget JS. Funziona su qualsiasi piattaforma, si carica in modo asincrono e richiede meno di cinque minuti per essere configurato.

Prima di iniziare

Ogni metodo di embed richiede un chatbot addestrato. Se non ne hai ancora uno:

1. Registrati su Agentkit (gratis).
2. Crea un chatbot e addestralo sui tuoi contenuti usando URL del sito web, documenti, coppie di domande e risposte o testo.
3. Testalo nel Playground finché le risposte non sono accurate.
4. Ottieni il tuo codice di incorporamento da Impostazioni poi Pubblica nella dashboard.

Per indicazioni sull'addestramento, vedi Come addestrare un chatbot sui contenuti del tuo sito web.

Metodo 1: widget JavaScript

Il widget JS è il metodo di embed universale. Un tag script, inserito prima del tag di chiusura </body>, carica una bolla della chat sul tuo sito. Funziona su qualsiasi piattaforma che consente JavaScript personalizzato: siti HTML statici, piattaforme CMS, builder di landing page e applicazioni web.

Installazione di base

Copia questo tag script e inseriscilo prima del tag di chiusura </body> della tua pagina:

<script
  src="https://cdn.agentkit.ai/widget.js"
  data-chatbot="your-chatbot-id"
  async>
</script>

Sostituisci your-chatbot-id con l'ID reale dalla tua dashboard di Agentkit. L'attributo async assicura che lo script si carichi senza bloccare la tua pagina.

Questo è tutto ciò che serve per un chatbot funzionante. Il widget appare come una bolla della chat nell'angolo in basso a destra. I visitatori la cliccano per aprire una conversazione.

Configurazione tramite attributi dati

Puoi personalizzare il comportamento del widget aggiungendo attributi dati al tag script:

<script
  src="https://cdn.agentkit.ai/widget.js"
  data-chatbot="your-chatbot-id"
  data-position="bottom-right"
  data-theme="light"
  async>
</script>

Attributi dati disponibili

La maggior parte della personalizzazione visiva (colori, messaggio di benvenuto, branding) è controllata dalla dashboard di Agentkit invece che dagli attributi dati. Questo mantiene semplice il tuo codice di incorporamento e ti permette di aggiornare le impostazioni senza modificare il codice sul tuo sito.

Come si carica il widget

Lo script del widget è leggero e si carica in modo asincrono. Ecco cosa succede:

1. La tua pagina si carica normalmente. L'attributo async fa sì che lo script non blocchi il rendering.
2. Lo script viene scaricato dal nostro CDN e si inizializza.
3. Una bolla della chat appare sulla pagina.
4. Quando un visitatore clicca sulla bolla, si carica l'interfaccia di chat completa.
5. I messaggi vengono inviati all'API di Agentkit e trasmessi in streaming in tempo reale.

Lo script iniziale è piccolo. L'interfaccia di chat completa si carica solo quando il visitatore interagisce con la bolla, quindi l'impatto sulla velocità della tua pagina è minimo.

Installazione del widget specifica per piattaforma

Il widget JS funziona su tutte le piattaforme, ma i passaggi per aggiungere lo script variano da piattaforma a piattaforma. Ecco link rapidi alle guide specifiche per piattaforma:

Metodo 2: componente React

Se stai sviluppando con React, Next.js, Remix o Gatsby, il componente React ti dà un'integrazione più stretta rispetto al semplice tag script. Ottieni configurazione basata su props, tipi TypeScript e la possibilità di agganciarti agli eventi del chatbot.

Installazione

Installa il pacchetto React di Agentkit:

npm install @agentkit/react

Uso di base

import { AgentitkChat } from '@agentkit/react';

function App() {
  return (
    <AgentitkChat chatbotId="your-chatbot-id" />
  );
}

Questo renderizza la stessa bolla della chat del widget JS, ma come componente React all'interno dell'albero dei componenti della tua app.

Props

Integrazione con Next.js

In un progetto Next.js con App Router, aggiungi il chatbot al tuo root layout così appare su tutte le pagine:

// app/layout.tsx
import { AgentitkChat } from '@agentkit/react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <AgentitkChat chatbotId="your-chatbot-id" />
      </body>
    </html>
  );
}

Per il Pages Router, aggiungi il componente a _app.tsx invece.

Quando usare il componente React rispetto al widget JS

Se usi React, usa il componente React. Per tutto il resto, usa il widget JS.

Metodo 3: iframe

Il metodo iframe incorpora il chatbot come pagina autonoma all'interno di un frame sul tuo sito. È utile in ambienti dove l'iniezione di JavaScript è limitata o dove vuoi mostrare il chatbot come elemento in linea invece che come bolla fluttuante.

Embed iframe di base

<iframe
  src="https://cdn.agentkit.ai/embed/your-chatbot-id"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write">
</iframe>

Questo mostra l'interfaccia di chat completa in linea sulla tua pagina, non come bolla fluttuante.

Quando usare l'iframe

Configurazione dell'iframe

Personalizza l'iframe tramite parametri URL:

<iframe
  src="https://cdn.agentkit.ai/embed/your-chatbot-id?theme=dark"
  style="width: 400px; height: 600px; border: none; border-radius: 12px;"
  allow="clipboard-write">
</iframe>

Dimensionare l'iframe

L'iframe non si ridimensiona automaticamente. Controlli le sue dimensioni tramite CSS:

• Chat incorporata a piena larghezza: width: 100%; height: 600px;
• Chat in barra laterale: width: 400px; height: 100vh; posizionata in un layout a barra laterale.
• Widget compatto: width: 350px; height: 500px; per un'area in linea più piccola.

Limiti dell'embed con iframe

Per la maggior parte dei siti web, il widget JS è la scelta migliore. Usa l'iframe solo quando il widget JS non è un'opzione oppure quando vuoi specificamente un'esperienza di chat in linea.

Metodo 4: plugin WordPress

I siti WordPress possono usare il widget JS tramite uno qualsiasi dei metodi descritti sopra, ma esiste anche un approccio dedicato che usa plugin per snippet di codice e semplifica il processo per gli utenti non tecnici.

Configurazione rapida con WPCode

1. Installa il plugin WPCode (gratuito, oltre 2 milioni di installazioni) da Plugin poi Aggiungi nuovo.
2. Vai su Code Snippets poi Header & Footer.
3. Incolla il tag script di Agentkit nella sezione Footer.
4. Salva.

Il chatbot ora appare su ogni pagina. WPCode supporta anche la logica condizionale così puoi mostrare il chatbot solo su pagine specifiche.

Altri metodi per WordPress

Per la guida completa per WordPress con la risoluzione dei problemi, vedi Come aggiungere un chatbot a WordPress.

Opzioni di personalizzazione

Indipendentemente dal metodo di embed che usi, la maggior parte della personalizzazione avviene dalla dashboard di Agentkit. Questo significa che puoi cambiare le impostazioni senza toccare il tuo codice di incorporamento.

Personalizzazione visiva

Personalizzazione comportamentale

Considerazioni di sicurezza

Quando incorpori un chatbot sul tuo sito, tieni a mente queste impostazioni di sicurezza.

Restrizione di dominio

Imposta sempre la restrizione di dominio nelle impostazioni del tuo chatbot. Questo assicura che il tuo chatbot si carichi solo sui domini autorizzati. Senza questa impostazione, chiunque trovi il tuo ID chatbot potrebbe incorporare il tuo chatbot sul proprio sito e usare la tua quota di messaggi.

Vai su Impostazioni nella dashboard di Agentkit e aggiungi ogni dominio dove il chatbot dovrebbe funzionare:

• Il tuo dominio principale (ad es., yourbusiness.com)
• Eventuali sottodomini (ad es., support.yourbusiness.com)
• Domini di sviluppo o staging se ti serve fare test

Limite di frequenza

Il limite di frequenza fissa un tetto al numero di messaggi che un singolo visitatore può inviare per sessione. Questo previene abusi e aiuta a gestire la tua quota di messaggi. Un limite di 15-25 messaggi per sessione è ragionevole per la maggior parte dei siti.

Content Security Policy

Se il tuo sito usa header Content Security Policy, devi mettere in whitelist i domini di Agentkit. Aggiungi quanto segue alla tua CSP:

• script-src: cdn.agentkit.ai
• frame-src: cdn.agentkit.ai (se usi il metodo iframe)
• connect-src: *.agentkit.com (per le chiamate API)

Risoluzione dei problemi comuni con l'embed

Il chatbot non appare

Il chatbot appare ma non risponde

• Controlla i dati di addestramento. Un chatbot non addestrato non ha nulla su cui lavorare.
• Verifica l'ID chatbot. Un ID errato significa che il widget si carica ma non trova il chatbot.
• Controlla la restrizione di dominio. Se il tuo dominio non è nell'elenco consentito, il chatbot non risponderà.
• Controlla la quota del tuo piano. Se hai esaurito i messaggi mensili, il chatbot smetterà di rispondere fino al prossimo ciclo di fatturazione.

Il chatbot va in conflitto con altri widget

Se un altro widget di chat (Intercom, Crisp, Drift) si sovrappone al tuo, puoi rimuovere l'altro widget, cambiare la posizione di Agentkit su bottom-left, oppure usare il metodo iframe per posizionare il chatbot in linea invece che come bolla fluttuante.

Scegliere il piano giusto per il tuo embed

La fatturazione annuale fa risparmiare circa il 20% su tutti i piani a pagamento. Inizia con il piano Free per testare l'embed, poi fai l'upgrade quando il tuo traffico richiede più messaggi.

Prossimi passi

Una volta incorporato il tuo chatbot, il lavoro passa dall'installazione all'ottimizzazione:

1. Monitora le conversazioni nella dashboard di Agentkit per la prima settimana. Individua le domande su cui il chatbot fatica.
2. Aggiungi dati di addestramento per i punti deboli. Le coppie di domande e risposte sono il modo più rapido per correggere risposte specifiche.
3. Attiva la raccolta lead per raccogliere le email dei visitatori durante le conversazioni. Vedi la guida alla lead generation.
4. Collega i tuoi strumenti tramite Zapier, webhook o API REST. Vedi la guida all'integrazione.
5. Configura la restrizione di dominio e il limite di frequenza per la sicurezza e la gestione della quota.

Per le guide specifiche per piattaforma, vedi le guide dettagliate:

• WordPress
• Shopify
• Squarespace
• Wix
• Webflow

Crea il tuo chatbot gratis →

Nessuna carta di credito richiesta.