---
title: "Встраиваемый голосовой виджет"
description: "Добавьте голосового ИИ-агента на любой сайт с помощью нескольких строк кода"
---
Встраиваемый голосовой виджет ThunderPhone позволяет посетителям вашего сайта общаться с ИИ-агентом прямо из браузера. Телефонный звонок не требуется — пользователи нажимают кнопку и начинают голосовой разговор в реальном времени на базе ThunderPhone.
Виджет отображается в виде стеклянной панели, адаптирующейся к светлой и тёмной темам, с настраиваемыми акцентными цветами и расположением. Он распространяется как npm-пакет `@thunderphone/widget` и также доступен через CDN для сред без сборщиков.
## Предварительные требования
Перед встраиванием виджета выполните эти 3 этапа в [панели управления ThunderPhone](https://app.thunderphone.com):
Перейдите в раздел **Веб-виджеты** на панели управления и создайте виджет. Выберите агента, которого хотите сделать доступным. У каждого виджета есть собственный публикуемый ключ (`pk_live_...`), который безопасно включать в клиентский код; агент определяется по ключу.
В этом же виджете добавьте домены, на которых он будет встроен. Поддерживаются подстановочные знаки (например, `*.example.com`). Этот список не позволяет виджету работать, если кто-то скопирует ваш ключ на другой сайт; это не аутентификация, поскольку скрипт вне браузера может отправить любой заголовок `Origin`. `localhost` не разрешён автоматически в продакшене: добавьте его в список, чтобы локально тестировать с API продакшена.
Если ваша страница задаёт `language`, `voice` или `context`, включите каждый из них в разделе **Переопределения браузера**. Для новых виджетов ни одно из них не включено, а запрос сеанса с отключённой настройкой завершается ошибкой `400 override_not_allowed`. См. [Переопределения браузера](/ru/guides/embed-web-widget).
Публикуемые ключи (`pk_live_...`) **не** совпадают с секретными API-токенами. Публикуемые ключи предназначены для клиентского использования и ограничены сеансами виджета на разрешённых доменах. Никогда не используйте секретный API-токен в клиентском коде.
По умолчанию сеансы виджета завершаются через 30 минут или раньше, если собственная максимальная длительность звонка агента меньше. Измените ограничение для каждого ключа с помощью `max_call_duration_seconds` в [публикуемом ключе](/api-reference/publishable-keys) (до 6 часов) или установите `null`, чтобы использовать ограничение самого агента.
---
## Быстрый старт
Установите пакет:
```bash
npm install @thunderphone/widget
```
Добавьте виджет в приложение:
```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
function App() {
return (
)
}
```
Готово. Пользователи увидят стеклянную панель звонка, которая подключит их к вашему ИИ-агенту одним нажатием.
---
## Настройка
Виджет имеет 4 свойства внешнего вида:
| Свойство | По умолчанию | Описание |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` для светлого стекла, `'dark'` для тёмного стекла |
| `primaryColor` | `'#000000'` (светлая) / `'#ffffff'` (тёмная) | Акцентный цвет для кнопки запуска, звуковой волны и индикатора подключения |
| `title` | `'Voice assistant'` | Текст, отображаемый в виджете |
| `position` | `'bottom-right'` | Угол области просмотра: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |
```tsx Light theme (default)
```
```tsx Dark theme with custom color
```
Ещё 3 свойства настраивают сеанс, а не внешний вид: все они передаются в запрос сеанса при начале звонка. Каждое работает только в том случае, если публичный ключ виджета разрешает его в разделе **Переопределения браузера**; в противном случае запрос сеанса завершается ошибкой `400 override_not_allowed`:
| Свойство | Описание |
|------|-------------|
| `language` | Переопределение языка для сеанса — код или локаль, например `en`, `es` или `fr-FR` |
| `voice` | Переопределение голоса для сеанса — имя голоса, например `maria` |
| `context` | Фактический контекст страницы или сайта, передаваемый ИИ-агенту (на стороне сервера сокращается до 12 000 символов) |
Полную таблицу свойств смотрите в [справочнике React-компонента](/ru/widget/react).
Для полностью настраиваемого интерфейса используйте [headless-хук](/ru/widget/headless-hook) для управления голосовым сеансом при создании собственного интерфейса. Хук предоставляет уровни звука в реальном времени для создания визуализаций, реагирующих на аудио.
Каждый разговор в виджете считается звонком. Он учитывается в [лимите одновременных звонков](/api-reference/introduction#call-limits) вашей организации (по умолчанию 20 звонков в процессе, общий с телефонными и другими звонками), а также в ограничении виджета — 25 активных сеансов (или в вашем лимите одновременных звонков, если он выше). При достижении любого из лимитов новый разговор нельзя начать, пока не завершится звонок.
---
## Варианты интеграции
Выберите метод интеграции, подходящий для вашего стека:
Готовый компонент интерфейса со встроенными элементами управления звонком и отображением статуса. Импортируйте, передайте props — готово.
Полный контроль над интерфейсом. Хук `useThunderPhone` управляет голосовой сессией, пока вы создаёте собственный интерфейс.
Сборщик не требуется. Загружайте виджет через тег script для статических сайтов, WordPress и других сред без React.
---
## Стилизация
Виджет поставляется со встроенными светлой и тёмной темами, управляемыми свойством `theme`, а также с акцентным цветом, управляемым свойством `primaryColor`. Для более глубокой настройки можно переопределить пользовательские свойства и классы CSS. Подробнее см. в [руководстве по стилизации](/ru/widget/styling).
Нужна помощь? Свяжитесь с нами по email: [support@thunderphone.com](mailto:support@thunderphone.com)