---
title: "Vložení webového widgetu"
description: "Přidejte na svůj marketingový nebo podpůrný web hlasového agenta pomocí jediného tagu skriptu — návštěvníci s ním mohou mluvit přímo z prohlížeče, bez nutnosti telefonního čísla."
---

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

<Note>
  To vše můžete provést bez cURL: stránka **Webové widgety** na 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žívat relaci 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 pomocí
      [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">
    Uveďte každý název hostitele, který bude widget vkládat. Prohlížeče odesílají
    původ stránky s každým požadavkem na relaci, takže seznam zabrání tomu, aby váš klíč
    fungoval, když jej někdo zkopíruje na jiný web. Nejde o
    ověřování: skript mimo prohlížeč může odeslat libovolnou hlavičku `Origin`.
    `localhost` není v produkci automaticky povolen; chcete-li testovat lokálně
    proti produkčnímu API, přidejte `localhost` do seznamu.
  </Step>
  <Step title="Zvolte přepsání nastavení prohlížečem">
    Rozhodněte, která nastavení relace může vaše stránka odesílat. Nové klíče
    nepřijímají žádná; viz [Přepsání nastavení prohlížečem](#browser-overrides).
  </Step>
</Steps>

## Vytvořte veřejný klíč

<CodeGroup>
```bash Static agent
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"],
    "allowed_overrides": ["context"]
  }'
```

```bash Dynamic via webhook
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_...`. **Veřejné
klíče jsou záměrně veřejné** — můžete je bezpečně zahrnout do front-endového balíčku.
Všechna pole najdete v [referenci veřejný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 **ne** holé
  doméně. Holé zástupné znaky jako `*` nebo `*.*` jsou odmítnuty.
</Warning>

## Vložte widget na svůj web

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

<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 s prvkem zvuku během hovoru.

## Přepsání z prohlížeče

Widget může ze stránky odesílat čtyři nastavení pro jednotlivé relace:

| Nastavení | Vlastnost widgetu | Co mění |
|---------|-------------|-----------------|
| `context` | `context` | Text ze stránky připojený k promptu agenta jako referenční informace |
| `variables` | žádná (pouze nezpracovaný `POST /v1/widget/session`) | Hodnoty pro zástupné symboly `{{variable}}` v promptu |
| `voice` | `voice` | Hlas agenta pro tuto relaci |
| `language` | `language` | Jazyk, ve kterém relace začíná |

Váš publikovatelný klíč je veřejný, takže kdokoli, kdo jej má, může tato
nastavení odeslat, včetně skriptu, který se vydává za vaši doménu. Každé z nich je
proto vypnuté, dokud je u klíče nepovolíte: zaškrtněte je v části **Přepsání
v prohlížeči**, když widget vytváříte nebo upravujete v dashboardu, nebo nastavte
`allowed_overrides` prostřednictvím
[API publikovatelných klíčů](/api-reference/publishable-keys). Povolte pouze to,
co vaše stránka skutečně odesílá.

Požadavek na relaci, který obsahuje nastavení, jež klíč nepovoluje, selže s `400` a uvede jeho název:

```json
{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}
```

Kontrola se uplatňuje v obou režimech. V režimu webhooku se povolené nastavení také předá vašemu webhooku `web.incoming` (`context` dorazí jako `website_context`). Klíče vytvořené před zavedením tohoto nastavení povolují všechna čtyři, takže stávající vložení nadále fungují; vypněte to, co nepoužíváte.

Hodnota `context` widgetu je zkrácena 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). Agent dostane pokyn, aby ji považoval za obsah stránky, nikoli za instrukce.

## Webhooky v režimu widgetu

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

```json
{
  "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 které stránce se nachází) a během nasazení měnit agenty.

## 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í a
účtování jako telefonní hovory. Filtrujte podle `direction` a vytvořte
si řídicí panel pouze pro widget.

---

## Další kroky

<CardGroup cols={2}>
  <Card title="Referenční dokumentace SDK widgetu" icon="window-maximize" href="/cs/widget/overview">
    Podrobnosti o integraci React / hook / CDN.
  </Card>
  <Card title="Dynamická konfigurace pro každý hovor" 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>