Incorpora il widget web

Aggiungi un agente vocale al tuo sito di marketing o assistenza con un solo tag di copione: i visitatori possono parlarci direttamente dal browser, senza bisogno di un numero di telefono.

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 di riferimento dell'SDK — questa guida si concentra sulla configurazione lato ThunderPhone necessaria al widget.

Prerequisiti#

1. Crea un agente

   L'agente il cui prompt e la cui voce eseguiranno la sessione del widget. Imposta widget_enabled: true (impostazione predefinita).

2. Decidi la modalità di instradamento
   • 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. Usalo per utenti autenticati, test A/B o instradamento per pagina.
3. Elenca i domini consentiti

   Indica ogni hostname che incorporerà il widget. I browser inviano l'origine della pagina con ogni richiesta di sessione, quindi l'elenco impedisce che la tua chiave funzioni quando qualcuno la copia su un altro sito. Non è autenticazione: uno script esterno a un browser può inviare qualsiasi intestazione Origin. localhost non è consentito automaticamente in produzione; per eseguire test locali con l'API di produzione, aggiungi localhost all' elenco.

4. Scegli le sovrascritture del browser

   Decidi quali impostazioni di sessione può inviare la tua pagina. Le nuove chiavi non ne accettano nessuna; consulta Sovrascritture del browser.

Crea una chiave pubblicabile#

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

La risposta include una key che inizia con pk_live_.... Le chiavi pubblicabili sono pubbliche per progettazione — puoi includerle senza rischi nel bundle front-end. Consulta la documentazione di riferimento delle chiavi pubblicabili per tutti i campi.

Inserisci il widget nel tuo sito#

La documentazione dell'SDK del widget descrive tre opzioni di integrazione:

Tutte e tre accettano lo stesso publishableKey e visualizzano il pulsante del microfono più l'elemento audio durante la chiamata.

Override del browser#

Il widget può inviare quattro impostazioni per sessione dalla pagina:

La tua chiave pubblicabile è pubblica, quindi chiunque la possieda può inviare queste impostazioni, anche da un copione che falsifica il tuo dominio. Ciascuna è quindi disattivata finché non la autorizzi sulla chiave: selezionala in Override del browser quando crei o modifichi il widget nella dashboard, oppure imposta allowed_overrides tramite l' API delle chiavi pubblicabili. Autorizza solo ciò che la tua pagina invia effettivamente.

Una richiesta di sessione che include un'impostazione non consentita dalla chiave non riesce con 400 e la indica:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

Il controllo si applica in entrambe le modalità. In modalità webhook, un'impostazione consentita viene inoltre inoltrata al tuo webhook web.incoming (context arriva come website_context). Le chiavi create prima dell'introduzione di questa impostazione consentono tutte e quattro, quindi gli embed esistenti continuano a funzionare; disattiva ciò che non usi.

Il context del widget viene troncato a 12.000 caratteri (all'incirca 3.400 token di testo inglese tipico) e contribuisce al sovrapprezzo per le dimensioni del prompt. All'agente viene indicato di trattarlo come contenuto della pagina, non come istruzioni.

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:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

Puoi combinare nel prompt il contesto della tua sessione (quale cliente sta navigando, quale pagina sta visualizzando) e cambiare agente per ciascun rilascio.

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#