Widget per sito web
Incorpora il tuo agente vocale su qualsiasi sito web così i visitatori possono avviare una conversazione vocale direttamente dal browser. La scheda Widgets fornisce codici di embed, opzioni di personalizzazione e impostazioni di sicurezza dei domini.
Il Widget di richiamata funziona in modo molto diverso dai widget in questa pagina — invece di avviare una chiamata vocale nel browser, raccoglie il numero di telefono del visitatore e fa in modo che il tuo agente lo richiami. Vedi la pagina dedicata Widget di richiamata.
Tipi di widget
Hanc.AI offre quattro tipi di widget in-browser, più un Widget di richiamata separato per le richiamate telefoniche:
| Widget | Nome del tag | Descrizione | Ideale per |
|---|---|---|---|
| Floating Widget | hanc-ai-floating-call | Pulsante a orb che fluttua sopra la tua pagina | Call-to-action sempre visibile |
| Pill Widget | hanc-ai-pill-call | Pulsante compatto a forma di pill inserito in linea nel tuo contenuto | Ingombro minimo all'interno di un layout esistente |
| Pill Floating Widget | hanc-ai-pill-floating-call | Stessa forma compatta a pill del Pill, ma fluttua con la pagina come il widget Floating | Quando vuoi un'estetica a pill che segue il visitatore mentre scorre |
| Inline Widget | hanc-ai-inline-call | Pulsante di chiamata a dimensione piena incorporato nel contenuto della pagina | Sezioni dedicate "Parla con noi" |
| Callback Widget | hanc-ai-callback | Modulo per il numero di telefono; l'agente richiama il visitatore | Pagine di generazione lead, landing page ad alta intenzione — vedi Widget di richiamata |
Attributi comuni
Tutti i tipi di widget supportano questi attributi principali:
| Attributo | Obbligatorio | Descrizione | Predefinito |
|---|---|---|---|
agent-id | Sì | L'identificativo univoco del tuo agente | — |
voice-service-url | No | Sovrascrivi l'URL del servizio vocale | Rilevato automaticamente |
api-base-url | No | Sovrascrivi l'URL base dell'API | Rilevato automaticamente |
Attributi di visualizzazione
| Attributo | Descrizione | Valori | Predefinito |
|---|---|---|---|
position | Posizione del widget sulla pagina | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Dimensione del widget in pixel | Numero | 120 |
theme | Nome del tema di colore | Vedi Temi di colore | default |
Attributi del testo del pulsante
| Attributo | Descrizione | Predefinito |
|---|---|---|
button-start-text | Testo mostrato sul pulsante inattivo | "Call" |
button-connecting-text | Testo mostrato durante la connessione | "Connecting..." |
button-end-text | Testo mostrato durante una chiamata attiva | — |
Attributi dei termini
| Attributo | Descrizione | Predefinito |
|---|---|---|
terms-enabled | Abilita la finestra di dialogo di consenso prima della chiamata | false |
terms-content | Testo di consenso formattato in Markdown | "" |
terms-url | Link alla tua pagina Termini e Condizioni | "https://hanc.ai/terms" |
privacy-url | Link alla tua pagina Informativa sulla Privacy | "https://hanc.ai/privacy" |
Gli attributi dei termini impostati sull'elemento HTML vengono sovrascritti dalle impostazioni del widget dell'agente recuperate dall'API, a meno che skip-fetch non sia impostato su true.
Attributi del suono
| Attributo | Descrizione | Predefinito |
|---|---|---|
sound-enabled | Abilita i suoni di inizio/fine chiamata | true |
sound-volume | Volume degli effetti sonori | 0.25 |
sound-preset | Identificativo del preset sonoro | "1" |
Temi di colore
Personalizza l'aspetto del widget con 11 temi di colore integrati:
| Tema | Valore |
|---|---|
| Default | default |
| Purple | purple |
| Blue | blue |
| Cyan | cyan |
| Emerald | emerald |
| Amber | amber |
| Tangerine | tangerine |
| Rose | rose |
| Ember | ember |
| Black | black |
| White | white |
Ogni tema ha sia una variante scura che chiara. Imposta il tema tramite l'attributo theme nel codice di embed, o configuralo nelle impostazioni del widget dell'agente.
Esempi di embed
Floating Widget
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Floating Widget con tema e posizione
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Pill Widget
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Inline Widget
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
L'URL dello script qui sopra carica sempre l'ultimo widget rilasciato — il tuo sito adotta automaticamente i miglioramenti, e @latest è il valore predefinito quando non viene specificata alcuna versione. Se hai bisogno di bloccare su una release fissa, specificala esplicitamente aggiungendo la versione che vuoi, es. https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.
Eventi del widget
I widget emettono eventi che puoi ascoltare in JavaScript:
| Evento | Descrizione |
|---|---|
status-changed | Attivato quando lo stato della chiamata cambia |
connecting | La chiamata è in fase di stabilimento |
connected | La chiamata è attiva |
idle | Nessuna chiamata attiva |
error | Si è verificato un errore |
audio-track | Traccia audio remota ricevuta (per la visualizzazione) |
local-audio-track | Traccia audio del microfono locale (per la visualizzazione) |
microphone-enabled | Il microfono è stato abilitato |
microphone-disabled | Il microfono è stato disabilitato |
call-start | Attivato quando una chiamata inizia con successo |
call-end | Attivato quando la chiamata termina |
Esempio: ascoltare gli eventi
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Lasciare che l'agente apra le pagine
Durante una chiamata dal browser l'agente può chiedere al suo sito di aprire una pagina — «le mostro i prezzi» — e il visitatore lo vede senza interrompere la conversazione.
Comanda la sua pagina. L'agente invia una richiesta, il suo codice decide cosa significa. Aprire un URL, cambiare scheda, scorrere fino a una sezione, espandere una fisarmonica: sono tutte risposte valide.
Servono tre passaggi, e nessuno funziona da solo.
Passo 1 — Dica all'agente quali pagine esistono
L'agente non vede la mappa del suo sito. Chiede solo percorsi che gli ha fornito lei: li elenchi nel prompt dell'agente o nella base di conoscenza.
Pagine del nostro sito:
/pricing — piani e prezzi
/contact — modulo di contatto e telefono
/product/crm — il CRM
Senza questo passaggio l'agente non ha nulla da chiedere e non ci prova nemmeno.
Passo 2 — Gestisca la richiesta nella sua pagina
Lo aggiunga una volta sola, ovunque dopo lo script del widget. L'evento risale la pagina, quindi document è un buon punto d'ascolto:
<script>
document.addEventListener('agent-command', (event) => {
const { type, payload } = event.detail;
if (type === 'navigate') {
// SPA: naviga senza ricaricare — la chiamata prosegue.
router.push(payload.path);
// Sito classico: apri una seconda scheda, questa (e la chiamata) resta viva.
// window.open(payload.path, '_blank');
event.preventDefault(); // ← è così che dice all'agente «fatto»
}
});
</script>
La chiamata vive in questa pagina. window.location.href = … scarica il documento e la conversazione se ne va con lui: il visitatore viene interrotto a metà frase. Se ha un router, navighi lato client; altrimenti apra la pagina in una nuova scheda. Non c'è riconnessione: nulla sopravvive a un ricaricamento.
preventDefault() non è facoltativoÈ l'unico modo per dire «me ne sono occupato». Senza, all'agente viene comunicato che il sito non supporta la navigazione: smette di provarci per il resto della chiamata e torna a spiegare dove cliccare. Nella console non compare nulla — la pagina sembra semplicemente aver ignorato la richiesta, perché l'ha ignorata.
Passo 3 — Provi
Chiami il suo agente dal sito e gli chieda una pagina per nome. Devono succedere due cose: la pagina si apre e l'agente dice qualcosa come «ecco i prezzi» invece di «li trova nel menu».
Rispondere all'agente con dei dati
Alcuni comandi sono domande, non istruzioni. Arrivano allo stesso modo, ma si risponde con respond():
| Comando | Cosa chiede l'agente | Cosa risponde lei |
|---|---|---|
navigate | «apri questo percorso» | niente: basta preventDefault() |
page_context | «cosa sta guardando il visitatore?» | ciò che è utile: percorso, titolo, prodotto |
cart_state | «cosa ha nel carrello?» | articoli, totali, valuta |
<script>
document.addEventListener('agent-command', (event) => {
const { type, respond } = event.detail;
if (type === 'page_context') {
event.preventDefault();
respond({ path: location.pathname, title: document.title });
}
});
</script>
Dopo preventDefault() ha circa un secondo per rispondere: un await va bene, una chiamata API lenta no. Risponda con quello che ha già.
Cosa l'agente può e non può chiedere
- Solo percorsi del suo sito. Un percorso deve iniziare con
/. Tutto ciò che potrebbe uscire dal suo dominio —//evil.com,https://…, backslash — viene rifiutato prima di arrivare alla pagina. Un agente non può mandare i suoi visitatori altrove. - Solo chiamate dal browser. In una telefonata non c'è nessuna pagina da aprire, quindi lì questi comandi non esistono.
- Un rifiuto basta. Se la sua pagina non conferma la prima richiesta, l'agente smette di chiedere per il resto della chiamata. Non riprova e — soprattutto — non dirà al visitatore di aver aperto qualcosa che non ha aperto.
Registri ogni comando prima di filtrarlo: document.addEventListener('agent-command', e => console.log(e.detail)). Se vede navigate in console, l'agente ha fatto la sua parte e manca preventDefault() o il suo handler. Se non vede nulla, all'agente non è mai stato detto che quel percorso esiste: torni al passo 1.
Requisiti tecnici
I widget richiedono che il browser del visitatore supporti:
- WebGL 2.0 — per il rendering
- Web Audio API — per l'elaborazione audio
- WebRTC — per la comunicazione vocale in tempo reale
Tutti i browser moderni (Chrome, Firefox, Safari, Edge) supportano queste tecnologie.
Restrizioni sui domini
Controlla quali siti web possono incorporare il widget del tuo agente.
Domini sempre consentiti
I seguenti domini sono sempre consentiti indipendentemente dalla configurazione:
hanc.ai(e sottodomini)hanc.me(e sottodomini)localhost
Consenti tutti i domini
Per impostazione predefinita, il tuo widget può essere incorporato su qualsiasi sito web. Attiva "Allow all domains" nelle impostazioni del widget per limitare questo.
Limita a domini specifici
Quando limitato, aggiungi ciascun dominio che dovrebbe essere consentito:
- Inserisci i nomi dei domini senza
https://(es.example.com) - I sottodomini richiedono voci separate (es.
www.example.com,shop.example.com) - Le porte possono essere specificate (es.
localhost:3000) - Un massimo di 50 domini può essere inserito nella whitelist
Per gli agenti in produzione, limita i widget ai tuoi domini per evitare incorporamenti non autorizzati.
Termini e Condizioni
Abilita una finestra di dialogo di consenso prima che i chiamanti possano avviare una conversazione.
Configurazione
| Impostazione | Descrizione |
|---|---|
| Enable Terms | Attiva/disattiva la finestra di dialogo dei termini |
| Terms Content | Testo di consenso formattato in Markdown mostrato agli utenti (max 5.000 caratteri) |
| Terms URL | Link alla tua pagina completa Termini e Condizioni |
| Privacy URL | Link alla tua pagina Informativa sulla Privacy |
Quando abilitato:
- Gli utenti vedono una finestra di dialogo di consenso prima di avviare una chiamata
- Devono cliccare "Agree" per procedere
- Il consenso è memorizzato localmente nel browser
- Il pulsante Reset Consent cancella il consenso memorizzato per i test
Formattazione del contenuto
Il contenuto dei termini supporta la formattazione Markdown:
- Usa
####per i titoli - Usa
**grassetto**per l'enfasi - Usa le interruzioni di riga per la leggibilità
Correlati
- Widget di richiamata — Richiamate telefoniche per i visitatori che preferiscono non parlare in-browser
- Panoramica degli agenti vocali
- Impostazioni — Impostazioni dell'agente inclusa la configurazione del widget
- Integrazioni — Chiavi API e configurazione dei numeri di telefono