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

# Komponenta React

> 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 theme={null}
npm install @thunderphone/widget
```

## Základní použití

```tsx theme={null}
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 nastavení pro vývojáře. 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žívaný jako zvýrazňující barva (tlačítko hovoru, průběh zvuku, aktivní indikátory).                                                                  |
| `title`          | `string`                                                       | Ne      | `'Voice assistant'`                        | Text zobrazený v panelu widgetu.                                                                                                                                          |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Ne      | `'bottom-right'`                           | Pevná pozice widgetu ve výřezu stránky.                                                                                                                                   |
| `apiBase`        | `string`                                                       | Ne      | `'https://api.thunderphone.com/v1'`        | Přepsání základní adresy URL API.                                                                                                                                         |
| `language`       | `string`                                                       | Ne      | --                                         | Přepsání jazyka pro relaci – kód jazyka nebo národní prostředí, například `en`, `es` nebo `fr-FR`. Pokud není nastaveno, použije se nakonfigurovaný jazyk agenta.         |
| `voice`          | `string`                                                       | Ne      | --                                         | Přepsání hlasu pro relaci – název hlasu, například `maria`. Pokud není nastaveno, použije se nakonfigurovaný hlas agenta.                                                 |
| `context`        | `string`                                                       | Ne      | --                                         | Věcný kontext stránky nebo webu pro relaci předaný agentovi (například podrobnosti o stránce, kterou návštěvník zobrazuje). Na straně serveru je zkrácen na 12 000 znaků. |
| `onConnect`      | `() => void`                                                   | Ne      | --                                         | Volá se po úspěšném připojení hlasové relace.                                                                                                                             |
| `onDisconnect`   | `() => void`                                                   | Ne      | --                                         | Volá se při 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ý na kontejner widgetu.                                                                                                                       |
| `ringtone`       | `boolean \| string`                                            | Ne      | `false`                                    | Při připojování přehraje vyzváněcí tón. Hodnota `true` použije výchozí vyzváněcí tón, případně můžete zadat řetězec URL pro vlastní zvuk.                                 |

***

## Příklady

### Tmavý motiv s vlastní barvou

```tsx theme={null}
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 theme={null}
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í požadavku relace (`POST /widget/session`) a pro tuto relaci přepisují nakonfigurované výchozí hodnoty agenta:

```tsx theme={null}
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. Na straně serveru se zkracuje na 12 000 znaků.

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

```tsx theme={null}
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 theme={null}
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 theme={null}
.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 theme={null}
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 theme={null}
<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 theme={null}
<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>