---
title: "React компонент"
description: "Вградете гласовата джаджа ThunderPhone в React приложение"
---

Компонентът `ThunderPhoneWidget` визуализира стъклен панел за разговор с вградени контроли за заглушаване, прекратяване на разговора и показване на състоянието на връзката. Това е най-бързият начин да добавите гласов AI към 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`. Когато не е зададено, се прилага конфигурираният език на агента. |
| `voice` | `string` | Не | -- | Замяна на гласа за конкретната сесия -- име на глас, като `maria`. Когато не е зададено, се прилага конфигурираният глас на агента. |
| `context` | `string` | Не | -- | Фактически контекст за страница или сайт за конкретната сесия, предаван на агента (например подробности за страницата, която посетителят разглежда). Съкратен от сървъра до 12 000 знака. |
| `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`) при започване на разговор, като заместват конфигурираните по подразбиране настройки на агента за тази сесия:

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

Вижте [ръководството за стилизиране](/bg/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="/bg/widget/headless-hook">
    Нуждаете се от пълен контрол над потребителския интерфейс? Вместо това използвайте hook-а `useThunderPhone`.
  </Card>
  <Card title="Стилизиране" icon="palette" href="/bg/widget/styling">
    Персонализирайте цветовете, размерите и оформлението с персонализирани CSS свойства.
  </Card>
</CardGroup>