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

# Osadź widżet internetowy

> Umieść agenta głosowego na swojej stronie marketingowej lub wsparcia — bez numeru telefonu.

Widżet internetowy zapewnia odwiedzającym Twoją witrynę rozmowę typu kliknij, aby porozmawiać
z agentem AI, korzystając z mikrofonu przeglądarki. To osobny
zestaw SDK JavaScript / React z własną [dokumentacją referencyjną SDK](/pl/widget/overview)
— ten przewodnik skupia się na konfiguracji po stronie ThunderPhone wymaganej przez widżet.

<Note>
  Możesz zrobić to wszystko bez cURL: strona panelu **Widżety internetowe**
  (`/dashboard/web-widgets`) tworzy widżet, ustawia jego tryb
  i agenta, zarządza dozwolonymi domenami oraz przekazuje fragment kodu do osadzenia.
</Note>

## Wymagania wstępne

<Steps>
  <Step title="Utwórz agenta">
    Agent, którego prompt i głos będą używane podczas sesji widżetu. Ustaw
    `widget_enabled: true` (wartość domyślna).
  </Step>

  <Step title="Wybierz tryb routingu">
    * `mode="agent"` — jeden statyczny agent na klucz. Najprostsze rozwiązanie.
    * `mode="webhook"` — Twój serwer wybiera agenta dla każdego odwiedzającego za pomocą
      [webhooka `web.incoming`](/pl/webhooks/call-incoming). Użyj tego w przypadku
      zalogowanych użytkowników, testów A/B lub routingu zależnego od strony.
  </Step>

  <Step title="Wymień dozwolone domeny">
    Klucze publiczne są ograniczone do originów. Musisz podać każdą nazwę hosta,
    która będzie osadzać widżet. `localhost` / `127.0.0.1` są zawsze
    dozwolone podczas programowania lokalnego.
  </Step>
</Steps>

## Utwórz klucz publiczny

<CodeGroup>
  ```bash Static agent theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Marketing site (prod)",
      "mode":            "agent",
      "agent_id":        12,
      "allowed_domains": ["example.com", "*.example.com"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Support (dynamic)",
      "mode":            "webhook",
      "webhook_url":     "https://example.com/thunderphone/widget-hook",
      "allowed_domains": ["support.example.com"]
    }'
  ```
</CodeGroup>

Odpowiedź zawiera `key` zaczynający się od `pk_live_...`. **Klucze publiczne
są publiczne z założenia** — można je bezpiecznie umieścić w pakiecie front-endu.
Wszystkie pola znajdziesz w [dokumentacji referencyjnej kluczy publicznych](/api-reference/publishable-keys).

<Warning>
  `allowed_domains` musi zawierać co najmniej jeden wpis. `*.example.com`
  dopasowuje subdomeny (np. `api.example.com`), ale **nie** domenę
  główną. Ogólne symbole wieloznaczne, takie jak `*` lub `*.*`, są odrzucane.
</Warning>

## Dodaj widżet do swojej witryny

Trzy opcje integracji opisano w
[dokumentacji SDK widżetu](/pl/widget/overview):

<CardGroup cols={3}>
  <Card title="Komponent React" icon="react" href="/pl/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="Hook headless" icon="circle-nodes" href="/pl/widget/headless-hook">
    `useThunderPhone()` dla niestandardowych interfejsów użytkownika.
  </Card>

  <Card title="Tag skryptu CDN" icon="code" href="/pl/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` dla witryn bez bundlera.
  </Card>
</CardGroup>

Wszystkie trzy akceptują ten sam `publishableKey` i renderują przycisk mikrofonu
oraz element audio podczas połączenia.

Pole `context` widżetu jest obcinane do 12 000 znaków (około 3400
tokenów typowego tekstu angielskiego) i jest uwzględniane w
[dopłacie za rozmiar promptu](/pl/guides/billing-and-topups).

## Webhooki w trybie widżetu

Gdy `mode="webhook"`, ThunderPhone wywołuje Twój `webhook_url` przy każdym
rozpoczęciu sesji z ładunkiem `web.incoming`. Zwróć konfigurację agenta,
którą chcesz uruchomić dla tego odwiedzającego — stosuje ona ten sam
[schemat odpowiedzi](/pl/webhooks/call-incoming) co połączenia
telefoniczne:

```json theme={null}
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

Możesz włączyć do promptu kontekst z własnej sesji (który klient przegląda witrynę,
na której stronie się znajduje) oraz zmieniać agentów dla poszczególnych wdrożeń.

## Monitoruj sesje

Sesje widżetu pojawiają się w
[`GET /v1/calls`](/api-reference/calls#list-calls) z
`direction="widget"` — z tym samym transkryptem, nagraniem, oceną i
rozliczeniem co połączenia telefoniczne. Filtruj według `direction`, aby utworzyć panel tylko dla widżetu.

***

## Kolejne kroki

<CardGroup cols={2}>
  <Card title="Dokumentacja SDK widżetu" icon="window-maximize" href="/pl/widget/overview">
    Szczegóły integracji React / hook / CDN.
  </Card>

  <Card title="Dynamiczna konfiguracja dla każdego połączenia" icon="bolt" href="/pl/guides/dynamic-call-config">
    Zaimplementuj kompleksowo przepływ `mode="webhook"`.
  </Card>

  <Card title="Dokumentacja kluczy publikowalnych" icon="key" href="/api-reference/publishable-keys">
    Każde pole zasobu klucza.
  </Card>

  <Card title="API sesji mikrofonu" icon="microphone" href="/api-reference/mic-sessions">
    Pomiń widżet; steruj LiveKit bezpośrednio, aby tworzyć niestandardowe interfejsy użytkownika.
  </Card>
</CardGroup>