Developer cookbook

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 (valore predefinito).

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 ogni visitatore tramite un webhook web.incoming. Usalo per utenti autenticati, test A/B o instradamento per pagina.
3. Elenca i domini consentiti

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

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"]
  }'

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.

Il context del widget viene troncato a 12.000 caratteri (circa 3.400 token di testo inglese tipico) e contribuisce al sovrapprezzo per la 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:

{
  "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#