> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Osadzalny widżet głosowy

> 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="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="ThunderPhone widget in light and dark themes with various accent colors" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## Wymagania wstępne

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

<Steps>
  <Step title="Utwórz publikowalny klucz API">
    Przejdź do **Programiści** w ustawieniach panelu i utwórz publikowalny klucz. Klucze publikowalne zaczynają się od `pk_live_` i można je bezpiecznie umieszczać w kodzie po stronie klienta.
  </Step>

  <Step title="Skonfiguruj dozwolone domeny">
    W tych samych ustawieniach Programiści dodaj domeny, w których widżet będzie osadzony. `localhost` jest zawsze dozwolony podczas programowania. Obsługiwane są symbole wieloznaczne, np. `*.example.com`.
  </Step>

  <Step title="Utwórz widżet internetowy">
    Przejdź do **Widżety internetowe** w panelu i utwórz widżet. Wybierz agenta, którego chcesz udostępnić, oraz publikowalny klucz do użycia. Agent jest rozpoznawany automatycznie na podstawie konfiguracji publikowalnego klucza.
  </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>

***

## Szybki start

Zainstaluj pakiet:

```bash theme={null}
npm install @thunderphone/widget
```

Dodaj widżet do aplikacji:

```tsx theme={null}
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) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

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

Trzy dodatkowe właściwości dostosowują sesję, a nie wygląd — wszystkie są przekazywane do żądania sesji po rozpoczęciu połączenia:

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

***

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