> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Componente React

> Incorpora il widget vocale ThunderPhone in un'applicazione React

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

```bash theme={null}
npm install @thunderphone/widget
```

## Utilizzo di base

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

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

***

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

```tsx theme={null}
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

```tsx theme={null}
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:

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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"
    />
  )
}
```

```css theme={null}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

Consulta la [guida allo stile](/it/widget/styling) per tutte le classi CSS e le proprietà personalizzate disponibili.

### Con suoneria

Riproduci un suono di telefono che squilla durante la connessione:

```tsx theme={null}
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:

```tsx theme={null}
<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

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

```tsx theme={null}
<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

<CardGroup cols={2}>
  <Card title="Hook headless" icon="code" href="/it/widget/headless-hook">
    Ti serve il controllo completo sull'interfaccia utente? Usa invece l'hook `useThunderPhone`.
  </Card>

  <Card title="Stile" icon="palette" href="/it/widget/styling">
    Personalizza colori, dimensioni e layout con le proprietà CSS personalizzate.
  </Card>
</CardGroup>