Widget aanpassen

Widgets maken directe integratie van ElevenAgents in elke website mogelijk. Je kunt je widget aanpassen via de UI of via onze typeveilige ElevenAgents SDK’s voor volledige controle over styling en gedrag. De SDK-overschrijvingen hebben voorrang op aanpassingen via de UI. Onze widget is multimodaal en kan zowel tekst als audio verwerken.

Modaliteitsconfiguratie

De widget ondersteunt flexibele invoermodi die aansluiten bij je use case. Configureer deze opties in het dashboard onder Kanalen → Widget → Interface.

Beschikbare modi:

• Alleen spraak (standaard): Gebruikers communiceren alleen via spraak.
• Spraak + tekst: Gebruikers kunnen tijdens gesprekken schakelen tussen spraak- en tekstinvoer.
• Chatmodus: Gesprekken beginnen in chatmodus (alleen tekst), zonder spraakmogelijkheden, wanneer ze met een tekstbericht worden gestart.

Lees voor meer informatie over het gebruik van de chatmodus (alleen tekst) via onze SDK’s onze handleiding voor chatmodus.

De widget insluiten

Voeg dit codefragment toe aan de sectie <body> van je website. Plaats het in je hoofdbestand index.html zodat het op de hele site beschikbaar is:

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

Widgetattributen

Deze basiscode voor insluiting toont de widget met de standaardconfiguratie die in het dashboard van de agent is ingesteld. De widget ondersteunt verschillende HTML-attributen voor verdere aanpassing:

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

Runtimeconfiguratie

Je kunt nog twee html-attributen gebruiken om het gedrag van de agent tijdens runtime aan te passen. Je kunt deze twee functies samen, afzonderlijk of helemaal niet gebruiken

Dynamische variabelen

Met dynamische variabelen kun je runtimewaarden invoegen in de berichten, system prompts en tools van je agent.

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

Alle dynamische variabelen die de agent nodig heeft, moeten aan de widget worden doorgegeven.

Overschrijvingen

Met overschrijvingen kun je het gedrag van je agent tijdens runtime volledig aanpassen:

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

Je kunt overschrijvingen voor specifieke velden inschakelen; ze zijn volledig optioneel.

Visuele aanpassing

Pas de weergave, tekstinhoud, taalkeuze en meer van de widget aan.

Geavanceerde implementatie

Client Tools

Met clienttools kun je de functionaliteit van de widget uitbreiden door event listeners toe te voegen. Hierdoor kan de widget bijvoorbeeld de volgende acties uitvoeren:

• De gebruiker naar een specifieke pagina doorsturen
• Een e-mail naar je supportteam sturen
• De gebruiker naar een externe URL doorsturen

Om voorbeelden van deze tools in actie te zien, start je een gesprek met de agent rechtsonder op deze pagina. De broncode is beschikbaar op GitHub als referentie.

Een clienttool maken

Volg de handleiding voor clienttools om je eerste clienttool te maken.

Voorbeeldimplementatie

Hieronder zie je een voorbeeld van hoe je de door de widget geactiveerde tool redirectToExternalURL in je JavaScript-code verwerkt:

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