Callback Widget

Il Callback Widget è un piccolo form integrabile che permette ai visitatori del tuo sito di lasciare il numero di telefono e ricevere una chiamata dal tuo agente IA — di solito entro pochi secondi. Invece di chiedere ai visitatori di comporre un numero, la conversazione arriva a loro.

È il quinto tipo di widget, accanto ai widget Floating, Pill, Inline e Popup — ma funziona in modo molto diverso. Gli altri widget avviano una conversazione vocale nel browser. Il Callback Widget mette in coda una vera chiamata telefonica effettuata dal tuo agente tramite il tuo numero outbound.

---

Quando Usarlo

Scenario	Perché il Callback Widget Funziona
Landing page di lead-gen	Il visitatore si impegna con un numero di telefono, l'agente lo qualifica nel minuto successivo
Pagine prodotto ad alta intenzione	"Parla con uno specialista" senza obbligare il visitatore a digitare
Siti mobile-first	Un tocco sul pill, nessun prompt di permessi, niente cuffie
Copertura fuori orario	Il visitatore lascia un numero fuori orario, l'agente chiama all'apertura della coda
Meno attrito rispetto ai form	I visitatori compilano un solo campo e ottengono una risposta immediata

---

Idoneità

Il Callback Widget richiede tre cose sul tuo account prima di poter essere attivato:

Requisito	Perché
Piano a pagamento (Starter o superiore)	I minuti outbound consumati durante la callback sono fatturati al minuto
Numero di telefono outbound verificato assegnato all'agente	L'agente ha bisogno di un numero reale da cui chiamare
Email verificata sul tuo workspace	Conferma la titolarità prima che le chiamate outbound vengano sbloccate

Se manca uno di questi, la sezione Callback widget nel tab Widgets dell'agente mostra un avviso che ti indica esattamente cosa sistemare. Il widget resta disattivato finché tutti e tre non sono in regola.

Piano Free

Il Callback Widget non è disponibile sul piano Free perché effettua chiamate telefoniche outbound. Tutti gli altri tipi di widget (Floating, Pill, Inline) restano gratuiti.

---

Configurazione

1. Abilita la callback sull'agente

1. Apri il tuo agente e vai al tab Widgets.
2. Scorri fino alla sezione Callback widget.
3. Attiva il toggle "Enable callback widget".
4. Configura:
   • Retry attempts — quante volte l'agente riprova se il visitatore non risponde (1–5, default 3).
   • Retry interval — minuti tra i tentativi (1–30, default 5).
   • Widget language — la lingua in cui il form, i messaggi di stato e il country picker parlano al visitatore (14 lingue disponibili — vedi sotto).
   • Theme — schema colori per il pill flottante e il dialog (usa la stessa palette di temi degli altri widget).
5. Salva.

Un'anteprima live del widget appare accanto alle impostazioni così vedi subito le modifiche — non serve fare deploy per testarne l'aspetto.

2. Copia lo snippet di embed

Nella stessa sezione, copia lo snippet HTML:

<hanc-ai-callback agent-id="YOUR_AGENT_ID"></hanc-ai-callback>
<script src="https://unpkg.com/hanc-webrtc-widgets@latest" async type="text/javascript"></script>

Incollalo una sola volta nel tuo sito, tipicamente subito prima di </body>. Il widget appare come un pill flottante nell'angolo della pagina.

suggerimento

Il tag @latest significa che il tuo sito riceve automaticamente le nuove versioni del widget appena rilasciate. Fissa una versione specifica (es. hanc-webrtc-widgets@1.4.0) se vuoi pieno controllo sugli aggiornamenti.

---

Cosa Vede il Visitatore

Il widget guida i visitatori attraverso quattro stati:

Stato	Cosa Vede il Visitatore
Form	Pill flottante nell'angolo. Click per aprire. Country picker a sinistra, input telefono a destra, pulsante di submit.
In coda	"Sei in coda — circa N secondi prima che ti chiamiamo." Si aggiorna live.
In composizione	"Ti stiamo chiamando ora." Resta finché la chiamata non si connette o fallisce.
Completata / Fallita	Una breve conferma o un messaggio di errore cordiale con un suggerimento per "ricaricare la pagina per fare un'altra callback".

Il form valida automaticamente il numero di telefono rispetto al formato nazionale del paese scelto e rifiuta il submit a meno che il numero non sia plausibile.

Copertura paesi

Il country picker copre Europa (UE + DACH + UK), Nord America (US + Canada) e una selezione curata di altri paesi ampiamente supportati. Ogni paese mostra la sua bandiera, il nome e un placeholder di esempio nel formato nativo, così il visitatore sa cosa digitare.

Se un paese usato dai tuoi visitatori non è elencato, contatta support@hanc.ai — la copertura viene ampliata regolarmente.

---

Attributi HTML

Il widget accetta questi attributi sul tag <hanc-ai-callback>:

Attributo	Obbligatorio	Descrizione
agent-id	Sì	L'identificatore univoco del tuo agente
locale	No	Sovrascrive la lingua UI del widget per questa pagina (es. locale="de"). Utile se il tuo sito è multilingua e la locale di pagina non corrisponde a quella di default dell'agente.
theme	No	Sovrascrive il tema colore per questa pagina
position	No	Dove si ancora il pill flottante (bottom-right, bottom-left, top-right, top-left)

Tutto ciò che lasci fuori ricade sulla configurazione dell'agente nella dashboard.

Esempio: pagina tedesca su un sito multilingua

<hanc-ai-callback agent-id="YOUR_AGENT_ID" locale="de"></hanc-ai-callback>
<script src="https://unpkg.com/hanc-webrtc-widgets@latest" async></script>

Il testo del pill, le etichette del dialog, il country picker e i messaggi di stato passano tutti al tedesco. L'agente stesso continua a parlare nella lingua per cui è configurato — locale influenza solo ciò che il visitatore legge sulla pagina.

---

Lingua del Widget

L'UI del widget è disponibile in 14 lingue integrate:

Codice	Lingua
en	English
de	Deutsch
fr	Français
es	Español
it	Italiano
pt	Português
pl	Polski
cs	Čeština
hu	Magyar
tr	Türkçe
kk	Қазақша
zh	中文
ru	Русский
uk	Українська

L'agente sceglie la lingua da tre fonti, in ordine di priorità:

1. L'attributo locale="…" sull'embed (priorità più alta)
2. La Widget language impostata nel tab Widgets dell'agente
3. Inglese (default)

Widget language ≠ lingua parlata dall'agente

La lingua del widget influenza solo il testo a schermo che legge il visitatore — etichette, country picker, messaggi di stato. La conversazione vocale vera e propria avviene nella lingua per cui il tuo agente è configurato.

---

Comportamento dei Retry

Se il visitatore non risponde al primo tentativo, l'agente aspetta l'intervallo configurato e richiama — fino al numero di tentativi configurato.

• Tentativi: 1–5 (default 3)
• Intervallo: 1–30 minuti (default 5)

Il widget mostra al visitatore lo stato di ogni tentativo. Dopo che tutti i tentativi falliscono, il widget passa allo stato "non siamo riusciti a contattarti" con un messaggio cortese.

Scegli i numeri giusti

Tre tentativi a intervalli di cinque minuti funziona bene per la maggior parte delle pagine di lead-gen — abbastanza rapidi mentre il visitatore sta ancora navigando, abbastanza gentili da non risultare invadenti. Alzali se il tuo pubblico tende a ignorare i numeri sconosciuti.

---

Una Callback per Caricamento Pagina

Una volta che un visitatore ha inviato il numero, il widget si blocca per il resto della vita di quella pagina:

• Chiudere il dialog comprime il pill ma non resetta il form.
• Riaprire mostra lo stato attuale (in coda / in composizione / completata / fallita), non un form nuovo.
• Per fare una seconda callback, il visitatore deve ricaricare la pagina.

Questo previene submission duplicate accidentali mentre una chiamata è già in arrivo. Se il visitatore annulla esplicitamente la propria callback in coda dal dialog (il pulsante "Cancel" sulla schermata di coda), il blocco viene rilasciato e può inviare di nuovo subito.

Cosa succede se ricaricano a callback in corso?

Se un visitatore ricarica la pagina mentre l'agente sta ancora ritentando il suo numero, il widget rileva che esiste già una callback attiva per lo stesso numero e si ricollega silenziosamente — nessuna chiamata duplicata, nessuna seconda voce in coda. Il visitatore vede semplicemente il suo stato esistente riprendere da dove si era interrotto.

---

Concorrenza e Throughput

Un singolo agente può avere fino a 10 callback in corso contemporaneamente. Le submission oltre questa soglia attendono in coda e vengono composte man mano che si libera capacità.

Il loop di "agente rilasciato e poi compone" svuota la coda in continuazione — la maggior parte dei visitatori viene chiamata entro pochi secondi dal submit se non sei vicino al limite di concorrenza.

C'è un rate limit per numero (un numero può essere messo in coda solo un paio di volte all'ora per lo stesso agente) per prevenire abusi. I visitatori che lo raggiungono vedono un cortese messaggio "ti contatteremo a breve" invece della schermata di coda.

---

Anteprima Live nella Dashboard

Il tab Widgets mostra un'anteprima live del callback widget accanto alle impostazioni. Ogni modifica che fai — tema, lingua, numeri di retry — aggiorna l'anteprima all'istante. Non devi fare il deploy del tuo sito per vedere come apparirà il widget.

L'anteprima usa un manifest mock con la lista paesi completa e l'idoneità demo, così il widget si renderizza anche sui piani in cui le callback outbound non sono ancora disponibili.

---

Tracking Integrato

Il widget emette gli stessi eventi call-start e call-end degli altri widget. Mettiti in ascolto in JavaScript se vuoi attivare la tua analytics:

const widget = document.querySelector('hanc-ai-callback');

widget.addEventListener('call-start', () => {
  // La callback del visitatore è stata appena connessa — traccia come conversione
});

widget.addEventListener('call-end', () => {
  // Callback terminata — traccia durata, esito, ecc.
});

---

Disponibilità per Piano

Piano	Callback Widget
Free	Non disponibile (richiede chiamate outbound)
Starter / Pro / Business / Enterprise	Disponibile

Tutti i piani a pagamento ottengono lo stesso set di funzionalità widget. Il costo per chiamata segue la tua normale tariffa outbound — vedi Billing.

---

Correlati

• Website Widgets — tipi di widget Floating, Pill, Inline e Popup per conversazioni in-browser
• Settings — impostazioni delle chiamate a livello di agente, inclusa la Max Call Duration che limita anche le callback
• Phone Numbers — collega il numero outbound da cui il tuo callback widget chiamerà
• FAQ — domande frequenti e casi limite