Dostosowanie widżetu

Widgety pozwalają od razu zintegrować ElevenAgents z dowolną stroną. Możesz dostosować widget w interfejsie lub użyć naszych bezpiecznych typowo SDK ElevenAgents, by w pełni kontrolować styl i działanie. Ustawienia SDK mają pierwszeństwo przed dostosowaniem w interfejsie. Nasz widget jest multimodalny i obsługuje tekst oraz audio.

Konfiguracja trybu

Widget obsługuje elastyczne tryby wprowadzania danych, dopasowane do twojego zastosowania. Skonfigurujesz je w panelu: Channels → Widget → Interface.

Dostępne tryby:

• Tylko głos (domyślnie): użytkownicy komunikują się wyłącznie głosowo.
• Głos + tekst: użytkownicy mogą przełączać się między głosem a tekstem podczas rozmowy.
• Tryb czatu: rozmowy rozpoczęte wiadomością tekstową działają w trybie czatu (tylko tekst), bez obsługi głosu.

Więcej informacji o korzystaniu z trybu czatu (tylko tekst) przez nasze SDK znajdziesz w przewodniku po trybie czatu.

Osadzanie widgetu

Dodaj ten fragment kodu do sekcji <body> swojej strony. Aby był dostępny w całej witrynie, umieść go w głównym pliku index.html:

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

Atrybuty widgetu

Ten podstawowy kod osadzania wyświetli widget z domyślną konfiguracją ustawioną w panelu agenta. Widget obsługuje różne atrybuty HTML, które pozwalają na dalsze dostosowanie:

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

Konfiguracja w czasie działania

Dwóch dodatkowych atrybutów HTML możesz użyć, by dostosować działanie agenta w czasie działania. Te funkcje można łączyć, używać osobno lub wcale.

Zmienne dynamiczne

Zmienne dynamiczne pozwalają wstawiać wartości z czasu działania do wiadomości agenta, promptów systemowych i narzędzi.

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

W widżecie musisz przekazać wszystkie wymagane przez agenta zmienne dynamiczne.

Zastąpienia

Zastąpienia pozwalają w pełni dostosować działanie agenta w czasie działania:

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

Zastąpienia można włączyć dla wybranych pól i są całkowicie opcjonalne.

Dostosowanie wyglądu

Dostosuj wygląd widgetu, treść tekstów, wybór języka i inne elementy.

Zaawansowana implementacja

Narzędzia klienckie

Narzędzia klienckie pozwalają rozszerzyć funkcje widgetu przez dodanie nasłuchiwania zdarzeń. Dzięki temu widget może wykonywać takie działania jak:

• Przekierowanie użytkownika na konkretną stronę
• Wysłanie e-maila do zespołu wsparcia
• Przekierowanie użytkownika na zewnętrzny URL

Aby zobaczyć te narzędzia w działaniu, rozpocznij rozmowę z agentem w prawym dolnym rogu tej strony. Dla odniesienia kod źródłowy jest dostępny na GitHubie.

Tworzenie narzędzia klienckiego

Aby utworzyć pierwsze narzędzie klienckie, skorzystaj z przewodnika po narzędziach klienckich.

Przykładowa implementacja

Poniżej znajdziesz przykład obsługi narzędzia redirectToExternalURL wywołanego przez widget w kodzie 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");
        },
      };
    });
  }
});