---
title: "Вградима джаджа за гласов агент"
description: "Добавете гласов AI агент към всеки уебсайт с няколко реда код"
---

Вградяемият гласов уиджет на ThunderPhone позволява на посетителите на вашия уебсайт да разговарят с AI агент директно от браузъра. Не е необходимо телефонно обаждане -- потребителите щракват върху бутон и започват гласов разговор в реално време, задвижван от ThunderPhone.

Уиджетът се визуализира като стъкломорфна лента, която се адаптира към светли и тъмни теми, с персонализируеми акцентни цветове и позициониране. Разпространява се като npm пакета `@thunderphone/widget` и е достъпен и чрез CDN за среди без bundler.

<Frame>
  <img src="/images/widget-showcase.png" alt="Уиджетът на ThunderPhone в светли и тъмни теми с различни акцентни цветове" />
</Frame>

## Предварителни изисквания

Преди да вградите уиджета, изпълнете тези три стъпки в [таблото за управление на ThunderPhone](https://app.thunderphone.com):

<Steps>
<Step title="Създайте публикуем API ключ">
  Отидете в **Разработчици** в настройките на таблото за управление и създайте публикуем ключ. Публикуемите ключове започват с `pk_live_` и могат безопасно да се включват в клиентски код.
</Step>

<Step title="Конфигурирайте разрешените домейни">
  В същите настройки за Разработчици добавете домейните, в които ще бъде вграден уиджетът. `localhost` винаги е разрешен за разработка. Поддържат се заместващи символи (напр. `*.example.com`).
</Step>

<Step title="Създайте уеб уиджет">
  Отидете в **Уеб уиджети** в таблото за управление и създайте уиджет. Изберете агента, който искате да предоставите, и публикуемия ключ, който да използвате. Агентът се определя автоматично от конфигурацията на вашия публикуем ключ.
</Step>
</Steps>

<Warning>
  Публикуемите ключове (`pk_live_...`) **не** са същите като вашите тайни API токени. Публикуемите ключове са предназначени за използване от клиентска страна и са ограничени до сесии на уиджета във вашите разрешени домейни. Никога не използвайте своя таен API токен в клиентски код.
</Warning>

---

## Бърз старт

Инсталирайте пакета:

```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"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

Това е всичко. Вашите потребители ще видят стъкломорфна лента за разговор, която ги свързва с вашия AI агент с едно щракване.

---

## Персонализиране

Уиджетът има четири свойства за външен вид:

| Свойство | По подразбиране | Описание |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` за бяло стъкло, `'dark'` за тъмно стъкло |
| `primaryColor` | `'#000000'` (светло) / `'#ffffff'` (тъмно) | Акцентен цвят за бутона за стартиране, звуковата вълна и индикатора за свързване |
| `title` | `'Voice assistant'` | Текст, показван в уиджета |
| `position` | `'bottom-right'` | Ъгъл на viewport: `'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>

Още три свойства персонализират сесията, а не външния вид -- всички се препращат към заявката за сесия при започване на разговор:

| Свойство | Описание |
|------|-------------|
| `language` | Замяна на езика за конкретната сесия -- код или локал, като `en`, `es` или `fr-FR` |
| `voice` | Замяна на гласа за конкретната сесия -- име на глас, като `maria` |
| `context` | Фактически контекст за страница или сайт, предаван на агента (съкратен от сървъра до 12 000 знака) |

Вижте [справочника за React компонента](/bg/widget/react) за пълната таблица със свойства.

За напълно персонализиран интерфейс използвайте [headless hook](/bg/widget/headless-hook), за да управлявате гласовата сесия, докато изграждате собствен интерфейс. Hook-ът предоставя аудио нива в реално време за създаване на визуализации, реагиращи на аудио.

---

## Опции за интеграция

Изберете метода за интеграция, който отговаря на вашия стек:

<CardGroup cols={3}>
  <Card title="React компонент" icon="react" href="/bg/widget/react">
    Предварително изграден UI компонент с вградени контроли за разговори и показване на състоянието. Импортирайте, подайте пропсове и сте готови.
  </Card>
  <Card title="Headless hook" icon="code" href="/bg/widget/headless-hook">
    Пълен контрол върху UI. Hook-ът `useThunderPhone` управлява гласовата сесия, докато вие изграждате собствен интерфейс.
  </Card>
  <Card title="CDN / Script таг" icon="globe" href="/bg/widget/cdn-script-tag">
    Не е необходим bundler. Заредете уиджета чрез script таг за статични сайтове, WordPress и други среди извън React.
  </Card>
</CardGroup>

---

## Стилизиране

Уиджетът се предоставя с вградени светла и тъмна тема, управлявани чрез пропса `theme`, и акцентен цвят, управляван чрез пропса `primaryColor`. За по-задълбочена персонализация можете да презапишете CSS персонализирани свойства и класове. Вижте [ръководството за стилизиране](/bg/widget/styling) за подробности.

<Note>
  Нуждаете се от помощ? Свържете се с нас на [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>