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

# Vložení webového widgetu

> Přidejte na svůj marketingový web nebo web podpory hlasového agenta — telefonní číslo není potřeba.

Webový widget umožňuje návštěvníkům vašeho webu zahájit konverzaci s hlasovým agentem s AI kliknutím a pomocí mikrofonu v prohlížeči. Jde o samostatné JavaScriptové / React SDK s vlastní [referencí SDK](/cs/widget/overview) — tento průvodce se zaměřuje na nastavení na straně ThunderPhone, které widget potřebuje.

<Note>
  Vše můžete provést bez cURL: stránka **Webové widgety** v dashboardu
  (`/dashboard/web-widgets`) vytvoří widget, nastaví jeho režim
  a agenta, spravuje povolené domény a poskytne vám kód pro vložení.
</Note>

## Předpoklady

<Steps>
  <Step title="Vytvořte agenta">
    Agent, jehož prompt a hlas budou použity během relace widgetu. Nastavte
    `widget_enabled: true` (výchozí hodnota).
  </Step>

  <Step title="Rozhodněte o režimu směrování">
    * `mode="agent"` — jeden statický agent pro každý klíč. Nejjednodušší možnost.
    * `mode="webhook"` — váš server vybere agenta pro každého návštěvníka prostřednictvím
      [webhooku `web.incoming`](/cs/webhooks/call-incoming). Použijte pro
      přihlášené uživatele, A/B testy nebo směrování podle stránky.
  </Step>

  <Step title="Uveďte povolené domény">
    Publikovatelné klíče jsou omezené na origin. Musíte uvést každý název hostitele,
    který bude widget vkládat. Během lokálního vývoje jsou vždy povoleny
    `localhost` / `127.0.0.1`.
  </Step>
</Steps>

## Vytvořte publikovatelný klíč

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

Odpověď obsahuje `key` začínající na `pk_live_...`. **Publikovatelné
klíče jsou záměrně veřejné** — můžete je bezpečně zahrnout do balíčku front-endu.
Všechna pole najdete v [referenci publikovatelných klíčů](/api-reference/publishable-keys).

<Warning>
  `allowed_domains` musí obsahovat alespoň jednu položku. `*.example.com`
  odpovídá subdoménám (např. `api.example.com`), ale **nikoli** samotné
  doméně. Samostatné zástupné znaky jako `*` nebo `*.*` jsou odmítnuty.
</Warning>

## Vložte widget na svůj web

V [dokumentaci SDK widgetu](/cs/widget/overview) jsou popsány tři možnosti
integrace:

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

  <Card title="Headless hook" icon="circle-nodes" href="/cs/widget/headless-hook">
    `useThunderPhone()` pro vlastní uživatelská rozhraní.
  </Card>

  <Card title="Značka skriptu CDN" icon="code" href="/cs/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` pro weby bez bundleru.
  </Card>
</CardGroup>

Všechny tři přijímají stejný `publishableKey` a vykreslují tlačítko mikrofonu
spolu se zvukovým prvkem během hovoru.

`context` widgetu je zkrácen na 12 000 znaků (přibližně 3 400
tokenů běžného anglického textu) a započítává se do
[příplatku za velikost promptu](/cs/guides/billing-and-topups).

## Webhooky v režimu widgetu

Když je nastaveno `mode="webhook"`, ThunderPhone při každém zahájení
relace zavolá vaše `webhook_url` s daty `web.incoming`. Vraťte konfiguraci
agenta, kterou chcete pro daného návštěvníka použít — řídí se stejným
[schématem odpovědi](/cs/webhooks/call-incoming) jako telefonní
hovory:

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

Do promptu můžete přidat kontext z vlastní relace (který zákazník prochází web,
na jaké stránce se nachází) a měnit agenty podle jednotlivých nasazení.

## Sledování relací

Relace widgetu se zobrazují v
[`GET /v1/calls`](/api-reference/calls#list-calls) s
`direction="widget"` — mají stejný přepis, nahrávku, hodnocení i
účtování jako telefonní hovory. Filtrujte podle `direction` a vytvořte si panel pouze pro widget.

***

## Další kroky

<CardGroup cols={2}>
  <Card title="Referenční dokumentace SDK widgetu" icon="window-maximize" href="/cs/widget/overview">
    Podrobnosti integrace React / hook / CDN.
  </Card>

  <Card title="Dynamická konfigurace pro jednotlivé hovory" icon="bolt" href="/cs/guides/dynamic-call-config">
    Implementujte tok `mode="webhook"` od začátku do konce.
  </Card>

  <Card title="Referenční dokumentace publikovatelných klíčů" icon="key" href="/api-reference/publishable-keys">
    Každé pole prostředku klíče.
  </Card>

  <Card title="API relací mikrofonu" icon="microphone" href="/api-reference/mic-sessions">
    Přeskočte widget; pro vlastní uživatelská rozhraní ovládejte LiveKit přímo.
  </Card>
</CardGroup>