---
title: "Osadzalny widżet głosowy"
description: "Dodaj głosowego agenta AI do dowolnej strony internetowej za pomocą kilku wierszy kodu"
---

Osadzalny widżet głosowy ThunderPhone umożliwia odwiedzającym Twoją witrynę rozmawianie z agentem AI bezpośrednio w przeglądarce. Rozmowa telefoniczna nie jest wymagana — użytkownicy klikają przycisk i rozpoczynają rozmowę głosową w czasie rzeczywistym obsługiwaną przez ThunderPhone.

Widżet jest wyświetlany jako pasek o szklanym wyglądzie, który dostosowuje się do jasnych i ciemnych motywów, z konfigurowalnymi kolorami akcentów i pozycjonowaniem. Jest dystrybuowany jako pakiet npm `@thunderphone/widget` i dostępny również przez CDN dla środowisk bez bundlera.

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

## Wymagania wstępne

Przed osadzeniem widżetu wykonaj te trzy kroki w [Panelu ThunderPhone](https://app.thunderphone.com):

<Steps>
<Step title="Utwórz widżet internetowy">
  Przejdź do sekcji **Widżety internetowe** w panelu i utwórz widżet. Wybierz agenta, którego chcesz udostępnić. Każdy widżet ma własny klucz publiczny (`pk_live_...`), który można bezpiecznie umieścić w kodzie po stronie klienta; agent jest określany na podstawie klucza.
</Step>

<Step title="Skonfiguruj dozwolone domeny">
  W tym samym widżecie dodaj domeny, w których będzie osadzony. Obsługiwane są symbole wieloznaczne (np. `*.example.com`). Lista uniemożliwia działanie widżetu, gdy ktoś skopiuje Twój klucz do innej witryny; nie jest to uwierzytelnianie, ponieważ skrypt poza przeglądarką może wysłać dowolny nagłówek `Origin`. `localhost` nie jest automatycznie dozwolony w środowisku produkcyjnym: dodaj go do listy, aby testować lokalnie z użyciem produkcyjnego API.
</Step>

<Step title="Wybierz nadpisania przeglądarki">
  Jeśli Twoja strona ustawia `language`, `voice` lub `context`, włącz każde z nich w sekcji **Nadpisania przeglądarki**. Nowe widżety nie akceptują żadnych nadpisań, a żądanie sesji zawierające wyłączone ustawienie kończy się błędem `400 override_not_allowed`. Zobacz [Nadpisania przeglądarki](/pl/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  Klucze publikowalne (`pk_live_...`) **nie** są tym samym co tajne tokeny API. Klucze publikowalne są przeznaczone do użycia po stronie klienta i ograniczone do sesji widżetu w dozwolonych domenach. Nigdy nie używaj tajnego tokenu API w kodzie po stronie klienta.
</Warning>

<Note>
  Sesje widżetu domyślnie kończą się po 30 minutach lub wcześniej, jeśli maksymalny czas trwania połączenia agenta jest krótszy. Zmień limit dla każdego klucza za pomocą `max_call_duration_seconds` w [kluczu publicznym](/api-reference/publishable-keys) (do 6 godzin) albo ustaw wartość `null`, aby użyć limitu własnego agenta.
</Note>

---

## Szybki start

Zainstaluj pakiet:

```bash
npm install @thunderphone/widget
```

Dodaj widżet do aplikacji:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

To wszystko. Użytkownicy zobaczą pasek połączenia o szklanym wyglądzie, który jednym kliknięciem łączy ich z agentem AI.

---

## Dostosowywanie

Widżet ma cztery właściwości wyglądu:

| Właściwość | Domyślnie | Opis |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` dla białego szkła, `'dark'` dla ciemnego szkła |
| `primaryColor` | `'#000000'` (jasny) / `'#ffffff'` (ciemny) | Kolor akcentu przycisku rozpoczęcia, przebiegu fali i wskaźnika łączenia |
| `title` | `'Voice assistant'` | Tekst wyświetlany w widżecie |
| `position` | `'bottom-right'` | Róg obszaru widoku: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

Trzy kolejne właściwości dostosowują sesję, a nie wygląd — wszystkie są przekazywane do żądania sesji po rozpoczęciu połączenia. Każda z nich działa tylko wtedy, gdy klucz publikowalny widżetu zezwala na to w sekcji **Nadpisania przeglądarki**; w przeciwnym razie żądanie sesji kończy się błędem `400 override_not_allowed`:

| Właściwość | Opis |
|------|-------------|
| `language` | Nadpisanie języka dla pojedynczej sesji — kod lub ustawienia regionalne, takie jak `en`, `es` lub `fr-FR` |
| `voice` | Nadpisanie głosu dla pojedynczej sesji — nazwa głosu, taka jak `maria` |
| `context` | Faktyczny kontekst strony lub witryny przekazywany agentowi (obcinany po stronie serwera do 12 000 znaków) |

Pełną tabelę właściwości znajdziesz w [dokumentacji komponentu React](/pl/widget/react).

Aby utworzyć w pełni niestandardowy interfejs, użyj [hooka headless](/pl/widget/headless-hook) do zarządzania sesją głosową podczas tworzenia własnego interfejsu. Hook udostępnia poziomy dźwięku w czasie rzeczywistym do tworzenia wizualizacji reagujących na dźwięk.

Każda rozmowa w widżecie jest połączeniem. Jest uwzględniana w [limicie równoczesnych połączeń](/api-reference/introduction#call-limits) organizacji (domyślnie 20 trwających połączeń, wspólny limit dla połączeń telefonicznych i innych) oraz limicie widżetu wynoszącym 25 aktywnych sesji (lub limicie równoczesnych połączeń, jeśli jest wyższy). Po osiągnięciu któregokolwiek z limitów nie można rozpocząć nowej rozmowy, dopóki połączenie się nie zakończy.

---

## Opcje integracji

Wybierz metodę integracji dopasowaną do Twojego stosu technologicznego:

<CardGroup cols={3}>
  <Card title="Komponent React" icon="react" href="/pl/widget/react">
    Gotowy komponent interfejsu z wbudowanymi kontrolkami połączeń i wyświetlaniem statusu. Zaimportuj, przekaż właściwości i gotowe.
  </Card>
  <Card title="Hook bez interfejsu" icon="code" href="/pl/widget/headless-hook">
    Pełna kontrola nad interfejsem. Hook `useThunderPhone` zarządza sesją głosową, podczas gdy tworzysz własny interfejs.
  </Card>
  <Card title="CDN / znacznik skryptu" icon="globe" href="/pl/widget/cdn-script-tag">
    Nie wymaga bundlera. Załaduj widżet za pomocą znacznika skryptu w witrynach statycznych, WordPressie i innych środowiskach bez Reacta.
  </Card>
</CardGroup>

---

## Stylizacja

Widżet zawiera wbudowane jasne i ciemne motywy sterowane właściwością `theme` oraz kolor akcentu sterowany właściwością `primaryColor`. Aby uzyskać bardziej zaawansowaną personalizację, możesz nadpisać niestandardowe właściwości i klasy CSS. Szczegółowe informacje znajdziesz w [przewodniku po stylizacji](/pl/widget/styling).

<Note>
  Potrzebujesz pomocy? Skontaktuj się z nami pod adresem [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>