Przejdź do nawigacji
WdrażanieWeb

Dostosowywanie widgetu

Dowiedz się, jak dopasować wygląd widgetu do swojej marki i personalizować działanie agenta z poziomu HTML.

Widgety umożliwiają natychmiastową integrację ElevenAgents z dowolną stroną internetową. Możesz dostosować widget w interfejsie lub skorzystać z naszych bezpiecznych typowo SDK ElevenAgents, aby w pełni kontrolować jego wygląd i działanie. Ustawienia SDK mają pierwszeństwo przed dostosowaniami w interfejsie. Nasz widget jest multimodalny i obsługuje zarówno tekst, jak i audio.

Konfigurację widgetu agenta i link do udostępniania możesz też pobrać z Claude’a lub innego klienta MCP przez hostowany serwer MCP.

Konfiguracja trybu

Widget obsługuje elastyczne tryby wprowadzania danych, które dopasujesz do swojego zastosowania. Skonfigurujesz je w panelu: Channels → Widget → Interface.

Multimodalność jest w pełni obsługiwana przez nasze SDK klienckie. Więcej informacji tutaj.

Opcje interfejsu widgetu

Dostępne tryby:

  • Tylko głos (domyślnie): użytkownicy komunikują się wyłącznie głosowo.
  • Głos + tekst: użytkownicy mogą podczas rozmowy przełączać się między głosem a tekstem.
  • 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.

Widget domyślnie działa w trybie tylko głosowym. Włącz przełącznik wprowadzania tekstu, aby umożliwić interakcje multimodalne, lub obsługę trybu tylko tekstowego dla rozmów rozpoczętych tekstem.

Osadzanie widgetu

Widgety obecnie wymagają publicznych agentów z wyłączonym uwierzytelnianiem. Upewnij się, że jest ono wyłączone na karcie Advanced w ustawieniach agenta.

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:

Kod osadzający 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>

Dla większego bezpieczeństwa określ dozwolone domeny na liście Allowlist agenta (na karcie Security). Ograniczy to dostęp wyłącznie do wskazanych hostów.

Atrybuty widgetu

Ten podstawowy kod osadzający wyświetli widget z domyślną konfiguracją określoną 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>

Widget renderuje Markdown w odpowiedziach agenta. Linki są domyślnie wyświetlane jako zwykły tekst, aby zapobiegać phishingowi.

<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

Za pomocą dwóch dodatkowych atrybutów HTML możesz dostosować działanie agenta w czasie działania. Możesz używać obu funkcji razem, 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 widgecie musisz przekazać wszystkie zmienne dynamiczne wymagane przez agenta.

Więcej informacji znajdziesz w przewodniku po zmiennych dynamicznych.

Zastąpienia

Zastąpienia umożliwiają pełne dostosowanie działania 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.

Więcej informacji znajdziesz w przewodniku po zastąpieniach.

Dostosowanie wyglądu

Dostosuj wygląd widgetu, wyświetlany tekst, wybór języka i inne elementy.

Otwórz agenta w panelu i przejdź do karty Widget, aby dostosować wygląd, awatar, tekst, warunki, obsługiwane języki i inne elementy.

Dostosowywanie widgetu

Dostosuj kolory i kształty widgetu do identyfikacji swojej marki.

Wygląd widgetu

Bogata treść

Bogata treść pozwala agentowi odpowiadać interaktywnymi komponentami obok wiadomości. Skonfigurujesz ją w panelu: Channels → Widget → Rich content.

Ustawienia bogatej treści widgetu

Bogata treść jest widoczna w rozmowach tekstowych oraz w rozmowach głosowych, gdy w sekcji Interface włączono opcję Realtime transcript of the conversation. Jest dostępna tylko w osadzonym widgecie.

Szybkie odpowiedzi to przyciski, które użytkownicy mogą nacisnąć zamiast pisać. Po naciśnięciu ich etykieta jest wysyłana jako kolejna wiadomość użytkownika.

Szybkie odpowiedzi

Sugerowane przez agenta

Agent sugeruje do trzech odpowiedzi podczas rozmowy, na przykład aby potwierdzić wybór lub zaproponować kolejne kroki.

Odpowiedzi do pierwszej wiadomości

Dodaj maksymalnie trzy odpowiedzi w sekcji First message replies, aby wyświetlać je przy pierwszej wiadomości agenta i pozwolić użytkownikom rozpocząć rozmowę jednym kliknięciem. Przeciągaj je, aby zmienić kolejność.

Te odpowiedzi są stałe: pojawiają się przy każdej pierwszej wiadomości, a agent ich nie wybiera. Są tłumaczone wraz z innymi ustawieniami językowymi.

Jak agent korzysta z bogatej treści

Poza odpowiedziami do pierwszej wiadomości agent w każdej turze decyduje, czy wyświetlić szybkie odpowiedzi, czy karuzelę. Odpowiedź, która nie wymaga komponentu, pozostaje zwykłym tekstem. Aby określić, kiedy i jak się pojawiają, opisz to w prompcie systemowym agenta.

Szybkie odpowiedzi i karuzela są domyślnie włączone dla nowych agentów. W przypadku agentów utworzonych przed udostępnieniem bogatej treści włącz je w ustawieniach widgetu.

Zaawansowana implementacja

Aby uzyskać bardziej zaawansowane możliwości dostosowania, użyj bezpiecznych typowo SDK ElevenAgents SDKs z aplikacją Next.js, React lub Python.

Narzędzia klienckie

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

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

Aby zobaczyć przykłady działania tych narzędzi, 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.

Konfiguracja narzędzia klienckiego

Przykładowa implementacja

Poniżej znajduje się przykład obsługi narzędzia redirectToExternalURL uruchamianego przez widget w kodzie JavaScript:

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

Poznaj nasze bezpieczne typowo SDK z implementacjami dla React, Next.js i Pythona.