Integrazione nel sito

Una volta creato, addestrato e personalizzato, l'Agent AI deve essere reso accessibile ai tuoi visitatori. Hotely offre diverse modalità di integrazione, dalla più semplice (copia-incolla di un codice) alla più avanzata (iframe a pagina piena), ciascuna adatta a esigenze specifiche. Nessuna richiede competenze di programmazione avanzate.

A differenza di molti sistemi che richiedono plugin specifici per ogni piattaforma (WordPress, Wix, Shopify) o che impongono configurazioni complesse lato server, l'integrazione di Hotely funziona con un singolo snippet di codice universale compatibile con qualsiasi sito web.

Metodi di integrazione

Panoramica

Widget JavaScript

Il widget è il metodo di integrazione più comune. Aggiunge una bolla nell'angolo inferiore destro del tuo sito web. Quando l'utente clicca la bolla, si apre la finestra di chat con l'Agent.

Come ottenere il codice

1. Dalla dashboard dell'Agent, vai alla sezione "Integrazione" o "Installa"
2. Seleziona "Widget"
3. Il sistema mostra il codice snippet pronto per il copia-incolla
4. Clicca "Copia codice"

Formato del codice

Il codice del widget è simile a questo:

<script
  src="https://app.hotely.ai/widget.js"
  data-chatbot-id="IL_TUO_ID_AGENT"
  async
></script>

Si tratta di un singolo tag <script> che carica il widget in modo asincrono (non rallenta il caricamento del sito).

Dove incollare il codice

Il codice va inserito nel codice HTML del tuo sito web, idealmente prima del tag di chiusura </body>. La posizione esatta dipende dalla piattaforma che utilizzi:

Verifica dell'integrazione

Dopo aver inserito il codice:

1. Salva le modifiche al sito
2. Apri il sito in una finestra del browser in modalità incognito
3. Verifica che la bolla appaia nell'angolo inferiore destro
4. Clicca sulla bolla e verifica che la finestra di chat si apra
5. Scrivi un messaggio di test e verifica che l'Agent risponda
6. Controlla i colori e i testi personalizzati

Posizionamento del widget

Il widget appare di default nell'angolo inferiore destro della pagina. Questa è la posizione standard per le chat web e gli utenti si aspettano di trovarlo lì. Se hai altri elementi in quella posizione (pulsanti di supporto, cookie banner), assicurati che non si sovrappongano.

Iframe

L'integrazione via iframe è ideale quando vuoi dedicare un'intera pagina o una sezione specifica del sito alla chat con l'Agent.

Quando usare l'iframe

• Vuoi creare una pagina "Parla con noi" dedicata
• Vuoi integrare la chat in una sezione specifica di una pagina
• Vuoi mostrare la chat a dimensione piena senza la bolla/finestra popup

Come ottenere il codice iframe

1. Dalla sezione "Integrazione" dell'Agent
2. Seleziona "Iframe"
3. Copia il codice fornito

Formato del codice

<iframe
  src="https://app.hotely.ai/chat/IL_TUO_ID_AGENT"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none; border-radius: 12px;"
></iframe>

Puoi personalizzare le dimensioni modificando gli attributi width e height:

Link diretto

Il link diretto è un URL che apre la chat dell'Agent in una pagina a sè stante, senza integrazione in un sito web. È perfetto per:

• Inserirlo in email e newsletter
• Condividerlo sui social media
• Includerlo nelle risposte automatiche (fuori ufficio, conferme prenotazione)
• Aggiungerlo nella bio di Instagram o nella pagina Facebook

Come ottenere il link

1. Dalla sezione "Integrazione" dell'Agent
2. Seleziona "Link diretto"
3. Copia il link fornito

Il formato del link è:

https://app.hotely.ai/chat/IL_TUO_ID_AGENT

Dove usare il link

QR Code

Il QR code è un codice a barre bidimensionale che, se scansionato con la fotocamera di uno smartphone, apre il link diretto dell'Agent. È lo strumento ideale per collegare il mondo fisico a quello digitale.

Come generare il QR code

1. Dalla sezione "Integrazione" dell'Agent
2. Seleziona "QR Code"
3. Il sistema genera automaticamente un QR code che punta al link diretto dell'Agent
4. Scarica il QR code in formato PNG o SVG

Dove usare il QR code

Vantaggi del QR code

• L'ospite non deve cercare il sito o digitare un URL
• Funziona offline (basta la fotocamera dello smartphone)
• È misurabile: puoi tracciare quanti utenti arrivano tramite il QR code
• Non richiede il download di nessuna app

Personalizzazione via parametri URL

Il link diretto e l'iframe supportano parametri URL per personalizzare il comportamento dell'Agent:

Esempio di URL con parametri:

https://app.hotely.ai/chat/IL_TUO_ID?lang=en&ref=email-newsletter

Questo è utile per personalizzare l'esperienza in base al canale di provenienza o alla lingua del target.

Test dell'integrazione

Prima di rendere l'Agent visibile ai tuoi clienti, esegui un test completo:

Checklist di test

Problemi comuni

La bolla non appare:

• Verifica che il codice snippet sia inserito correttamente
• Controlla la console del browser (F12 > Console) per errori JavaScript
• Assicurati che non ci siano blocchi da parte di ad-blocker o Content Security Policy
• Svuota la cache del browser

La chat si apre ma non risponde:

• Verifica che l'Agent abbia contenuti (crawler o file caricati)
• Controlla che l'ID dell'Agent nel codice sia corretto
• Verifica la connessione internet

Il widget si sovrappone ad altri elementi:

• Controlla il z-index degli elementi del sito
• Verifica che non ci siano altri widget (cookie banner, chat di supporto) nella stessa posizione
• Considera di spostare gli altri elementi

Performance degradata:

• Il widget viene caricato in modo asincrono e non dovrebbe impattare le performance
• Se noti rallentamenti, verifica con gli strumenti sviluppatore del browser che il problema sia effettivamente legato al widget

Integrazione avanzata

Apertura automatica

In alcune situazioni potresti voler aprire la chat automaticamente:

• Dopo che l'utente è rimasto sulla pagina per un certo tempo
• Su pagine specifiche (es. la pagina "Contatti")
• Dopo un'interazione specifica (es. click su un bottone "Hai bisogno di aiuto?")

Queste personalizzazioni possono essere implementate con un minimo di JavaScript. Contatta il supporto per dettagli tecnici.

Pulsanti personalizzati

Invece di usare la bolla predefinita, puoi creare un pulsante personalizzato nel design del tuo sito che apre la chat dell'Agent al click. Questo è utile per integrare la call-to-action nella struttura della pagina (es. un pulsante "Chatta con noi" nel menu di navigazione).

Tracking delle conversioni

Se utilizzi Google Analytics o altri strumenti di tracking, puoi monitorare:

• Quanti utenti aprono la chat
• Quanti utenti inviano almeno un messaggio
• Quanti utenti compilano il form di contatto
• Da quale pagina del sito viene aperta la chat più frequentemente

Per assistenza nell'integrazione dell'Agent, contatta support@hotely.ai.