Skip to main content
Il widget web offre ai visitatori del tuo sito una conversazione click-to-talk con un agente IA, utilizzando il microfono del browser. È un SDK JavaScript / React separato con la propria documentazione SDK — questa guida si concentra sulla configurazione lato ThunderPhone necessaria al widget.
Puoi fare tutto questo senza cURL: la pagina della dashboard Widget web (/dashboard/web-widgets) crea il widget, ne imposta la modalità e l’agente, gestisce i domini consentiti e ti fornisce lo snippet di incorporamento.

​
Prerequisiti

1

Crea un agente

L’agente il cui prompt e la cui voce eseguiranno la sessione del widget. Imposta widget_enabled: true (il valore predefinito).
2

Scegli la modalità di routing

  • mode="agent" — un agente statico per chiave. La soluzione più semplice.
  • mode="webhook" — il tuo server seleziona l’agente per visitatore tramite un webhook web.incoming. Usala per utenti autenticati, test A/B o routing per pagina.
3

Elenca i domini consentiti

Le chiavi pubblicabili sono vincolate all’origine. Devi indicare ogni nome host che incorporerà il widget. localhost / 127.0.0.1 sono sempre consentiti durante lo sviluppo locale.

​
Crea una chiave pubblicabile

La risposta include una key che inizia con pk_live_.... Le chiavi pubblicabili sono pubbliche per progettazione — puoi includerle in sicurezza nel bundle front-end. Consulta la documentazione delle chiavi pubblicabili per tutti i campi.
allowed_domains deve contenere almeno una voce. *.example.com corrisponde ai sottodomini (ad esempio api.example.com) ma non al dominio senza sottodominio. I caratteri jolly generici come * o *.* vengono rifiutati.

​
Inserisci il widget nel tuo sito

Tre opzioni di integrazione sono illustrate nella documentazione SDK del widget:

Componente React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Hook headless

useThunderPhone() per interfacce utente personalizzate.

Tag script CDN

ThunderPhone.mount({...}) per siti senza bundler.
Tutte e tre accettano lo stesso publishableKey e visualizzano il pulsante del microfono più l’elemento audio durante la chiamata. Il context del widget viene troncato a 12.000 caratteri (circa 3.400 token di testo inglese tipico) e concorre al supplemento per dimensione del prompt.

​
Webhook in modalità widget

Quando mode="webhook", ThunderPhone chiama il tuo webhook_url a ogni avvio di sessione con un payload web.incoming. Restituisci la configurazione dell’agente che vuoi eseguire per quel visitatore — segue lo stesso schema di risposta delle chiamate telefoniche:
Puoi inserire nel prompt il contesto della tua sessione (quale cliente sta navigando, in quale pagina si trova) e cambiare agente a ogni rollout.

​
Osserva le sessioni

Le sessioni del widget vengono visualizzate in GET /v1/calls con direction="widget" — stessa trascrizione, registrazione, valutazione e fatturazione delle chiamate telefoniche. Filtra per direction per creare una dashboard dedicata al widget.

​
Passaggi successivi

Riferimento SDK del widget

Dettagli sull’integrazione React / hook / CDN.

Configurazione dinamica per chiamata

Implementa il flusso mode="webhook" end-to-end.

Riferimento delle chiavi pubblicabili

Ogni campo della risorsa chiave.

API delle sessioni microfono

Salta il widget; usa direttamente LiveKit per interfacce utente personalizzate.