Open in

Componente React

Incorpora il widget vocale ThunderPhone in un

Il componente ThunderPhoneWidget visualizza una barra di chiamata glassmorfica con controlli integrati per disattivare il microfono, terminare la chiamata e mostrare lo stato della connessione. È il modo più rapido per aggiungere l'IA vocale a un'app React.

Installazione

npm install @thunderphone/widget

Utilizzo di base

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

Proprietà

Il componente accetta le seguenti proprietà tramite ThunderPhoneWidgetProps:

Proprietà	Tipo	Obbligatorio	Predefinito	Descrizione
`publishableKey`	`string`	Sì	--	Chiave API pubblicabile (`pk_live_...`) da Widget web nella dashboard. L'agente viene risolto automaticamente dalla configurazione del widget della chiave.
`theme`	`'light' \| 'dark'`	No	`'light'`	Schema di colori. Applica la classe `tp--light` o `tp--dark` alla radice del widget.
`primaryColor`	`string`	No	`'#000000'` (light) / `'#ffffff'` (dark)	Stringa di colore CSS usata come colore di accento (pulsante di chiamata, forma d'onda, indicatori attivi).
`title`	`string`	No	`'Voice assistant'`	Testo visualizzato nella barra del widget.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	No	`'bottom-right'`	Posizione fissa del widget nella finestra di visualizzazione.
`apiBase`	`string`	No	`'https://api.thunderphone.com/v1'`	Sostituzione dell'URL di base dell'API.
`language`	`string`	No	--	Sostituzione della lingua per sessione -- un codice lingua o una lingua regionale come `en`, `es` o `fr-FR`. Se non impostata, viene applicata la lingua configurata dell'agente. Richiede `language` nelle sostituzioni del browser della chiave.
`voice`	`string`	No	--	Sostituzione della voce per sessione -- un nome di voce come `maria`. Se non impostata, viene applicata la voce configurata dell'agente. Richiede `voice` nelle sostituzioni del browser della chiave.
`context`	`string`	No	--	Contesto fattuale della pagina o del sito per sessione passato all'agente, ad esempio i dettagli della pagina visualizzata dal visitatore. Troncato lato server a 12.000 caratteri. Richiede `context` nelle sostituzioni del browser della chiave.
`onConnect`	`() => void`	No	--	Chiamato quando la sessione vocale si connette correttamente.
`onDisconnect`	`() => void`	No	--	Chiamato al termine della sessione.
`onError`	`(error) => void`	No	--	Chiamato in caso di errori. L'oggetto `error` contiene i campi `error` (codice) e `message`.
`className`	`string`	No	--	Nome di classe CSS aggiuntivo applicato al contenitore del widget.
`ringtone`	`boolean \| string`	No	`false`	Riproduce una suoneria durante la connessione. `true` per la suoneria predefinita oppure una stringa URL per un audio personalizzato.

Esempi

Tema scuro con colore personalizzato

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}

Posizione personalizzata

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

Lingua, voce e contesto per sessione

Le prop language, voice e context vengono inoltrate alla richiesta di sessione (POST /widget/session) all'avvio di una chiamata, sovrascrivendo le impostazioni predefinite configurate per l'agente per quella sessione. Abilita ogni prop utilizzata in Override del browser per il widget nella dashboard (o in allowed_overrides della chiave). I nuovi widget non ne accettano nessuna e una richiesta di sessione che ne include una disabilitata non riesce con 400 override_not_allowed; consulta Override del browser.

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}

Usa context per fornire all'agente informazioni fattuali sulla pagina visualizzata dal visitatore -- dettagli del prodotto, prezzi o FAQ specifiche della pagina. L'agente lo considera contenuto della pagina, non istruzioni. Viene troncato lato server a 12.000 caratteri.

Con callback degli eventi

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}

Con stile personalizzato

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

Consulta la guida allo stile per tutte le classi CSS e le proprietà personalizzate disponibili.

Con suoneria

Riproduci un suono di telefono che squilla durante la connessione:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

Usa una suoneria personalizzata passando l'URL di un file audio:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

La suoneria viene riprodotta in loop mentre il widget è nello stato connecting e sfuma gradualmente quando l'agente si connette.

Con base API personalizzata

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

Gestione degli errori

Quando viene attivata la callback onError, riceve un oggetto errore con due campi:

Campo	Tipo	Descrizione
`error`	`string`	Codice di errore leggibile dalla macchina
`message`	`string`	Descrizione dell'errore leggibile dall'utente

I codici di errore comuni includono dominio non consentito, agente non trovato e chiave API non valida.

Passaggi successivi

Hook headless

Ti serve il controllo completo sull'interfaccia utente? Usa invece l'hook useThunderPhone.

Stile

Personalizza colori, dimensioni e layout con le proprietà CSS personalizzate.