---
title: "Widget vocale incorporabile"
description: "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 **Widget web** nella dashboard e crea un widget. Seleziona l'agente che desideri esporre. Ogni widget dispone della propria chiave pubblicabile (`pk_live_...`), che può essere inclusa in sicurezza nel codice lato client; l'agente viene risolto dalla chiave.
Nello stesso widget, aggiungi i domini in cui verrà incorporato. Sono supportati i caratteri jolly, ad esempio `*.example.com`. L'elenco impedisce il funzionamento del widget quando qualcuno copia la tua chiave su un altro sito; non è un sistema di autenticazione, poiché uno script esterno a un browser può inviare qualsiasi intestazione `Origin`. In produzione, `localhost` non è consentito automaticamente: aggiungilo all'elenco per eseguire test locali con l'API di produzione.
Se la tua pagina imposta `language`, `voice` o `context`, abilita ciascuna opzione in **Sostituzioni del browser**. I nuovi widget non ne accettano alcuna e una richiesta di sessione che include un'impostazione disabilitata non riesce con `400 override_not_allowed`. Consulta [Sostituzioni del browser](/it/guides/embed-web-widget).
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.
Per impostazione predefinita, le sessioni del widget terminano dopo 30 minuti, o prima se la durata massima delle chiamate dell'agente è inferiore. Modifica il limite per chiave con `max_call_duration_seconds` sulla [chiave pubblicabile](/api-reference/publishable-keys) (fino a 6 ore), oppure impostalo su `null` per usare il limite dell'agente.
---
## Avvio rapido
Installa il pacchetto:
```bash
npm install @thunderphone/widget
```
Inserisci il widget nella tua app:
```tsx
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)
```
```tsx Dark theme with custom color
```
Altre tre proprietà personalizzano la sessione anziché l'aspetto -- tutte vengono inoltrate alla richiesta di sessione quando inizia una chiamata. Ciascuna funziona solo quando la chiave pubblicabile del widget la consente in **Override del browser**; in caso contrario, la richiesta di sessione non riesce con `400 override_not_allowed`:
| 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.
Ogni conversazione del widget è una chiamata. Conta ai fini del [limite di chiamate simultanee](/api-reference/introduction#call-limits) della tua organizzazione (20 chiamate in corso per impostazione predefinita, condivise con le chiamate telefoniche e altre chiamate) e di un limite del widget di 25 sessioni attive (o del tuo limite di chiamate simultanee, se superiore). Raggiunto uno dei due limiti, una nuova conversazione non può iniziare finché una chiamata non termina.
---
## 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)