> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.
# Personalizzazione del widget
I **widget** consentono di integrare subito ElevenAgents in qualsiasi sito web. Puoi personalizzare il widget tramite l'interfaccia utente oppure tramite i nostri [SDK ElevenAgents](/docs/it/eleven-api/resources/libraries) type-safe, per avere il pieno controllo su stile e comportamento. Le impostazioni degli SDK hanno priorità sulla personalizzazione dall'interfaccia utente.
Il nostro widget è multimodale e può elaborare testo e audio.
> **Note**
>
> Puoi anche recuperare la configurazione del widget e il link condivisibile di un agente da Claude o da un altro client MCP tramite il [server MCP ospitato](/docs/it/eleven-agents/operate/hosted-mcp).
## Configurazione delle modalità
Il widget supporta modalità di input flessibili per adattarsi al tuo caso d'uso. Configura queste opzioni nella dashboard in **Canali** → **Widget** → **Interfaccia**.
> **Note**
>
> La multimodalità è pienamente supportata nei nostri SDK client. Scopri di più [qui](/docs/it/eleven-api/resources/libraries).
**Modalità disponibili:**
* **Solo voce** (predefinita): gli utenti interagiscono esclusivamente tramite il parlato.
* **Voce + testo**: gli utenti possono passare dall'input vocale a quello testuale durante le conversazioni.
* **Modalità chat**: le conversazioni avviate con un messaggio di testo iniziano in modalità chat, solo testo, senza funzionalità vocali.
Per ulteriori informazioni sull'uso della modalità chat, solo testo, tramite i nostri SDK, consulta la [guida alla modalità chat](/docs/it/eleven-agents/guides/chat-mode).
> **Note**
>
> Per impostazione predefinita, il widget usa la modalità solo voce. Abilita l'interruttore dell'input di testo per consentire interazioni multimodali oppure il supporto della modalità solo testo per conversazioni esclusivamente testuali avviate tramite testo.
## Incorporare il widget
> **Note**
>
> Al momento i widget richiedono agenti pubblici con l'autenticazione disabilitata. Assicurati di disabilitarla nella scheda **Avanzate** delle impostazioni dell'agente.
Aggiungi questo snippet di codice alla sezione `` del tuo sito web. Per renderlo disponibile in tutto il sito, inseriscilo nel file `index.html` principale:
**`Codice di incorporamento del widget`**
```html title="Codice di incorporamento del widget"
```
> **Info**
>
> Per una maggiore sicurezza, definisci i domini consentiti nella **Allowlist** del tuo agente, nella scheda **Sicurezza**. In questo modo l'accesso è limitato agli host specificati.
## Attributi del widget
Questo codice di incorporamento di base visualizzerà il widget con la configurazione predefinita definita nella dashboard dell'agente.
Il widget supporta vari attributi HTML per un'ulteriore personalizzazione:
#### Configurazione principale
```html
```
#### Personalizzazione visiva
```html
```
#### Personalizzazione del testo
```html
```
#### Rendering Markdown
Il widget esegue il rendering del Markdown nelle risposte dell'agente. Per prevenire il phishing, per impostazione predefinita i link vengono visualizzati come testo semplice.
```html
```
## Configurazione runtime
Puoi usare altri due attributi HTML per personalizzare il comportamento dell'agente a runtime. Puoi utilizzare queste due funzionalità insieme, separatamente o non utilizzarle affatto.
### Variabili dinamiche
Le variabili dinamiche ti permettono di inserire valori runtime nei messaggi, nei prompt di sistema e negli strumenti del tuo agente.
```html
```
Tutte le variabili dinamiche richieste dall'agente devono essere passate nel widget.
> **Info**
>
> Scopri di più nella nostra [guida alle variabili dinamiche](/docs/it/eleven-agents/customization/personalization/dynamic-variables).
### Override
Gli override permettono di personalizzare completamente il comportamento del tuo agente a runtime:
```html
```
Puoi abilitare gli override per campi specifici e sono del tutto facoltativi.
> **Info**
>
> Scopri di più nella nostra [guida agli override](/docs/it/eleven-agents/customization/personalization/overrides).
## Personalizzazione visiva
Personalizza l'aspetto del widget, il contenuto testuale, la selezione della lingua e altro ancora.
#### Aggiorna dalla dashboard
Apri il tuo agente nella dashboard e vai alla scheda **Widget** per personalizzare aspetto, avatar, testo, termini, supporto linguistico e altro ancora.
#### Aggiorna tramite la CLI
#### Recupera la configurazione dell'agente
```bash
elevenlabs agents pull --agent ""
```
#### Modifica \`agent\_configs/\.json\`
Imposta i campi in `platform_settings.widget`. Ad esempio, per cambiare i colori dell'orb e la modalità di feedback:
```json
{
"platform_settings": {
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB"
},
"feedback_mode": "during",
"bg_color": "#ffffff",
"text_color": "#000000",
"btn_color": "#000000",
"btn_text_color": "#ffffff"
}
}
}
```
#### Invia le modifiche
```bash
elevenlabs agents push --agent ""
```
#### Aggiorna tramite l'API
```python
from elevenlabs import ElevenLabs
elevenlabs = ElevenLabs()
elevenlabs.conversational_ai.agents.update(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
platform_settings={
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB",
},
"feedback_mode": "during",
},
},
)
```
```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
platformSettings: {
widget: {
variant: "full",
placement: "bottom-right",
avatar: {
type: "orb",
color1: "#6DB035",
color2: "#F5CABB",
},
feedbackMode: "during",
},
},
});
```
#### Aspetto
Personalizza colori e forme del widget in linea con l'identità del tuo brand.
#### Feedback
Raccogli informazioni dagli utenti per migliorare le prestazioni dell'agente. Puoi usarle per ottimizzare la knowledge base e il prompt di sistema del tuo agente.
**Modalità di raccolta**
* **Nessuna**: disabilita completamente la raccolta di feedback.
* **Durante la conversazione**: supporta feedback in tempo reale durante le conversazioni. Verranno raccolti metadati aggiuntivi, come la risposta dell'agente che ha generato il feedback, per aiutarti a individuare ulteriormente eventuali lacune.
* **Dopo la conversazione**: mostra una singola richiesta di feedback dopo la conversazione.
> **Note**
>
> Invia feedback in modo programmatico tramite l'[API](/docs/it/eleven-agents/api-reference/conversations/create) quando usi implementazioni SDK personalizzate.
#### Avatar
Configura l'orb vocale o fornisci un tuo avatar.
**Opzioni disponibili**
* **Orb**: scegli due colori del gradiente, ad esempio #6DB035 e #F5CABB.
* **Link/immagine**: usa un'immagine avatar personalizzata.
#### Testo visualizzato
Personalizza tutti gli elementi di testo visualizzati nel widget, ad esempio per modificare le etichette dei pulsanti.
#### Termini
Visualizza termini e condizioni personalizzati prima della conversazione.
**Opzioni disponibili**
* **Contenuto dei termini**: usa Markdown per formattare il testo della tua policy.
* **Chiave di archiviazione locale**: una chiave, ad esempio "terms\_accepted", per evitare di mostrare il prompt agli utenti di ritorno.
**Utilizzo**
I termini vengono mostrati agli utenti in una finestra modale prima di avviare la chiamata:
I termini possono essere scritti in Markdown, consentendoti di:
* Aggiungere link a policy esterne
* Formattare il testo con titoli ed elenchi
* Includere enfasi e stile
Per ulteriore assistenza con Markdown, consulta la [guida di CommonMark](https://commonmark.org/help/).
> **Info**
>
> Una volta accettato, lo stato viene memorizzato localmente e all'utente non verrà più mostrato il prompt nelle visite successive.
#### Lingua
Abilita il supporto multilingue nel widget.
> **Note**
>
> Per abilitare la selezione della lingua, devi prima [aggiungere altre lingue](/docs/it/eleven-agents/customization/voice/customization/language) al tuo agente.
#### Disattivazione audio
Consenti agli utenti di disattivare l'audio nel widget.
Per aggiungere il pulsante di disattivazione audio, abilita questa opzione nella scheda `interface` delle impostazioni `widget` dell'agente.
#### Pagina condivisibile
Personalizza la landing page pubblica del widget, ovvero il link condivisibile.
**Opzioni disponibili**
* **Descrizione**: fornisci un breve paragrafo che spieghi lo scopo della chiamata.
---
## Implementazione avanzata
> **Note**
>
> Per una personalizzazione più avanzata, usa gli [SDK ElevenAgents](/docs/it/eleven-api/resources/libraries) type-safe con un'applicazione Next.js, React o Python.
### Strumenti client
Gli strumenti client ti permettono di estendere le funzionalità del widget aggiungendo event listener. In questo modo il widget può eseguire azioni come:
* Reindirizzare l'utente a una pagina specifica
* Inviare un'email al tuo team di assistenza
* Reindirizzare l'utente a un URL esterno
Per vedere esempi di questi strumenti in azione, avvia una chiamata con l'agente nell'angolo in basso a destra di questa pagina. Il [codice sorgente è disponibile su GitHub](https://github.com/elevenlabs/elevenlabs-dx/blob/main/fern/assets/scripts/widget.js) come riferimento.
#### Creare uno strumento client
Per creare il tuo primo strumento client, segui la [guida agli strumenti client](/docs/it/eleven-agents/customization/tools/client-tools).
#### Esempio: creazione dello strumento \`redirectToExternalURL\`
#### Esempio di implementazione
Di seguito trovi un esempio di come gestire lo strumento `redirectToExternalURL` attivato dal widget nel tuo codice JavaScript:
**`index.js`**
```javascript title="index.js"
document.addEventListener("DOMContentLoaded", () => {
const widget = document.querySelector("elevenlabs-convai");
if (widget) {
// Listen for the widget's "call" event to trigger client-side tools
widget.addEventListener("elevenlabs-convai:call", (event) => {
event.detail.config.clientTools = {
// Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
redirectToExternalURL: ({ url }) => {
window.open(url, "_blank", "noopener,noreferrer");
},
};
});
}
});
```
> **Info**
>
> Esplora i nostri [SDK](/docs/it/eleven-api/resources/libraries) type-safe per implementazioni React, Next.js e Python.