> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Dostosowywanie widgetu

**Widgety** umożliwiają natychmiastową integrację ElevenAgents z dowolną stroną internetową. Możesz dostosować widget w interfejsie lub skorzystać z naszych bezpiecznych typowo [SDK ElevenAgents](/docs/pl/eleven-api/resources/libraries), 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.

> **Note**
>
> Konfigurację widgetu agenta i link do udostępniania możesz też pobrać z Claude'a lub innego
> klienta MCP przez [hostowany serwer MCP](/docs/pl/eleven-agents/operate/hosted-mcp).

## Konfiguracja trybu

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

> **Note**
>
> Multimodalność jest w pełni obsługiwana przez nasze SDK klienckie. Więcej informacji
> [tutaj](/docs/pl/eleven-api/resources/libraries).

![Opcje interfejsu widgetu](/docs/_fern-img/cf851dd7a29b4bd23f7d36097ebf57c0bfe1b6a7a3b35687ddea20d9920a93c0.webp)

**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](/docs/pl/eleven-agents/guides/chat-mode).

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

> **Note**
>
> 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`**

```html title="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>
```

> **Info**
>
> 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:

#### Podstawowa konfiguracja

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

#### Dostosowanie wyglądu

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

#### Dostosowanie tekstu

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

#### Renderowanie Markdown

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

```html
<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.

```html
<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.

> **Info**
>
> Więcej informacji znajdziesz w [przewodniku po zmiennych dynamicznych](/docs/pl/eleven-agents/customization/personalization/dynamic-variables).

### Zastąpienia

Zastąpienia umożliwiają pełne dostosowanie działania agenta w czasie działania:

```html
<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.

> **Info**
>
> Więcej informacji znajdziesz w [przewodniku po zastąpieniach](/docs/pl/eleven-agents/customization/personalization/overrides).

## Dostosowanie wyglądu

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

#### Aktualizacja w panelu

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](/docs/_fern-img/1f773d01a3c0925a47f11cf57153db23bc8bc03b93efe5d7085919886ae392cf.webp)

#### Aktualizacja przez CLI

#### Pobierz konfigurację agenta

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### Edytuj \`agent_configs/\<agent-name>.json\`

Ustaw pola w `platform_settings.widget`. Na przykład, aby zmienić kolory kuli i tryb opinii:

```json
{
  "platform_settings": {
    "widget": {
      "variant": "full",
      "placement": "bottom-right",
      "avatar": {
        "type": "orb",
        "color_1": "#6DB035",
        "color_2": "#F5CABB"
      },
      "feedback_mode": "during",
      "bg_color": "#ffffff",
      "text_color": "#000000",
      "btn_color": "#000000",
      "btn_text_color": "#ffffff"
    }
  }
}
```

#### Prześlij zmiany

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Aktualizacja przez API

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    platform_settings={
        "widget": {
            "variant": "full",
            "placement": "bottom-right",
            "avatar": {
                "type": "orb",
                "color_1": "#6DB035",
                "color_2": "#F5CABB",
            },
            "feedback_mode": "during",
        },
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  platformSettings: {
    widget: {
      variant: "full",
      placement: "bottom-right",
      avatar: {
        type: "orb",
        color1: "#6DB035",
        color2: "#F5CABB",
      },
      feedbackMode: "during",
    },
  },
});
```

#### Wygląd

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

![Wygląd widgetu](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/0c07c4569f8c5ad3b93933711c268601af411085aa7df1bb8e8ec547a01f2d8e/assets/images/conversational-ai/appearance.gif)

#### Opinie

Zbieraj opinie użytkowników, aby poprawiać działanie agenta. Możesz ich użyć do dostrojenia bazy wiedzy i promptu systemowego agenta.

![Opinie o widgecie](/docs/_fern-img/d7117399e23f06522b3112ff5c5ead23f66d3ea4700c011ff75e5dcd6cce875c.webp)

**Tryby zbierania**

* **Brak**: całkowicie wyłącz zbieranie opinii.
* **W trakcie rozmowy**: zbieraj opinie w czasie rzeczywistym podczas rozmów. Zbierane będą też dodatkowe metadane, takie jak odpowiedź agenta, która wywołała opinię, aby łatwiej wskazać luki.
* **Po rozmowie**: wyświetl pojedynczą prośbę o opinię po zakończeniu rozmowy.

> **Note**
>
> Przy własnych implementacjach SDK wysyłaj opinie programowo przez [API](/docs/pl/eleven-agents/api-reference/conversations/create).

#### Awatar

Skonfiguruj kulę głosową lub dodaj własny awatar.

![Dostosowywanie kuli widgetu](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/7530f28ad124fc4533911eca4a2269ac1df19dffd2b6dab1e8b56d95cc1eb53c/assets/images/conversational-ai/avatar.gif)

**Dostępne opcje**

* **Kula**: wybierz dwa kolory gradientu (np. #6DB035 i #F5CABB).
* **Link/obraz**: użyj własnego obrazu awatara.

#### Wyświetlany tekst

Dostosuj wszystkie wyświetlane elementy tekstowe widgetu, na przykład etykiety przycisków.

![Zawartość tekstowa widgetu](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/4ad66ecae5df29e587afcf6e1898ccb41ca197abdaa2fde3ada4b10d256f8b7c/assets/images/conversational-ai/textcontents.gif)

#### Warunki

Wyświetl własne warunki przed rozpoczęciem rozmowy.

![Konfiguracja warunków](/docs/_fern-img/58dfd0abf92615f85c7314e8baec1bf4dd401cc88a04f1096baf817f05edb39d.webp)

**Dostępne opcje**

* **Treść warunków**: użyj Markdown, aby sformatować tekst zasad.
* **Klucz pamięci lokalnej**: klucz (np. "terms_accepted"), aby nie wyświetlać komunikatu powracającym użytkownikom.

**Użycie**

Warunki są wyświetlane użytkownikom w oknie modalnym przed rozpoczęciem rozmowy:

![Wyświetlanie warunków](/docs/_fern-img/ca7511c60f1f6a29ee8bdd5c40083c73ef701f6cfd7ce1672161d73559a0c9b0.webp)

Warunki możesz zapisać w Markdown, co pozwala:

* Dodawać linki do zewnętrznych zasad
* Formatować tekst za pomocą nagłówków i list
* Dodawać wyróżnienia i style

Więcej pomocy dotyczącej Markdown znajdziesz w [przewodniku CommonMark](https://commonmark.org/help/).

> **Info**
>
> Po akceptacji status jest zapisywany lokalnie, a użytkownik nie zobaczy ponownie tego komunikatu podczas kolejnych
> wizyt.

#### Język

Włącz obsługę wielu języków w widgecie.

![Język widgetu](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/049e871eb0f609b071599e405c3da76351ee4ea38e52400fc416194930c42327/assets/images/conversational-ai/language.gif)

> **Note**
>
> Aby włączyć wybór języka, najpierw musisz [dodać dodatkowe języki](/docs/pl/eleven-agents/customization/voice/customization/language) do swojego agenta.

#### Wyciszanie

Pozwól użytkownikom wyciszać audio w widgecie.

![Przycisk wyciszania widgetu](/docs/_fern-img/e6968e4ba057d98857fb41125bb57f92570ed7c49711ce423add1ea558de5919.webp)

Aby dodać przycisk wyciszania, włącz tę opcję na karcie `interface` w ustawieniach `widgetu`
agenta.

![Przycisk wyciszania widgetu](/docs/_fern-img/7db9df78926f3f3b3db7c286d4efc033356ec9b79cabe20670f65a52a624fae8.webp)

#### Strona do udostępniania

Dostosuj publiczną stronę docelową widgetu (link do udostępniania).

![Strona widgetu do udostępniania](/docs/_fern-img/9d8b23aa816f4b7d727b3c0511ef91d046796bb57b8299382c53b6bcff746c50.webp)

**Dostępne opcje**

* **Opis**: dodaj krótki akapit wyjaśniający cel rozmowy.

## 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](/docs/_fern-img/f6396cd0fb21e6d431ff4b09d609b1ce9b6b88e64960e82ee97027bb28d3d8df.webp)

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

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](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/44cd80eba55869c350416f5265d3fa37097370618fa705796fb082bed89636eb/assets/images/conversational-ai/rich-content-quick-replies.gif)

**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](/docs/pl/eleven-agents/customization/voice/customization/language).

#### Karuzela

Agent wyświetla do pięciu elementów jako przewijane karty, na przykład wyniki wyszukiwania lub rekomendacje produktów.

![Karuzela](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/f0d00c476d5725625f86321983e2231a999f430293f4abc95b4d804c4fabfe22/assets/images/conversational-ai/rich-content-carousel.gif)

**Zawartość karty**

Każda karta ma tytuł, a także może zawierać podtytuł, obraz, opis i do trzech przycisków. Gdy użytkownik naciśnie przycisk na karcie, jego etykieta wraz z tytułem elementu zostanie wysłana jako kolejna wiadomość użytkownika.

**Promptowanie karuzeli**

Karuzela działa tylko wtedy, gdy agent ma rzeczywiste elementy do pokazania. Tworzy karty na podstawie danych zwracanych przez [narzędzie](/docs/pl/eleven-agents/customization/tools) lub udostępnianych przez [bazę wiedzy](/docs/pl/eleven-agents/customization/knowledge-base), i nie wymyśla elementów, cen ani obrazów. Agent bez narzędzia lub bazy wiedzy zwracających elementy rzadko wyświetli karuzelę.

W prompcie powiedz agentowi:

* **Kiedy wyświetlać karuzelę**, na przykład gdy użytkownik chce przeglądać lub porównywać produkty.
* **Co umieścić w każdym polu**, na przykład nazwę produktu jako tytuł, a cenę jako podtytuł.
* **Jakie przyciski dodać i co zrobić po ich naciśnięciu.** Proś tylko o przyciski, których działanie agent może wykonać. Przycisk **Dodaj do koszyka** wymaga narzędzia dodającego produkt do koszyka, inaczej jego naciśnięcie nic nie zrobi.

Dodaj takie instrukcje do promptu systemowego i zastąp nazwy narzędzi w nawiasach własnymi narzędziami:

**`Przykładowy prompt`**

```markdown title="Przykładowy prompt"
# Product carousel

When the user asks to browse, search or compare products, call [your product search tool] and show the results as a carousel.

- Title: the product name
- Subtitle: the price
- Description: a one-sentence summary
- Image: the product image URL from the search results

Give each card "View product" and "Add to cart" buttons. When the user picks "Add to cart" on a card, call [your add to cart tool] with that product.
```

**Rozwiązywanie problemów**

* **Karuzela się nie wyświetla**: sprawdź, czy narzędzie lub baza wiedzy zwróciły elementy, które agent może pokazać, oraz czy prompt określa, kiedy używać karuzeli.
* **Karta nie ma obrazu**: obrazy na kartach są wyświetlane tylko wtedy, gdy adres URL obrazu pojawił się wcześniej w rozmowie, na przykład w wyniku narzędzia, i jest udostępniany przez HTTPS. Upewnij się, że narzędzie zwraca adresy URL obrazów.

### 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](/docs/pl/eleven-agents/best-practices/prompting-guide) 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

> **Note**
>
> Aby uzyskać bardziej zaawansowane możliwości dostosowania, użyj bezpiecznych typowo [SDK ElevenAgents SDKs](/docs/pl/eleven-api/resources/libraries) 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](https://github.com/elevenlabs/elevenlabs-dx/blob/main/fern/assets/scripts/widget.js).

#### Tworzenie narzędzia klienckiego

Aby utworzyć pierwsze narzędzie klienckie, skorzystaj z [przewodnika po narzędziach klienckich](/docs/pl/eleven-agents/customization/tools/client-tools).

#### Przykład: tworzenie narzędzia \`redirectToExternalURL\`

![Konfiguracja narzędzia klienckiego](/docs/_fern-img/d800b8c60cba2ab0a1d0aaaecc0652a678998a4161adaf10d83df51b928a7734.webp)

#### Przykładowa implementacja

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

**`index.js`**

```javascript title="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");
        },
      };
    });
  }
});
```

> **Info**
>
> Poznaj nasze bezpieczne typowo [SDK](/docs/pl/eleven-api/resources/libraries) z implementacjami dla React, Next.js i Pythona.