Hoppa till navigering
DistribueraWebb

Anpassning av widget

Lär dig hur du anpassar widgetens utseende efter ditt varumärke och personanpassar agentens beteende från html.

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

Du kan också hämta en agents widgetkonfiguration och delbara länk från Claude eller en annan MCP-klient via den hostade MCP-servern.

Konfiguration av modalitet

Widgeten har flexibla inmatningslägen som passar ditt användningsfall. Konfigurera dessa alternativ i instrumentpanelen under Kanaler → Widget → Gränssnitt.

Multimodalitet stöds fullt ut i våra klient-SDK:er, läs mer här.

Alternativ för widgetgränssnitt

Tillgängliga lägen:

  • Endast röst (standard): Användare interagerar enbart genom 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 inleds med ett textmeddelande.

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

Widgeten använder som standard läget endast röst. Aktivera reglaget för textinmatning för att tillåta multimodala interaktioner, eller aktivera stöd för läget endast text för helt textbaserade samtal som inleds via text.

Bädda in widgeten

Widgetar kräver för närvarande offentliga agenter med autentisering inaktiverad. Kontrollera att detta är inaktiverat på fliken Avancerat i agentens inställningar.

Lägg till detta kodfragment i webbplatsens <body>-avsnitt. Placera det i din huvudsakliga index.html-fil så att det blir tillgängligt på hela webbplatsen:

Kod för inbäddning av 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>

För bättre säkerhet definierar du tillåtna domäner i agentens Tillåtelselista (finns på fliken Säkerhet). Det begränsar åtkomsten till endast angivna värdar.

Widgetattribut

Den här grundläggande inbäddningskoden visar widgeten med standardkonfigurationen som har definierats i agentens instrumentpanel. 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>

Widgeten renderar markdown i agentsvar. Länkar visas som oformaterad text som standard för att förhindra nätfiske.

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

Körningskonfiguration

Ytterligare två html-attribut kan användas för att anpassa agentens beteende vid körning. De här två funktionerna kan användas tillsammans, var för sig eller inte alls

Dynamiska variabler

Med dynamiska variabler kan du injicera 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 till widgeten.

Läs mer i vår guide till dynamiska variabler .

Åsidosättningar

Åsidosättningar ger dig 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.

Läs mer i vår guide till åsidosättningar.

Visuell anpassning

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

Öppna agenten i instrumentpanelen och gå till fliken Widget för att anpassa utseende, avatar, text, villkor, språkstöd och mer.

Anpassning av widget

Anpassa widgetens färger och former så att de matchar ditt varumärkes identitet.

Widgetens utseende

Rikt innehåll

Rikt innehåll gör att agenten kan svara med interaktiva komponenter tillsammans med sina meddelanden. Konfigurera det i instrumentpanelen under Kanaler → Widget → Rikt innehåll.

Inställningar för rikt innehåll i widgeten

Rikt innehåll visas i textsamtal och i röstsamtal när Realtidstranskription av samtalet är aktiverat under Gränssnitt. Det är bara tillgängligt i den inbäddade widgeten.

Snabbsvar är knappar som användare kan trycka på i stället för att skriva. När en användare trycker på en skickas knappens etikett som användarens nästa meddelande.

Snabbsvar

Föreslagna av agenten

Agenten föreslår upp till tre svar under samtalet, till exempel för att bekräfta ett val eller erbjuda nästa steg.

Svar på första meddelandet

Lägg till upp till tre svar under Svar på första meddelandet för att visa dem tillsammans med agentens första meddelande, så att användare kan starta samtalet med ett tryck. Dra dem för att ändra ordningen.

Dessa svar är fasta: de visas med varje första meddelande och agenten väljer dem inte. De översätts tillsammans med dina andra språkförinställningar.

Så här använder agenten rikt innehåll

Förutom svar på första meddelandet avgör agenten vid varje tur om den ska visa snabbsvar eller en karusell. Ett svar som inte behöver en komponent förblir oformaterad text. Beskriv det i agentens systemprompt för att styra när och hur de visas.

Snabbsvar och karusell är aktiverade som standard för nya agenter. För agenter som skapades innan rikt innehåll fanns tillgängligt aktiverar du dem i widgetinställningarna.

Avancerad implementation

För mer avancerad anpassning bör du använda de typsäkra ElevenAgents SDK:erna med en Next.js-, React- eller Python-applikation.

Klientverktyg

Med klientverktyg kan du utöka widgetens funktioner 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 praktiken startar du ett samtal med agenten längst ned till höger 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.

Konfiguration av klientverktyg

Exempelimplementation

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

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

Utforska våra typsäkra SDK:er för implementationer i React, Next.js och Python.