Widget JavaScript

Il widget JavaScript è il canale di integrazione principale dell'Agent. Si installa una sola volta sul sito web e appare come bolla chat in basso a destra di ogni pagina, disponibile per i visitatori 24 ore su 24.

L'installazione richiede di incollare una riga di codice nel template del sito. Nessuna competenza tecnica avanzata, nessun server da configurare, nessun plugin obbligatorio. Funziona con qualsiasi piattaforma di sito.

Dalla sidebar dell'Agent, vai su Integrazione o Embed. La schermata mostra:

Il codice del widget pronto da copiare
Anteprima visiva di come apparirà
Opzioni di configurazione (posizione, comportamento iniziale)
Istruzioni specifiche per piattaforma

Il codice è del tipo:

<script
  src="https://hotely.ai/embed.js"
  data-chatbot-id="il-tuo-agent-id"
  defer
></script>

Una sola riga, autonoma, senza dipendenze.

Installazione per piattaforma

WordPress

Tre opzioni in base al tuo tema/livello:

Opzione 1 — Plugin "Insert Headers and Footers":

Installa il plugin gratuito "Insert Headers and Footers"
Vai su Impostazioni → Insert Headers and Footers
Incolla il codice nel campo "Scripts in Footer"
Salva

Opzione 2 — Editor del tema:

Aspetto → Editor file del tema
Apri footer.php
Incolla il codice prima del tag </body>
Aggiorna file

Opzione 3 — Tema con campo "Custom Code":

Molti temi premium (Astra, Generatepress, Divi, OceanWP) hanno un campo dedicato per script personalizzati. Cerca "Custom JS" o "Footer Code" nelle opzioni del tema.

Wix

Pannello Editor → menù "Aggiungi" → "Embed Code"
Selezione "Embed HTML"
Incolla il codice
Posiziona l'elemento (può essere ovunque, non è visibile direttamente)
Pubblica

In alternativa, Wix offre nelle Impostazioni → Tracking & Analytics il campo per inserire codice nel header/body — è la posizione preferita.

Squarespace

Impostazioni → Avanzate → Code Injection
Incolla il codice nel campo "Footer"
Salva

Shopify

Negozio online → Temi → "..." sul tema attivo → "Modifica codice"
Apri theme.liquid
Incolla il codice prima del tag </body>
Salva

Webflow

Project Settings → Custom Code
Incolla il codice nel campo "Footer Code"
Salva e ripubblica il sito

Sito custom HTML/JavaScript

Apri il file HTML del sito (es. index.html) e incolla il codice prima del tag </body>. Se il sito ha template, fallo nel template del footer comune.

Website Builder Hotely

Se usi il Website Builder di Hotely per il sito della struttura, l'Agent è integrato automaticamente senza alcun codice. La connessione tra Builder e Agent avviene tramite il workspace condiviso.

Dalle impostazioni del widget puoi configurare:

Posizione sullo schermo

In basso a destra (default più comune) — convenzione classica
In basso a sinistra — utile per siti con elementi importanti a destra
Centrato in basso — per posizionamento bilanciato
Posizione custom — coordinate precise in pixel

Margine dai bordi

Spazio dal bordo dello schermo (in pixel). Utile per evitare sovrapposizioni con altri elementi (es. pulsante "Torna su", chat di altri sistemi che migrerai).

Pagine in cui mostrare/nascondere

Per default il widget appare su tutte le pagine. Puoi:

Includere solo alcune pagine (es. solo /contatti, /prenotazioni)
Escludere alcune pagine (es. checkout, admin)
Mostrare solo a determinate ore (es. solo fuori orario reception)
Mostrare a determinate sorgenti di traffico (es. solo Google Ads)

Apertura automatica

Mai apertura automatica — l'utente apre manualmente
Apertura automatica dopo X secondi — invita a interagire (consigliato 8-15 sec)
Apertura automatica al primo accesso, mai per ritorni — bilanciato
Tooltip iniziale — bolla chiusa con piccolo fumetto attrattivo

Notifica visiva

Pallino rosso sulla bolla se ci sono nuovi messaggi non letti
Anteprima messaggio sulla bolla (un fumetto che appare temporaneamente)
Animazione di pulsazione per attirare attenzione

Performance e velocità

Il widget Hotely è progettato per essere invisibile a livello di performance:

File JavaScript di poche kilobyte (compresso)
Caricamento asincrono (attributo defer) — non blocca il rendering della pagina
CDN globale per servizio in tutto il mondo
Lazy loading — la chat completa si carica solo al primo clic, non al caricamento pagina
Caching aggressivo — i ritorni sul sito non rifanno il download

Effetto pratico sul Lighthouse score: il widget aggiunge tipicamente 0-2 punti sul Performance Score, irrilevante per il SEO.

Test post-installazione

Dopo aver installato il widget:

Apri il sito in finestra di navigazione anonima (per evitare cookie cached)
Aspetta 3-5 secondi per il caricamento
La bolla dovrebbe apparire in basso a destra
Cliccala: si apre il welcome screen o la chat
Prova a scrivere un messaggio
Verifica che l'Agent risponda
Prova anche su mobile — il device principale dei visitatori

L'aspetto del widget (colori, logo, testi) si configura dalla scheda Design dell'Agent. Le modifiche al design entrano in vigore istantaneamente — non devi rivisitare il sito per aggiornare il widget.

Multi-Agent sullo stesso sito

Per attività complesse (es. hotel con ristorante interno) puoi avere più Agent sullo stesso sito:

Soluzione 1 — Agent diversi per pagine diverse

Pagina hotel → widget Agent struttura
Pagina ristorante → widget Agent ristorante

Si configurano due script con data-chatbot-id diversi, ciascuno mostrato sulla pagina pertinente.

Soluzione 2 — Un solo Agent con welcome screen multi-CTA

L'opzione più comune: un solo Agent con welcome screen che propone CTA distinti ("Camere", "Ristorante", "Spa"). Più semplice per il visitatore.

Soluzione 3 — Switcher di Agent

Per gruppi con multi-proprietà, un widget unico con selettore iniziale ("Quale struttura?") che apre il rispettivo Agent.

Sicurezza e privacy

Il widget:

Carica solo dal dominio hotely.ai (HTTPS sicuro)
Non legge cookie del sito host
Non interferisce con i sistemi di analytics esistenti
Rispetta le impostazioni di cookie banner del sito (può essere bloccato fino al consenso)
Funziona in modalità "no-cookie" se richiesto

Per dettagli su privacy e GDPR vedi Privacy.

Il widget Hotely può coesistere con:

Altri sistemi di chat (per transizioni graduali da un sistema all'altro)
Sistemi di analytics (Google Analytics, Hotjar, Plausible)
Cookie banner (Iubenda, OneTrust, Cookiebot)
Sistemi di newsletter popup esterni
Sistemi di feedback (Hotjar surveys, Typeform)
Pixel di tracking (Facebook, LinkedIn, TikTok)

Per evitare sovrapposizione visiva con altri pulsanti fluttuanti, puoi cambiare posizione del widget.

Risoluzione problemi

Cause possibili:

Codice non incollato correttamente
Cache del browser (prova in finestra anonima)
Cache del CDN del sito (svuota la cache)
Plugin di ad-blocking che blocca lo script
Errore di JavaScript nel sito che blocca esecuzione successiva

Verifica:

Apri DevTools del browser (F12) → Console: vedi errori JS?
Network tab: verifica che embed.js venga caricato
Cerca nel codice sorgente della pagina la presenza del tag <script>

Cause possibili:

ID Agent errato nel codice
Agent disattivato nelle impostazioni
Problemi di rete

Verifica:

Confronta l'ID nel codice con quello in dashboard
Verifica che l'Agent risulti "Pubblicato" in dashboard

Sposta la posizione del widget dalle impostazioni o aumenta il margine dai bordi.

Il caricamento dovrebbe essere 1-3 secondi. Per ritardi maggiori:

Verifica la velocità complessiva del sito (siti lenti rallentano tutto)
Verifica la posizione del codice (meglio nel footer, prima di </body>)

Casi reali

B&B su WordPress

Tempo installazione: 90 secondi (con plugin "Insert Headers and Footers"). Test su mobile e desktop: 5 minuti. Operatività completa: 7 minuti dall'inizio.

Ristorante su Wix

Tempo installazione: 3 minuti (via Tracking Settings). Widget visibile dopo pubblicazione del sito. Test completati il giorno stesso.

Hotel boutique su sito custom

Tempo installazione: 5 minuti (via FTP nel template footer). Test cross-browser e cross-device: 30 minuti. Configurazione ottimale dei trigger di apertura automatica: 1 ora di sperimentazione.

Catena di 12 B&B su template WordPress comune

Tempo per tutti e 12: 20 minuti (un solo edit del template parent, tutti i siti aggiornati). Variazioni per singola struttura solo nelle impostazioni Agent in dashboard.

Prossimi passi

Design — personalizzazione visiva del widget
QR code — distribuzione fisica per camere/tavoli
Email integrazione — canale email
Analytics — monitoraggio del traffico al widget