> ## 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](/ru/widget/overview)
— в этом руководстве рассматривается настройка ThunderPhone, необходимая виджету.

<Note>
  Всё это можно сделать без cURL: страница панели управления **Веб-виджеты**
  (`/dashboard/web-widgets`) создаёт виджет, задаёт его режим
  и агента, управляет разрешёнными доменами и предоставляет сниппет для встраивания.
</Note>

## Предварительные требования

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

  <Step title="Выберите режим маршрутизации">
    * `mode="agent"` — один статический агент для каждого ключа. Самый простой вариант.
    * `mode="webhook"` — ваш сервер выбирает агента для каждого посетителя через
      [вебхук `web.incoming`](/ru/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 виджета](/ru/widget/overview) описаны три
варианта интеграции:

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

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

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

Все три варианта принимают один и тот же `publishableKey` и отображают кнопку
микрофона вместе с аудиоэлементом во время звонка.

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

## Вебхуки режима виджета

Когда `mode="webhook"`, ThunderPhone вызывает ваш `webhook_url` при запуске
каждого сеанса с полезной нагрузкой `web.incoming`. Верните конфигурацию
агента, которую нужно запустить для этого посетителя — она использует ту же
[схему ответа](/ru/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="/ru/widget/overview">
    Подробности интеграции с React / хуками / CDN.
  </Card>

  <Card title="Динамическая конфигурация для каждого звонка" icon="bolt" href="/ru/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>