---
title: "Вбудовуваний віджет голосового агента"
description: "Додайте голосового AI-агента на будь-який вебсайт кількома рядками коду"
---
Вбудовуваний голосовий віджет ThunderPhone дає змогу відвідувачам вашого вебсайту спілкуватися з AI-агентом безпосередньо в браузері. Телефонний дзвінок не потрібен — користувачі натискають кнопку й починають голосову розмову в реальному часі на базі ThunderPhone.
Віджет відображається як панель у стилі скломорфізму, що адаптується до світлої та темної тем, із налаштовуваними акцентними кольорами та позиціонуванням. Він поширюється як npm-пакет `@thunderphone/widget` і також доступний через CDN для середовищ без збирачів.
## Передумови
Перш ніж вбудовувати віджет, виконайте ці три кроки в [панелі керування ThunderPhone](https://app.thunderphone.com):
Перейдіть до розділу **Вебвіджети** на панелі керування та створіть віджет. Виберіть агента, якого хочете зробити доступним. Кожен віджет має власний публічний ключ (`pk_live_...`), який безпечно додавати до клієнтського коду; агента визначають за ключем.
У цьому ж віджеті додайте домени, на яких його буде вбудовано. Підтримуються шаблони з підстановкою (наприклад, `*.example.com`). Список не дає віджету працювати, якщо хтось скопіює ваш ключ на інший сайт; це не автентифікація, оскільки скрипт поза браузером може надсилати будь-який заголовок `Origin`. `localhost` не дозволено автоматично в продакшні: додайте його до списку, щоб локально тестувати з продакшн API.
Якщо ваша сторінка задає `language`, `voice` або `context`, увімкніть кожне з них у розділі **Перевизначення браузера**. Нові віджети не приймають жодного з них, а запит сеансу з вимкненим параметром завершується помилкою `400 override_not_allowed`. Див. [Перевизначення браузера](/uk/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 (
)
}
```
Готово. Ваші користувачі побачать панель дзвінка у стилі скломорфізму, яка одним натисканням з’єднає їх із вашим AI-агентом.
---
## Налаштування
Віджет має чотири властивості зовнішнього вигляду:
| Властивість | Типове значення | Опис |
|------|---------|-------------|
| `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
```
Ще три властивості налаштовують сеанс, а не вигляд — усі вони передаються до запиту сеансу під час початку дзвінка. Кожна з них працює лише тоді, коли публічний ключ віджета дозволяє її в розділі **Перевизначення браузера**; інакше запит сеансу завершується помилкою `400 override_not_allowed`:
| Властивість | Опис |
|------|-------------|
| `language` | Перевизначення мови для кожного сеансу — код або локаль, наприклад `en`, `es` чи `fr-FR` |
| `voice` | Перевизначення голосу для кожного сеансу — назва голосу, наприклад `maria` |
| `context` | Фактичний контекст сторінки або сайту, переданий агенту (на стороні сервера скорочується до 12 000 символів) |
Повну таблицю властивостей дивіться в [довіднику компонента React](/uk/widget/react).
Для повністю налаштованого інтерфейсу використовуйте [headless-хук](/uk/widget/headless-hook), щоб керувати голосовим сеансом під час створення власного інтерфейсу. Хук надає рівні аудіо в реальному часі для створення візуалізацій, що реагують на звук.
Кожна розмова у віджеті є дзвінком. Вона враховується в [ліміті одночасних дзвінків](/api-reference/introduction#call-limits) вашої організації (за замовчуванням 20 дзвінків у процесі, спільно з телефонними та іншими дзвінками), а також у ліміті віджета в 25 активних сеансів (або у вашому ліміті одночасних дзвінків, якщо він вищий). Після досягнення будь-якого з цих лімітів нова розмова не може початися, доки не завершиться дзвінок.
---
## Варіанти інтеграції
Виберіть метод інтеграції, який відповідає вашому стеку:
Готовий UI-компонент із вбудованими елементами керування дзвінками та відображенням статусу. Імпортуйте, передайте props — готово.
Повний контроль над UI. Хук `useThunderPhone` керує голосовою сесією, а ви створюєте власний інтерфейс.
Збирач не потрібен. Завантажуйте віджет через тег script для статичних сайтів, WordPress та інших середовищ без React.
---
## Стилізація
Віджет постачається з вбудованими світлою та темною темами, якими керує властивість `theme`, а також акцентним кольором, яким керує властивість `primaryColor`. Для глибшого налаштування можна перевизначити користувацькі властивості та класи CSS. Докладніше дивіться в [посібнику зі стилізації](/uk/widget/styling).
Потрібна допомога? Зв’яжіться з нами: [support@thunderphone.com](mailto:support@thunderphone.com)