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

# Вбудовуваний віджет голосового агента

> Додайте голосового AI-агента на будь-який вебсайт кількома рядками коду

Вбудовуваний голосовий віджет ThunderPhone дає змогу відвідувачам вашого вебсайту спілкуватися з AI-агентом безпосередньо в браузері. Телефонний дзвінок не потрібен — користувачі натискають кнопку й починають голосову розмову в реальному часі на базі 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>

## Передумови

Перш ніж вбудовувати віджет, виконайте ці три кроки в [панелі керування 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"
    />
  )
}
```

Готово. Ваші користувачі побачать панель дзвінка у стилі скломорфізму, яка одним натисканням з’єднає їх із вашим AI-агентом.

***

## Налаштування

Віджет має чотири властивості зовнішнього вигляду:

| Властивість    | Типове значення                            | Опис                                                                                  |
| -------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| `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>

Ще три властивості налаштовують сеанс, а не зовнішній вигляд — усі вони передаються до запиту сеансу під час початку дзвінка:

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

Повну таблицю властивостей дивіться в [довіднику компонента React](/uk/widget/react).

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

***

## Варіанти інтеграції

Виберіть метод інтеграції, який відповідає вашому стеку:

<CardGroup cols={3}>
  <Card title="React-компонент" icon="react" href="/uk/widget/react">
    Готовий UI-компонент із вбудованими елементами керування дзвінками та відображенням статусу. Імпортуйте, передайте props — готово.
  </Card>

  <Card title="Headless-хук" icon="code" href="/uk/widget/headless-hook">
    Повний контроль над UI. Хук `useThunderPhone` керує голосовою сесією, а ви створюєте власний інтерфейс.
  </Card>

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

***

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

Віджет постачається з вбудованими світлою та темною темами, якими керує властивість `theme`, а також акцентним кольором, яким керує властивість `primaryColor`. Для глибшого налаштування можна перевизначити користувацькі властивості та класи CSS. Докладніше дивіться в [посібнику зі стилізації](/uk/widget/styling).

<Note>
  Потрібна допомога? Зв’яжіться з нами: [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>