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

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.

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.

Incorporare il widget

Aggiungi questo snippet di codice alla sezione <body> del tuo sito web. Per renderlo disponibile in tutto il sito, inseriscilo nel file index.html principale:

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

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:

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

<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

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.

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

Override

Gli override permettono di personalizzare completamente il comportamento del tuo 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>

Puoi abilitare gli override per campi specifici e sono del tutto facoltativi.

Personalizzazione visiva

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

Implementazione avanzata

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 come riferimento.

Creare uno strumento client

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

Esempio di implementazione

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

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