---
title: "Vložitelný hlasový widget"
description: "Přidejte hlasového AI agenta na libovolný web pomocí několika řádků kódu"
---

Vložitelný hlasový widget ThunderPhone umožňuje návštěvníkům vašeho webu mluvit s AI agentem přímo z prohlížeče. Není potřeba žádný telefonní hovor – uživatelé kliknou na tlačítko a zahájí hlasovou konverzaci v reálném čase využívající ThunderPhone.

Widget se zobrazuje jako skleněná lišta, která se přizpůsobí světlým a tmavým motivům, s přizpůsobitelnými barvami zvýraznění a umístěním. Je distribuován jako balíček npm `@thunderphone/widget` a pro prostředí bez bundleru je k dispozici také prostřednictvím CDN.

<Frame>
  <img src="/images/widget-showcase.png" alt="Widget ThunderPhone ve světlém a tmavém motivu s různými barvami zvýraznění" />
</Frame>

## Předpoklady

Před vložením widgetu dokončete tyto tři kroky v [Dashboardu ThunderPhone](https://app.thunderphone.com):

<Steps>
<Step title="Vytvořte webový widget">
  V dashboardu přejděte do sekce **Webové widgety** a vytvořte widget. Vyberte agenta, kterého chcete zpřístupnit. Každý widget má vlastní publikovatelný klíč (`pk_live_...`), který lze bezpečně zahrnout do kódu na straně klienta; agent se určí podle klíče.
</Step>

<Step title="Nakonfigurujte povolené domény">
  Do stejného widgetu přidejte domény, na kterých bude vložen. Zástupné znaky jsou podporovány (např. `*.example.com`). Seznam brání tomu, aby widget fungoval, když někdo zkopíruje váš klíč na jiný web; nejde o ověřování, protože skript mimo prohlížeč může odeslat libovolnou hlavičku `Origin`. `localhost` není v produkci povolen automaticky: pro místní testování vůči produkčnímu API jej přidejte do seznamu.
</Step>

<Step title="Zvolte přepsání nastavení prohlížeče">
  Pokud vaše stránka nastavuje `language`, `voice` nebo `context`, zapněte každé z nich v části **Přepsání nastavení prohlížeče**. Nové widgety nepovolují žádné z nich a požadavek relace obsahující vypnuté nastavení selže s `400 override_not_allowed`. Viz [Přepsání nastavení prohlížeče](/cs/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  Veřejně použitelné klíče (`pk_live_...`) **nejsou** stejné jako vaše tajné tokeny API. Veřejně použitelné klíče jsou určeny pro použití na straně klienta a jsou omezeny na relace widgetu na vašich povolených doménách. Tajný token API nikdy nepoužívejte v kódu na straně klienta.
</Warning>

<Note>
  Relace widgetu ve výchozím nastavení končí po 30 minutách, případně dříve, pokud je vlastní maximální délka hovoru agenta kratší. Limit pro každý klíč změňte pomocí `max_call_duration_seconds` u [publikovatelného klíče](/api-reference/publishable-keys) (až 6 hodin), nebo jej nastavte na `null`, aby se použil vlastní limit agenta.
</Note>

---

## Rychlý start

Nainstalujte balíček:

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

Vložte widget do aplikace:

```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 je vše. Uživatelé uvidí skleněnou lištu pro volání, která je jedním kliknutím spojí s vaším AI agentem.

---

## Přizpůsobení

Widget má čtyři vlastnosti vzhledu:

| Vlastnost | Výchozí hodnota | Popis |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` pro bílé sklo, `'dark'` pro tmavé sklo |
| `primaryColor` | `'#000000'` (světlý) / `'#ffffff'` (tmavý) | Barva zvýraznění pro tlačítko spuštění, průběh zvukové vlny a indikátor připojování |
| `title` | `'Voice assistant'` | Text zobrazený ve widgetu |
| `position` | `'bottom-right'` | Roh zobrazovací oblasti: `'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>

Další tři vlastnosti upravují relaci, nikoli vzhled – všechny se při zahájení hovoru předávají v požadavku na relaci. Každá funguje pouze tehdy, když ji veřejný klíč widgetu povoluje v části **Přepsání v prohlížeči**; jinak požadavek na relaci selže s chybou `400 override_not_allowed`:

| Vlastnost | Popis |
|------|-------------|
| `language` | Přepsání jazyka pro jednotlivou relaci – kód nebo národní prostředí, například `en`, `es` nebo `fr-FR` |
| `voice` | Přepsání hlasu pro jednotlivou relaci – název hlasu, například `maria` |
| `context` | Faktický kontext stránky nebo webu předaný agentovi (na straně serveru zkrácený na 12 000 znaků) |

Úplnou tabulku vlastností naleznete v [referenci komponenty React](/cs/widget/react).

Pro zcela vlastní uživatelské rozhraní použijte [headless hook](/cs/widget/headless-hook) ke správě hlasové relace při vytváření vlastního rozhraní. Hook zpřístupňuje úrovně zvuku v reálném čase pro vytváření vizualizací reagujících na zvuk.

Každá konverzace ve widgetu je hovor. Započítává se do [limitu souběžných hovorů](/api-reference/introduction#call-limits) vaší organizace (ve výchozím nastavení 20 probíhajících hovorů, sdílených s telefonními a dalšími hovory) a do limitu widgetu 25 aktivních relací (nebo do vašeho limitu souběžných hovorů, pokud je vyšší). Při dosažení kteréhokoli limitu nelze zahájit novou konverzaci, dokud hovor neskončí.

---

## Možnosti integrace

Zvolte způsob integrace, který vyhovuje vašemu stacku:

<CardGroup cols={3}>
  <Card title="Komponenta React" icon="react" href="/cs/widget/react">
    Předpřipravená komponenta uživatelského rozhraní s integrovanými ovládacími prvky hovoru a zobrazením stavu. Importujte, předejte props a máte hotovo.
  </Card>
  <Card title="Headless hook" icon="code" href="/cs/widget/headless-hook">
    Úplná kontrola nad uživatelským rozhraním. Hook `useThunderPhone` spravuje hlasovou relaci, zatímco si vytváříte vlastní rozhraní.
  </Card>
  <Card title="CDN / značka script" icon="globe" href="/cs/widget/cdn-script-tag">
    Není vyžadován bundler. Načtěte widget pomocí značky script pro statické weby, WordPress a další prostředí mimo React.
  </Card>
</CardGroup>

---

## Stylování

Widget nabízí integrovaná světlá a tmavá témata ovládaná pomocí prop `theme` a zvýrazňující barvu ovládanou pomocí prop `primaryColor`. Pro pokročilejší přizpůsobení můžete přepsat vlastní vlastnosti a třídy CSS. Podrobnosti naleznete v [průvodci stylováním](/cs/widget/styling).

<Note>
  Potřebujete pomoc? Kontaktujte nás na adrese [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>