> ## 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.
# Widget vocale incorporabile
> Aggiungi un agente vocale AI a qualsiasi sito web con poche righe di codice
Il widget vocale incorporabile di ThunderPhone consente ai visitatori del tuo sito web di parlare con un agente AI direttamente dal browser. Non è necessaria alcuna telefonata: gli utenti fanno clic su un pulsante e avviano una conversazione vocale in tempo reale basata su ThunderPhone.
Il widget viene visualizzato come una barra con effetto vetro che si adatta ai temi chiari e scuri, con colori di accento e posizionamento personalizzabili. È distribuito come pacchetto npm `@thunderphone/widget` ed è disponibile anche tramite CDN per ambienti senza bundler.
## Prerequisiti
Prima di incorporare il widget, completa questi tre passaggi nella [Dashboard ThunderPhone](https://app.thunderphone.com):
Vai a **Sviluppatori** nelle impostazioni della dashboard e crea una chiave pubblicabile. Le chiavi pubblicabili iniziano con `pk_live_` e possono essere incluse in sicurezza nel codice lato client.
Nelle stesse impostazioni di Sviluppatori, aggiungi i domini in cui verrà incorporato il widget. `localhost` è sempre consentito per lo sviluppo. Sono supportati i caratteri jolly, ad esempio `*.example.com`.
Vai a **Widget web** nella dashboard e crea un widget. Seleziona l'agente che vuoi esporre e la chiave pubblicabile da utilizzare. L'agente viene risolto automaticamente dalla configurazione della tua chiave pubblicabile.
Le chiavi pubblicabili (`pk_live_...`) **non** sono uguali ai tuoi token API segreti. Le chiavi pubblicabili sono progettate per l'uso lato client e sono limitate alle sessioni del widget sui domini consentiti. Non utilizzare mai il tuo token API segreto nel codice lato client.
***
## Avvio rapido
Installa il pacchetto:
```bash theme={null}
npm install @thunderphone/widget
```
Inserisci il widget nella tua app:
```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
function App() {
return (
)
}
```
Fatto. I tuoi utenti vedranno una barra di chiamata con effetto vetro che li collega al tuo agente AI con un solo clic.
***
## Personalizzazione
Il widget dispone di quattro prop per l'aspetto:
| Prop | Predefinito | Descrizione |
| -------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `theme` | `'light'` | `'light'` per vetro bianco, `'dark'` per vetro scuro |
| `primaryColor` | `'#000000'` (chiaro) / `'#ffffff'` (scuro) | Colore di accento per il pulsante di avvio, la forma d'onda e l'indicatore di connessione |
| `title` | `'Voice assistant'` | Testo visualizzato nel widget |
| `position` | `'bottom-right'` | Angolo della viewport: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |
```tsx Light theme (default) theme={null}
```
```tsx Dark theme with custom color theme={null}
```
Altre tre prop personalizzano la sessione anziché l'aspetto: tutte vengono inoltrate alla richiesta di sessione all'avvio di una chiamata:
| Prop | Descrizione |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| `language` | Override della lingua per sessione: un codice o una locale come `en`, `es` o `fr-FR` |
| `voice` | Override della voce per sessione: un nome di voce come `maria` |
| `context` | Contesto fattuale della pagina o del sito passato all'agente, troncato lato server a 12.000 caratteri |
Consulta il [riferimento del componente React](/it/widget/react) per la tabella completa delle prop.
Per un'interfaccia utente completamente personalizzata, usa l'[hook headless](/it/widget/headless-hook) per gestire la sessione vocale mentre crei la tua interfaccia. L'hook espone livelli audio in tempo reale per creare visualizzazioni reattive all'audio.
***
## Opzioni di integrazione
Scegli il metodo di integrazione più adatto al tuo stack:
Componente UI predefinito con controlli di chiamata e visualizzazione dello stato integrati. Importa, passa le props, fatto.
Controllo completo dell'interfaccia utente. L'hook `useThunderPhone` gestisce la sessione vocale mentre crei la tua interfaccia.
Non serve alcun bundler. Carica il widget tramite un tag script per siti statici, WordPress e altri ambienti non React.
***
## Stile
Il widget include temi chiaro e scuro integrati, controllati dalla prop `theme`, e un colore di accento controllato dalla prop `primaryColor`. Per una personalizzazione più approfondita, puoi sovrascrivere le proprietà e le classi personalizzate CSS. Consulta la [guida allo stile](/it/widget/styling) per i dettagli.
Ti serve aiuto? Contattaci all'indirizzo [support@thunderphone.com](mailto:support@thunderphone.com)