---
title: "Komponenta React"
description: "Vložte hlasový widget ThunderPhone do aplikace React"
---

Komponenta `ThunderPhoneWidget` vykresluje skleněný panel hovoru s integrovanými ovládacími prvky pro ztlumení, ukončení hovoru a zobrazení stavu připojení. Je to nejrychlejší způsob, jak přidat hlasovou AI do aplikace React.

## Instalace

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

## Základní použití

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  Abyste se widget vykreslil správně, **musíte** importovat soubor CSS. Bez něj widget nebude mít žádné styly.
</Warning>

---

## Vlastnosti

Komponenta přijímá následující vlastnosti prostřednictvím `ThunderPhoneWidgetProps`:

| Vlastnost | Typ | Povinné | Výchozí | Popis |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Ano | -- | Publikovatelný klíč API (`pk_live_...`) z části **Webové widgety** v ovládacím panelu. Agent se automaticky určí z konfigurace widgetu daného klíče. |
| `theme` | `'light' \| 'dark'` | Ne | `'light'` | Barevné schéma. Na kořenový prvek widgetu použije třídu `tp--light` nebo `tp--dark`. |
| `primaryColor` | `string` | Ne | `'#000000'` (světlé) / `'#ffffff'` (tmavé) | Řetězec barvy CSS použitý jako zvýrazňující barva (tlačítko volání, průběh zvuku, aktivní indikátory). |
| `title` | `string` | Ne | `'Voice assistant'` | Text zobrazený v liště widgetu. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Ne | `'bottom-right'` | Pevná pozice widgetu ve výřezu. |
| `apiBase` | `string` | Ne | `'https://api.thunderphone.com/v1'` | Přepsání základní adresy URL API. |
| `language` | `string` | Ne | -- | Přepsání jazyka pro jednotlivou relaci – kód jazyka nebo národní prostředí, například `en`, `es` nebo `fr-FR`. Pokud není nastaveno, použije se jazyk nakonfigurovaný pro agenta. Vyžaduje `language` v části [přepsání v prohlížeči](/cs/guides/embed-web-widget) daného klíče. |
| `voice` | `string` | Ne | -- | Přepsání hlasu pro jednotlivou relaci – název hlasu, například `maria`. Pokud není nastaveno, použije se hlas nakonfigurovaný pro agenta. Vyžaduje `voice` v části [přepsání v prohlížeči](/cs/guides/embed-web-widget) daného klíče. |
| `context` | `string` | Ne | -- | Věcný kontext stránky nebo webu pro jednotlivou relaci předaný agentovi (například podrobnosti o stránce, kterou návštěvník zobrazuje). Na serveru se zkrátí na 12 000 znaků. Vyžaduje `context` v části [přepsání v prohlížeči](/cs/guides/embed-web-widget) daného klíče. |
| `onConnect` | `() => void` | Ne | -- | Volá se po úspěšném připojení hlasové relace. |
| `onDisconnect` | `() => void` | Ne | -- | Volá se po ukončení relace. |
| `onError` | `(error) => void` | Ne | -- | Volá se při chybách. Objekt `error` obsahuje pole `error` (kód) a `message`. |
| `className` | `string` | Ne | -- | Další název třídy CSS použitý pro kontejner widgetu. |
| `ringtone` | `boolean \| string` | Ne | `false` | Při připojování přehraje vyzváněcí tón. `true` pro výchozí vyzváněcí tón nebo řetězec URL pro vlastní zvuk. |

---

## Příklady

### Tmavý motiv s vlastní barvou

```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"
      title="Talk to our AI"
    />
  )
}
```

### Vlastní pozice

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### Jazyk, hlas a kontext pro relaci

Vlastnosti `language`, `voice` a `context` se při zahájení hovoru předávají do požadavku relace (`POST /widget/session`) a pro danou relaci přepisují nakonfigurované výchozí hodnoty agenta. Každou používanou vlastnost povolte v části **Přepsání v prohlížeči** pro widget na dashboardu (nebo v `allowed_overrides` klíče). Nové widgety nepovolují žádné přepsání a požadavek relace obsahující nepovolené přepsání selže s `400 override_not_allowed`; viz [Přepsání v prohlížeči](/cs/guides/embed-web-widget).

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

Pomocí `context` poskytněte agentovi faktické informace o stránce, na které se návštěvník nachází – podrobnosti o produktu, ceny nebo časté dotazy specifické pro danou stránku. Agent jej považuje za obsah stránky, nikoli za pokyny. Na straně serveru je zkrácen na 12 000 znaků.

### Se zpětnými voláními událostí

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### S vlastním stylem

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

Všechny dostupné třídy CSS a vlastní vlastnosti najdete v [průvodci stylováním](/cs/widget/styling).

### S vyzváněním

Během navazování spojení přehrávejte zvuk vyzvánění telefonu:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

Vlastní vyzvánění použijte předáním adresy URL zvukového souboru:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

Vyzvánění se opakuje, dokud je widget ve stavu `connecting`, a po připojení agenta plynule utichne.

### S vlastní základní adresou API

<Tip>
  `apiBase` stačí nastavit pouze v případě, že používáte vlastní hostovaný nebo proxy koncový bod API. Výchozí hodnota ukazuje na `https://api.thunderphone.com/v1`.
</Tip>

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

---

## Zpracování chyb

Po spuštění zpětného volání `onError` obdrží objekt chyby se dvěma poli:

| Pole | Typ | Popis |
|-------|------|-------------|
| `error` | `string` | Strojově čitelný kód chyby |
| `message` | `string` | Uživatelsky čitelný popis chyby |

Mezi běžné kódy chyb patří nepovolená doména, nenalezený agent a neplatný klíč API.

---

## Další kroky

<CardGroup cols={2}>
  <Card title="Headless hook" icon="code" href="/cs/widget/headless-hook">
    Potřebujete plnou kontrolu nad uživatelským rozhraním? Použijte místo toho hook `useThunderPhone`.
  </Card>
  <Card title="Styly" icon="palette" href="/cs/widget/styling">
    Přizpůsobte barvy, velikosti a rozvržení pomocí vlastních vlastností CSS.
  </Card>
</CardGroup>