Anpassning av widget

Widgetar gör det enkelt att direkt integrera ElevenAgents på vilken webbplats som helst. Du kan anpassa widgeten antingen via gränssnittet eller via våra typsäkra ElevenAgents SDK:er för full kontroll över stil och beteende. SDK-åsidosättningar har företräde framför anpassningar i gränssnittet. Vår widget är multimodal och kan bearbeta både text och ljud.

Konfiguration av modalitet

Widgeten stöder flexibla inmatningslägen som passar ditt användningsområde. Konfigurera dessa alternativ i dashboarden under Kanaler → Widget → Gränssnitt.

Tillgängliga lägen:

• Endast röst (standard): Användare interagerar enbart via tal.
• Röst + text: Användare kan växla mellan röst- och textinmatning under samtal.
• Chattläge: Samtal startar i chattläge (endast text) utan röstfunktioner när de initieras med ett textmeddelande.

Mer information om hur du använder chattläge (endast text) via våra SDK:er finns i vår guide för chattläge.

Bädda in widgeten

Lägg till det här kodavsnittet i webbplatsens <body>-sektion. Placera det i huvudfilen index.html så att det är tillgängligt på hela webbplatsen:

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

Widgetattribut

Den här grundläggande inbäddningskoden visar widgeten med standardkonfigurationen som har definierats i agentens dashboard. Widgeten har flera HTML-attribut för ytterligare anpassning:

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

Konfiguration vid körning

Ytterligare två HTML-attribut kan användas för att anpassa agentens beteende vid körning. Dessa två funktioner kan användas tillsammans, var för sig eller inte alls.

Dynamiska variabler

Med dynamiska variabler kan du infoga värden vid körning i agentens meddelanden, systemprompter och verktyg.

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

Alla dynamiska variabler som agenten behöver måste skickas med i widgeten.

Åsidosättningar

Åsidosättningar ger fullständig anpassning av agentens beteende vid körning:

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

Åsidosättningar kan aktiveras för specifika fält och är helt valfria.

Visuell anpassning

Anpassa widgetens utseende, textinnehåll, språkval och mer.

Avancerad implementering

Klientverktyg

Klientverktyg låter dig utöka widgetens funktionalitet genom att lägga till händelselyssnare. Det gör att widgeten kan utföra åtgärder som:

• Omdirigera användaren till en specifik sida
• Skicka ett e-postmeddelande till ditt supportteam
• Omdirigera användaren till en extern URL

Om du vill se exempel på dessa verktyg i användning startar du ett samtal med agenten i det nedre högra hörnet på den här sidan. Källkoden finns på GitHub som referens.

Skapa ett klientverktyg

Följ guiden för klientverktyg för att skapa ditt första klientverktyg.

Exempelimplementation

Nedan följer ett exempel på hur du hanterar verktyget redirectToExternalURL som utlöses av widgeten i din JavaScript-kod:

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