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

# Вбудуйте вебвіджет

> Додайте голосового агента на свій маркетинговий сайт або сайт підтримки — номер телефону не потрібен.

Вебвіджет дає відвідувачам вашого сайту змогу розпочати розмову з голосовим агентом ШІ натисканням, використовуючи мікрофон браузера. Це окремий SDK для JavaScript / React із власним [довідником SDK](/uk/widget/overview)
— цей посібник зосереджений на налаштуванні ThunderPhone, необхідному для віджета.

<Note>
  Ви можете виконати все це без cURL: сторінка панелі керування **Вебвіджети**
  (`/dashboard/web-widgets`) створює віджет, налаштовує його режим
  і агента, керує дозволеними доменами та надає фрагмент коду для вбудовування.
</Note>

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

<Steps>
  <Step title="Створіть агента">
    Агент, чий промпт і голос працюватимуть у сеансі віджета. Установіть
    `widget_enabled: true` (значення за замовчуванням).
  </Step>

  <Step title="Визначте режим маршрутизації">
    * `mode="agent"` — один статичний агент для кожного ключа. Найпростіший варіант.
    * `mode="webhook"` — ваш сервер вибирає агента для кожного відвідувача через
      [`web.incoming` webhook](/uk/webhooks/call-incoming). Використовуйте це для
      авторизованих користувачів, A/B-тестів або маршрутизації за сторінками.
  </Step>

  <Step title="Вкажіть дозволені домени">
    Публічні ключі прив’язані до джерела. Потрібно вказати кожне ім’я хоста,
    яке вбудовуватиме віджет. `localhost` / `127.0.0.1` завжди дозволені під час локальної розробки.
  </Step>
</Steps>

## Створіть публічний ключ

<CodeGroup>
  ```bash Static agent theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Marketing site (prod)",
      "mode":            "agent",
      "agent_id":        12,
      "allowed_domains": ["example.com", "*.example.com"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Support (dynamic)",
      "mode":            "webhook",
      "webhook_url":     "https://example.com/thunderphone/widget-hook",
      "allowed_domains": ["support.example.com"]
    }'
  ```
</CodeGroup>

Відповідь містить `key`, що починається з `pk_live_...`. **Публічні
ключі за задумом є загальнодоступними** — їх безпечно включати до фронтенд-збірки.
Перегляньте [довідник публічних ключів](/api-reference/publishable-keys), щоб дізнатися
про всі поля.

<Warning>
  `allowed_domains` має містити щонайменше один запис. `*.example.com`
  відповідає піддоменам (наприклад, `api.example.com`), але **не** кореневому
  домену. Неповні шаблони, як-от `*` або `*.*`, відхиляються.
</Warning>

## Додайте віджет на свій сайт

Три варіанти інтеграції описано в
[документації SDK віджета](/uk/widget/overview):

<CardGroup cols={3}>
  <Card title="Компонент React" icon="react" href="/uk/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="Хук без інтерфейсу" icon="circle-nodes" href="/uk/widget/headless-hook">
    `useThunderPhone()` для власних інтерфейсів.
  </Card>

  <Card title="Тег скрипту CDN" icon="code" href="/uk/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` для сайтів без збирача.
  </Card>
</CardGroup>

Усі три варіанти приймають той самий `publishableKey` і відображають кнопку
мікрофона та аудіоелемент під час виклику.

`context` віджета скорочується до 12 000 символів (приблизно 3 400
токенів типового англійського тексту) і враховується в
[доплаті за розмір промпту](/uk/guides/billing-and-topups).

## Webhook-и режиму віджета

Коли `mode="webhook"`, ThunderPhone викликає ваш `webhook_url` на початку кожного
сеансу з корисним навантаженням `web.incoming`. Поверніть конфігурацію агента,
яку потрібно запустити для цього відвідувача — вона відповідає тій самій
[схемі відповіді](/uk/webhooks/call-incoming), що й телефонні
виклики:

```json theme={null}
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

Ви можете додавати до промпту контекст із власного сеансу (який клієнт переглядає сайт,
на якій сторінці він перебуває) і змінювати агентів для кожного розгортання.

## Перегляд сеансів

Сеанси віджета відображаються в
[`GET /v1/calls`](/api-reference/calls#list-calls) з
`direction="widget"` — ті самі транскрипт, запис, оцінювання та
білінг, що й для телефонних дзвінків. Фільтруйте за `direction`, щоб створити
панель керування лише для віджета.

***

## Наступні кроки

<CardGroup cols={2}>
  <Card title="Довідник SDK віджета" icon="window-maximize" href="/uk/widget/overview">
    Відомості про інтеграцію React / hook / CDN.
  </Card>

  <Card title="Динамічна конфігурація для кожного дзвінка" icon="bolt" href="/uk/guides/dynamic-call-config">
    Реалізуйте наскрізний процес `mode="webhook"`.
  </Card>

  <Card title="Довідник публічних ключів" icon="key" href="/api-reference/publishable-keys">
    Кожне поле ресурсу ключа.
  </Card>

  <Card title="API сеансів мікрофона" icon="microphone" href="/api-reference/mic-sessions">
    Пропустіть віджет; керуйте LiveKit безпосередньо для користувацьких інтерфейсів.
  </Card>
</CardGroup>