---
title: "Компонент React"
description: "Вбудуйте голосовий віджет ThunderPhone у застосунок React"
---

Компонент `ThunderPhoneWidget` відображає скляну панель дзвінка з вбудованими елементами керування для вимкнення мікрофона, завершення дзвінка та відображення статусу підключення. Це найшвидший спосіб додати голосовий ШІ до React-застосунку.

## Встановлення

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

## Базове використання

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

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

<Warning>
  Ви **повинні** імпортувати CSS-файл, щоб віджет відображався правильно. Без нього віджет буде без стилізації.
</Warning>

---

## Властивості

Компонент приймає такі властивості через `ThunderPhoneWidgetProps`:

| Параметр | Тип | Обов’язковий | За замовчуванням | Опис |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Так | -- | Публічний ключ API (`pk_live_...`) із розділу **Вебвіджети** на панелі керування. Агент автоматично визначається за конфігурацією віджета цього ключа. |
| `theme` | `'light' \| 'dark'` | Ні | `'light'` | Колірна схема. Застосовує клас `tp--light` або `tp--dark` до кореневого елемента віджета. |
| `primaryColor` | `string` | Ні | `'#000000'` (світла) / `'#ffffff'` (темна) | Рядок кольору CSS, що використовується як акцентний колір (кнопка дзвінка, форма хвилі, активні індикатори). |
| `title` | `string` | Ні | `'Voice assistant'` | Текст, що відображається на панелі віджета. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Ні | `'bottom-right'` | Фіксоване положення віджета у вікні перегляду. |
| `apiBase` | `string` | Ні | `'https://api.thunderphone.com/v1'` | Перевизначення базової URL-адреси API. |
| `language` | `string` | Ні | -- | Перевизначення мови для сеансу — код мови або локаль, наприклад `en`, `es` чи `fr-FR`. Якщо не задано, використовується налаштована мова агента. Потребує `language` у [перевизначеннях браузера](/uk/guides/embed-web-widget) ключа. |
| `voice` | `string` | Ні | -- | Перевизначення голосу для сеансу — назва голосу, наприклад `maria`. Якщо не задано, використовується налаштований голос агента. Потребує `voice` у [перевизначеннях браузера](/uk/guides/embed-web-widget) ключа. |
| `context` | `string` | Ні | -- | Фактичний контекст сторінки або сайту для сеансу, що передається агенту (наприклад, відомості про сторінку, яку переглядає відвідувач). На стороні сервера скорочується до 12 000 символів. Потребує `context` у [перевизначеннях браузера](/uk/guides/embed-web-widget) ключа. |
| `onConnect` | `() => void` | Ні | -- | Викликається, коли голосовий сеанс успішно підключено. |
| `onDisconnect` | `() => void` | Ні | -- | Викликається, коли сеанс завершується. |
| `onError` | `(error) => void` | Ні | -- | Викликається в разі помилок. Об’єкт `error` має поля `error` (код) і `message`. |
| `className` | `string` | Ні | -- | Додаткова назва класу CSS, застосована до контейнера віджета. |
| `ringtone` | `boolean \| string` | Ні | `false` | Відтворювати сигнал виклику під час підключення. `true` для стандартного сигналу виклику або рядок URL для власного аудіо. |

---

## Приклади

### Темна тема з користувацьким кольором

```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"
    />
  )
}
```

### Користувацьке розташування

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

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

### Мова, голос і контекст для кожного сеансу

Властивості `language`, `voice` і `context` передаються до запиту сеансу (`POST /widget/session`) на початку дзвінка, замінюючи налаштовані за замовчуванням параметри агента для цього сеансу. Увімкніть кожну використовувану властивість у розділі **Перевизначення браузера** для віджета в панелі керування (або в `allowed_overrides` ключа). Нові віджети не дозволяють жодної з них, а запит сеансу, що містить вимкнену властивість, завершується помилкою `400 override_not_allowed`; див. [Перевизначення браузера](/uk/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%."
    />
  )
}
```

Використовуйте `context`, щоб надати агенту фактичні відомості про сторінку, на якій перебуває відвідувач, — деталі продукту, ціни або поширені запитання для конкретної сторінки. Агент розглядає це як вміст сторінки, а не як інструкції. На сервері текст скорочується до 12 000 символів.

### Зі зворотними викликами подій

```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}`)
      }}
    />
  )
}
```

### З користувацьким стилем

```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;
}
```

Перегляньте [посібник зі стилізації](/uk/widget/styling), щоб дізнатися про всі доступні CSS-класи та користувацькі властивості.

### Із мелодією дзвінка

Відтворюйте звук телефонного дзвінка під час встановлення з’єднання:

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

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

Використовуйте користувацьку мелодію дзвінка, передавши URL аудіофайлу:

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

Мелодія дзвінка відтворюється циклічно, поки віджет перебуває в стані `connecting`, і плавно згасає, коли агент підключається.

### Із користувацькою базою API

<Tip>
  Налаштовувати `apiBase` потрібно лише якщо ви використовуєте самостійно розгорнуту або проксійовану кінцеву точку API. За замовчуванням використовується `https://api.thunderphone.com/v1`.
</Tip>

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

---

## Обробка помилок

Коли спрацьовує зворотний виклик `onError`, він отримує об’єкт помилки з двома полями:

| Поле | Тип | Опис |
|-------|------|-------------|
| `error` | `string` | Машинозчитуваний код помилки |
| `message` | `string` | Зрозумілий для людини опис помилки |

Поширені коди помилок включають недозволений домен, агента не знайдено та недійсний ключ API.

---

## Наступні кроки

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/uk/widget/headless-hook">
    Потрібен повний контроль над інтерфейсом? Натомість використовуйте хук `useThunderPhone`.
  </Card>
  <Card title="Стилізація" icon="palette" href="/uk/widget/styling">
    Налаштовуйте кольори, розміри та компонування за допомогою користувацьких властивостей CSS.
  </Card>
</CardGroup>