Componente React - ThunderPhone

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"
    />
  )
}

Devi importare il file CSS affinché il widget venga visualizzato correttamente. Senza di esso, il widget non avrà stili.

Proprietà

Il componente accetta le seguenti proprietà tramite ThunderPhoneWidgetProps:

Proprietà	Tipo	Obbligatoria	Predefinito	Descrizione
`publishableKey`	`string`	Sì	—	Chiave API pubblicabile (`pk_live_...`) dalle impostazioni Sviluppatori. 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'` (chiaro) / `'#ffffff'` (scuro)	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 viewport.
`apiBase`	`string`	No	`'https://api.thunderphone.com/v1'`	Sovrascrittura dell’URL di base dell’API.
`language`	`string`	No	—	Sovrascrittura della lingua per sessione: un codice lingua o una locale come `en`, `es` o `fr-FR`. Se non impostata, viene applicata la lingua configurata dell’agente.
`voice`	`string`	No	—	Sovrascrittura della voce per sessione: un nome voce come `maria`. Se non impostata, viene applicata la voce configurata dell’agente.
`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.
`onConnect`	`() => void`	No	—	Chiamata quando la sessione vocale si connette correttamente.
`onDisconnect`	`() => void`	No	—	Chiamata quando la sessione termina.
`onError`	`(error) => void`	No	—	Chiamata 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 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 props language, voice e context vengono inoltrate alla richiesta di sessione (POST /widget/session) all’avvio di una chiamata, sovrascrivendo i valori predefiniti configurati per l’agente per quella sessione:

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 conoscenze fattuali sulla pagina visualizzata dal visitatore — dettagli del prodotto, prezzi o FAQ specifiche della pagina. Il valore 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

Devi impostare apiBase solo se utilizzi un endpoint API self-hosted o proxy. Il valore predefinito punta a https://api.thunderphone.com/v1.

<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.

​Installazione

​Utilizzo di base

​Proprietà

​Esempi

​Tema scuro con colore personalizzato

​Posizione personalizzata

​Lingua, voce e contesto per sessione

​Con callback degli eventi

​Con stile personalizzato

​Con suoneria

​Con base API personalizzata

​Gestione degli errori

​Passaggi successivi

Hook headless

Stile

Installazione

Utilizzo di base

Proprietà

Esempi

Tema scuro con colore personalizzato

Posizione personalizzata

Lingua, voce e contesto per sessione

Con callback degli eventi

Con stile personalizzato

Con suoneria

Con base API personalizzata

Gestione degli errori

Passaggi successivi