Vai alla navigazione
DeploymentWeb

Personalizzazione del widget

Scopri come personalizzare l'aspetto del widget in linea con il tuo brand e il comportamento dell'agente da HTML.

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 type-safe per avere il pieno controllo su stile e comportamento. Le impostazioni degli SDK hanno la precedenza sulla personalizzazione dall’interfaccia utente. Il nostro widget è multimodale e può elaborare sia testo sia audio.

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.

Configurazione della modalità

Il widget supporta modalità di input flessibili per adattarsi al tuo caso d’uso. Configura queste opzioni nella dashboard in Canali → Widget → Interfaccia.

La multimodalità è pienamente supportata nei nostri SDK client; scopri di più qui.

Opzioni dell'interfaccia del widget

Modalità disponibili:

  • Solo voce (predefinita): gli utenti interagiscono esclusivamente tramite voce.
  • Voce + testo: gli utenti possono passare dall’input vocale a quello testuale durante le conversazioni.
  • Modalità chat: le conversazioni iniziano in modalità chat (solo testo), senza funzionalità vocali, quando vengono avviate con un messaggio di testo.

Per maggiori informazioni sull’uso della modalità chat (solo testo) tramite i nostri SDK, consulta la nostra guida alla modalità chat.

Per impostazione predefinita, il widget è in modalità solo voce. Abilita l’opzione per l’input di testo per consentire interazioni multimodali oppure abilita il supporto della modalità solo testo per conversazioni interamente testuali avviate tramite testo.

Incorporare il widget

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 <body> del tuo sito web. Inseriscilo nel file index.html principale per renderlo disponibile in tutto il sito:

Codice di incorporamento del widget
<elevenlabs-convai agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"></elevenlabs-convai>
<script
  src="https://unpkg.com/@elevenlabs/convai-widget-embed"
  async
  type="text/javascript"
></script>

Per una maggiore sicurezza, definisci i domini consentiti nell’Allowlist dell’agente (nella scheda Sicurezza). In questo modo limiti l’accesso agli host specificati.

Attributi del widget

Questo codice di incorporamento di base visualizza il widget con la configurazione predefinita definita nella dashboard dell’agente. Il widget supporta vari attributi HTML per ulteriori personalizzazioni:

<elevenlabs-convai
  agent-id="agent_id"              // Required: Your agent ID
  signed-url="signed_url"          // Alternative to agent-id
  server-location="us"             // Optional: "us" or default
  variant="expanded"               // Optional: Widget display mode
  dismissible="true"               // Optional: Allow the user to minimize the widget
></elevenlabs-convai>
<elevenlabs-convai
  avatar-image-url="https://..." // Optional: Custom avatar image
  avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
  avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
></elevenlabs-convai>
<elevenlabs-convai
  action-text="Need assistance?" // Optional: CTA button text
  start-call-text="Begin conversation" // Optional: Start call button
  end-call-text="End call" // Optional: End call button
  expand-text="Open chat" // Optional: Expand widget text
  listening-text="Listening..." // Optional: Listening state
  speaking-text="Assistant speaking" // Optional: Speaking state
></elevenlabs-convai>

Il widget esegue il rendering del Markdown nelle risposte dell’agente. Per evitare il phishing, i link vengono visualizzati come testo normale per impostazione predefinita.

<elevenlabs-convai
  markdown-link-allowed-hosts="example.com"  // Domains where links are clickable (use "*" for all)
  markdown-link-include-www="true"           // Also allow www variants (default: true)
  markdown-link-allow-http="true"            // Allow http:// links (default: true)
  syntax-highlight-theme="dark"              // Code block theme: "dark", "light", or "auto"
></elevenlabs-convai>

Configurazione runtime

Altri due attributi HTML possono essere usati per personalizzare il comportamento dell’agente a runtime. Queste due funzionalità possono essere usate insieme, separatamente o non essere usate affatto.

Variabili dinamiche

Le variabili dinamiche ti consentono di inserire valori runtime nei messaggi, nei system prompt e negli strumenti del tuo agente.

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>

Tutte le variabili dinamiche richieste dall’agente devono essere passate nel widget.

Scopri di più nella nostra guida alle variabili dinamiche.

Override

Gli override consentono di personalizzare completamente il comportamento dell’agente a runtime:

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  override-language="es"
  override-prompt="Custom system prompt for this user"
  override-first-message="Hi! How can I help you today?"
  override-voice-id="axXgspJ2msm3clMCkdW3"
></elevenlabs-convai>

Gli override possono essere abilitati per campi specifici e sono del tutto facoltativi.

Scopri di più nella nostra guida agli override.

Personalizzazione visiva

Personalizza l’aspetto del widget, il contenuto testuale, la selezione della lingua e altro ancora.

Apri il tuo agente nella dashboard e vai alla scheda Widget per personalizzare aspetto, avatar, testo, termini, supporto linguistico e altro ancora.

Personalizzazione del widget

Personalizza i colori e le forme del widget in linea con l’identità del tuo brand.

Aspetto del widget

Contenuti avanzati

I contenuti avanzati consentono all’agente di rispondere con componenti interattivi insieme ai suoi messaggi. Configurali nella dashboard in Canali → Widget → Contenuti avanzati.

Impostazioni dei contenuti avanzati del widget

I contenuti avanzati vengono mostrati nelle conversazioni testuali e in quelle vocali quando Trascrizione in tempo reale della conversazione è abilitata in Interfaccia. Sono disponibili esclusivamente nel widget incorporato.

Le risposte rapide sono pulsanti che gli utenti possono toccare invece di digitare. Quando un utente ne tocca uno, la sua etichetta viene inviata come messaggio successivo dell’utente.

Risposte rapide

Suggerite dall’agente

L’agente suggerisce fino a tre risposte durante la conversazione, ad esempio per confermare una scelta o proporre i passaggi successivi.

Risposte del primo messaggio

Aggiungi fino a tre risposte in Risposte del primo messaggio per mostrarle insieme al primo messaggio dell’agente, così gli utenti possono avviare la conversazione con un tocco. Trascinale per modificarne l’ordine.

Queste risposte sono fisse: compaiono con ogni primo messaggio e l’agente non le sceglie. Vengono tradotte insieme alle altre preimpostazioni linguistiche.

Come l’agente usa i contenuti avanzati

A eccezione delle risposte del primo messaggio, l’agente decide a ogni turno se mostrare risposte rapide o un carosello. Una risposta che non richiede un componente rimane in testo normale. Per definire quando e come vengono visualizzati, descrivilo nel system prompt dell’agente.

Le risposte rapide e il carosello sono attivi per impostazione predefinita per i nuovi agenti. Per gli agenti creati prima della disponibilità dei contenuti avanzati, attivali nelle impostazioni del widget.

Implementazione avanzata

Per una personalizzazione più avanzata, usa gli SDK ElevenAgents type-safe con un’applicazione Next.js, React o Python.

Strumenti client

Gli strumenti client ti consentono 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 come riferimento.

Creare uno strumento client

Per creare il tuo primo strumento client, segui la guida agli strumenti client.

Configurazione dello strumento client

Esempio di implementazione

Di seguito trovi un esempio di come gestire lo strumento redirectToExternalURL attivato dal widget nel tuo codice JavaScript:

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");
        },
      };
    });
  }
});

Esplora i nostri SDK type-safe per implementazioni React, Next.js e Python.