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

# Встраиваемый голосовой виджет

> Добавьте голосового ИИ-агента на любой сайт с помощью нескольких строк кода

Встраиваемый голосовой виджет ThunderPhone позволяет посетителям вашего сайта общаться с ИИ-агентом прямо из браузера. Телефонный звонок не требуется — пользователи нажимают кнопку и начинают голосовой разговор в реальном времени на базе ThunderPhone.

Виджет отображается в виде стеклянной панели, адаптирующейся к светлой и тёмной темам, с настраиваемыми акцентными цветами и расположением. Он распространяется как npm-пакет `@thunderphone/widget` и также доступен через CDN для сред без сборщиков.

<Frame>
  <img src="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="ThunderPhone widget in light and dark themes with various accent colors" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## Предварительные требования

Перед встраиванием виджета выполните эти 3 этапа в [панели управления 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 theme={null}
npm install @thunderphone/widget
```

Добавьте виджет в приложение:

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

Готово. Пользователи увидят стеклянную панель звонка, которая подключит их к вашему ИИ-агенту одним нажатием.

***

## Настройка

Виджет имеет 4 свойства внешнего вида:

| Свойство       | По умолчанию                                 | Описание                                                                               |
| -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------- |
| `theme`        | `'light'`                                    | `'light'` для светлого стекла, `'dark'` для тёмного стекла                             |
| `primaryColor` | `'#000000'` (светлая) / `'#ffffff'` (тёмная) | Акцентный цвет для кнопки запуска, звуковой волны и индикатора подключения             |
| `title`        | `'Voice assistant'`                          | Текст, отображаемый в виджете                                                          |
| `position`     | `'bottom-right'`                             | Угол области просмотра: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |

<CodeGroup>
  ```tsx Light theme (default) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

  ```tsx Dark theme with custom color theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
    theme="dark"
    primaryColor="#8b5cf6"
    title="Ask our AI"
  />
  ```
</CodeGroup>

Ещё 3 свойства настраивают сеанс, а не внешний вид — все они передаются в запрос сеанса при начале звонка:

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

Полную таблицу свойств смотрите в [справочнике React-компонента](/ru/widget/react).

Для полностью настраиваемого интерфейса используйте [headless-хук](/ru/widget/headless-hook) для управления голосовым сеансом при создании собственного интерфейса. Хук предоставляет уровни звука в реальном времени для создания визуализаций, реагирующих на аудио.

***

## Варианты интеграции

Выберите метод интеграции, подходящий для вашего стека:

<CardGroup cols={3}>
  <Card title="Компонент React" icon="react" href="/ru/widget/react">
    Готовый компонент интерфейса со встроенными элементами управления звонком и отображением статуса. Импортируйте, передайте props — готово.
  </Card>

  <Card title="Headless-хук" icon="code" href="/ru/widget/headless-hook">
    Полный контроль над интерфейсом. Хук `useThunderPhone` управляет голосовой сессией, пока вы создаёте собственный интерфейс.
  </Card>

  <Card title="CDN / тег script" icon="globe" href="/ru/widget/cdn-script-tag">
    Сборщик не требуется. Загружайте виджет через тег script для статических сайтов, WordPress и других сред без React.
  </Card>
</CardGroup>

***

## Стилизация

Виджет поставляется со встроенными светлой и тёмной темами, управляемыми свойством `theme`, а также с акцентным цветом, управляемым свойством `primaryColor`. Для более глубокой настройки можно переопределить пользовательские свойства и классы CSS. Подробнее см. в [руководстве по стилизации](/ru/widget/styling).

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