> ## 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. # Компонент React > Вбудуйте голосовий віджет ThunderPhone у застосунок React Компонент `ThunderPhoneWidget` відображає скляну панель дзвінка з вбудованими елементами керування для вимкнення мікрофона, завершення дзвінка та відображення статусу підключення. Це найшвидший спосіб додати голосовий ШІ до React-застосунку. ## Встановлення ```bash theme={null} npm install @thunderphone/widget ``` ## Базове використання ```tsx theme={null} import { ThunderPhoneWidget } from '@thunderphone/widget' import '@thunderphone/widget/style.css' function App() { return ( ) } ``` Ви **повинні** імпортувати CSS-файл, щоб віджет відображався правильно. Без нього віджет буде без стилізації. *** ## Властивості Компонент приймає такі властивості через `ThunderPhoneWidgetProps`: | Властивість | Тип | Обов’язково | За замовчуванням | Опис | | ---------------- | -------------------------------------------------------------- | ----------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `publishableKey` | `string` | Так | -- | Публічний API-ключ (`pk_live_...`) із налаштувань Developers. Агент визначається автоматично з конфігурації віджета ключа. | | `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 theme={null} import { ThunderPhoneWidget } from '@thunderphone/widget' import '@thunderphone/widget/style.css' function App() { return ( ) } ``` ### Користувацьке розташування ```tsx theme={null} import { ThunderPhoneWidget } from '@thunderphone/widget' import '@thunderphone/widget/style.css' function App() { return ( ) } ``` ### Мова, голос і контекст для кожного сеансу Властивості `language`, `voice` і `context` передаються в запит сеансу (`POST /widget/session`) на початку виклику, перевизначаючи налаштовані за замовчуванням параметри агента для цього сеансу: ```tsx theme={null} import { ThunderPhoneWidget } from '@thunderphone/widget' import '@thunderphone/widget/style.css' function PricingPageWidget() { return ( ) } ``` Використовуйте `context`, щоб надати агенту фактичні відомості про сторінку, на якій перебуває відвідувач: деталі продукту, ціни або поширені запитання, специфічні для сторінки. На сервері його буде скорочено до 12 000 символів. ### Зі зворотними викликами подій ```tsx theme={null} import { ThunderPhoneWidget } from '@thunderphone/widget' import '@thunderphone/widget/style.css' function SupportWidget() { return ( { 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 theme={null} import { ThunderPhoneWidget } from '@thunderphone/widget' import '@thunderphone/widget/style.css' function BrandedWidget() { return ( ) } ``` ```css theme={null} .my-custom-widget .tp-button--end { background-color: #e74c3c; } ``` Перегляньте [посібник зі стилізації](/uk/widget/styling), щоб дізнатися про всі доступні CSS-класи та користувацькі властивості. ### Із мелодією дзвінка Відтворюйте звук телефонного дзвінка під час встановлення з’єднання: ```tsx theme={null} import { ThunderPhoneWidget } from '@thunderphone/widget' import '@thunderphone/widget/style.css' function PhoneWidget() { return ( ) } ``` Використовуйте користувацьку мелодію дзвінка, передавши URL аудіофайлу: ```tsx theme={null} ``` Мелодія дзвінка відтворюється циклічно, поки віджет перебуває в стані `connecting`, і плавно згасає, коли агент підключається. ### Із користувацькою базою API Налаштовувати `apiBase` потрібно лише якщо ви використовуєте самостійно розгорнуту або проксійовану кінцеву точку API. За замовчуванням використовується `https://api.thunderphone.com/v1`. ```tsx theme={null} ``` *** ## Обробка помилок Коли спрацьовує зворотний виклик `onError`, він отримує об’єкт помилки з двома полями: | Поле | Тип | Опис | | --------- | -------- | ---------------------------------- | | `error` | `string` | Машинозчитуваний код помилки | | `message` | `string` | Зрозумілий для людини опис помилки | Поширені коди помилок включають недозволений домен, агента не знайдено та недійсний ключ API. *** ## Наступні кроки Потрібен повний контроль над інтерфейсом? Натомість використовуйте хук `useThunderPhone`. Налаштовуйте кольори, розміри та компонування за допомогою користувацьких властивостей CSS.