HomeDocumentazione

Widget Embedding

Aggiungi il tuo chatbot AI a qualsiasi sito web in pochi secondi con il nostro semplice codice di embed.

Avvio Rapido

Aggiungi questo codice prima del tag di chiusura </body>:

<script 
  src="https://www.chatreact.ai/embed/widget.js" 
  data-chatbot-id="YOUR_CHATBOT_ID" 
  async
></script>

È tutto! Il tuo chatbot è ora live sul tuo sito.

Trovare l'ID del Chatbot

  1. Vai alle impostazioni del tuo chatbot
  2. Naviga nella scheda Incorpora
  3. Copia il codice di embed (include il tuo ID)

L'ID del chatbot nel codice di embed non è lo stesso del nome nell'URL della dashboard. Copia sempre l'ID dalla scheda Incorpora.

Personalizzare il Widget

L'aspetto e il comportamento del widget si configurano nella tua dashboard — non nel codice di embed. Vai su Dashboard → Chatbots → [your chatbot] → Widget per regolare:

  • Position — bottom-right, bottom-left, or inline
  • Colors — primary, background and text colors, plus border radius
  • Dimensioni — larghezza e altezza del widget

Per aprire la chat automaticamente dopo un ritardo configurabile, abilita Apertura automatica nella scheda Comportamento della stessa pagina di impostazioni. Nei piani white-label, il branding di ChatReact è nascosto per impostazione predefinita — la stessa scheda Comportamento contiene un interruttore Show "Powered by ChatReact" se desideri mostrarlo comunque nel footer del widget.

Le modifiche si applicano automaticamente al tuo sito — non è necessario aggiornare il codice di embed. Consulta la guida Widget Customization per tutte le opzioni disponibili.

La lingua del widget viene rilevata automaticamente dal browser di ciascun visitatore, in base alle lingue che abiliti nella scheda Lingue del tuo chatbot.

Scegli la posizione Inline per incorporare la chat direttamente nella pagina nel punto in cui è posizionato il tag script. Il widget rimane sempre aperto, senza bubble o pulsante di chiusura — ideale per pagine dedicate alla chat o sezioni di supporto.

Widget FAQ

Mostra le FAQ come un accordion in qualsiasi pagina:

<div id="chatreact-faq"></div>
<script 
  src="https://www.chatreact.ai/embed/faq-widget.js" 
  data-chatbot-id="YOUR_CHATBOT_ID"
  async
></script>

Il widget FAQ mostra le FAQ pubblicate dal tuo chatbot. Colori e stile (primary, background and text colors, border radius) si configurano in Dashboard → FAQ → Impostazioni.

Opzioni del Widget FAQ

SettingDescriptionWhere to Configure
Colors & StylingPrimary, background and text colors, border radiusDashboard → FAQs → Settings
LarghezzaScegli tra 100% (larghezza completa) o una larghezza personalizzata in pixel (400–1200px)Dashboard → FAQs → Settings
FAQ Sort OrderOrdine di visualizzazione: Date (più recenti prima), Name (alfabetico), o Custom (manuale drag & drop)Dashboard → FAQs → Settings → Behavior
Filtro per categoriaMostra solo specifiche categorie nel widgetEmbed code data-categories attribute
Custom ContainerRenderizza il widget all'interno del tuo elemento invece del div predefinito chatreact-faqEmbed code data-container attribute
LinguaSovrascrivi la lingua del widget (di default usa l'attributo <html lang> della pagina, poi la lingua del browser del visitatore)Embed code data-lang attribute
Accordion BehaviorPermetti più FAQ aperte contemporaneamente, o espandi automaticamente la prima FAQDashboard → FAQs → Settings → Behavior

Esempio Filtro Categoria

<script
  src="https://www.chatreact.ai/embed/faq-widget.js"
  data-chatbot-id="YOUR_CHATBOT_ID"
  data-categories="shipping,returns"
  async
></script>

Quando il widget è filtrato su una singola categoria, l'ordine di quella categoria (impostato in Dashboard → FAQs → Categories) sovrascrive l'impostazione globale di ordinamento.

Ottimizzazione Mobile

Il widget di chat è completamente ottimizzato per dispositivi mobili:

  • Layout a larghezza completa su schermi piccoli
  • Animazione slide-up all'apertura
  • Gestione della tastiera su iOS (il widget si adatta alla tastiera a schermo)
  • Supporto safe-area per il notch e l'indicatore Home degli iPhone
  • Target touch più grandi per una migliore usabilità
  • Dimensione del font dell'input che previene l'auto-zoom su iOS

Guide Specifiche per Piattaforma

WordPress

Consigliato: usa il plugin ufficiale ChatReact WordPress Plugin per l'integrazione più semplice con blocchi Gutenberg, widget Elementor e shortcode.

Alternativa: embed manuale tramite un plugin "Header/Footer Scripts":

  1. Installa un plugin "Header/Footer Scripts"
  2. Aggiungi il codice di embed nella sezione footer
  3. Salva e pubblica

Shopify

Consigliato: ChatReact Shopify App

Installa l'app ChatReact dallo Shopify App Store per l'integrazione più semplice:

  1. Installa l'app ChatReact nell'admin di Shopify
  2. Inserisci il tuo Chatbot ID nelle impostazioni dell'app
  3. Il widget di chat appare automaticamente sul tuo storefront
  4. Gestisci le assegnazioni del widget per pagina, o abilitalo ovunque

L'app supporta anche i widget Form e FAQ come App Blocks nell'Editor del Tema.

Alternativa: Embed Manuale

  1. Vai a Online Store → Themes → Edit Code
  2. Apri theme.liquid
  3. Aggiungi il codice prima di </body>
  4. Salva

Webflow

  1. Vai a Project Settings → Custom Code
  2. Aggiungi nel Footer Code
  3. Pubblica il sito

Next.js / React

Usa il componente Script:

import Script from 'next/script';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <Script 
        src="https://www.chatreact.ai/embed/widget.js"
        data-chatbot-id="YOUR_CHATBOT_ID"
        strategy="lazyOnload"
      />
    </>
  );
}

Vue.js

Aggiungi nel tuo main App.vue o nel layout:

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://www.chatreact.ai/embed/widget.js';
  script.dataset.chatbotId = 'YOUR_CHATBOT_ID';
  script.async = true;
  document.body.appendChild(script);
});
</script>

API JavaScript

Interagisci con il widget programmaticamente:

// Open the chat
ChatReact.open();

// Close the chat
ChatReact.close();

// Toggle open/closed
ChatReact.toggle();

// Start a fresh conversation
ChatReact.newChat();

// Remove the widget from the page entirely
// (useful in single-page apps, e.g. on route changes)
ChatReact.destroy();

Test

Modalità Anteprima

Prima di incorporare in produzione:

  1. Usa la funzionalità Anteprima nella tua dashboard
  2. Testa scenari differenti
  3. Verifica che le risposte siano accurate

Testare su un sito in sviluppo locale? Usa il codice di embed standard senza modifiche — funziona anche su pagine localhost.

Risoluzione dei Problemi

Il Widget Non Appare

  1. Controlla la console del browser per errori
  2. Verifica che l'ID del chatbot sia corretto
  3. Assicurati che il chatbot sia attivo (non disabilitato)
  4. Verifica se gli ad blocker stanno interferendo
  5. Controlla l'utilizzo del tuo piano — il widget si sospende quando viene raggiunto il limite mensile del piano

Plugin di Caching & Ottimizzazione

Alcuni plugin di caching o ottimizzazione degli script riscrivono gli URL degli script, il che può impedire il caricamento del widget. In tal caso, aggiungi un URL API esplicito al tag script:

<script 
  src="https://www.chatreact.ai/embed/widget.js" 
  data-chatbot-id="YOUR_CHATBOT_ID"
  data-api-url="https://www.chatreact.ai"
  async
></script>

Lo stesso attributo funziona anche sugli script dei widget FAQ e form.

Conflitti di Stile

Se il CSS del tuo sito entra in conflitto:

  • Il widget scope le sue regole di stile nel proprio container e utilizza regole ad alta priorità per resistere ai conflitti
  • Controlla i valori di z-index degli elementi che sovrappongono il widget
  • Evita regole troppo generiche !important nel CSS del tuo sito che prendono di mira elementi generici

Prestazioni

Il widget è progettato per avere un impatto minimo:

  • Si carica in modo asincrono — non blocca mai il rendering della pagina
  • Leggero: circa 30 KB trasferiti compressi

Passi Successivi