Skip to main content
Веб-виджет даёт посетителям вашего сайта возможность начать разговор с ИИ-агентом по клику, используя микрофон браузера. Это отдельный SDK для JavaScript / React со своей справкой по SDK — в этом руководстве рассматривается настройка ThunderPhone, необходимая виджету.
Всё это можно сделать без cURL: страница панели управления Веб-виджеты (/dashboard/web-widgets) создаёт виджет, задаёт его режим и агента, управляет разрешёнными доменами и предоставляет сниппет для встраивания.

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

1

Создайте агента

Агент, чьи промпт и голос будут использоваться в сеансе виджета. Установите widget_enabled: true (значение по умолчанию).
2

Выберите режим маршрутизации

  • mode="agent" — один статический агент для каждого ключа. Самый простой вариант.
  • mode="webhook" — ваш сервер выбирает агента для каждого посетителя через вебхук web.incoming. Используйте этот вариант для авторизованных пользователей, A/B-тестов или маршрутизации по страницам.
3

Укажите разрешённые домены

Публикуемые ключи привязаны к источнику. Необходимо указать все имена хостов, на которых будет встроен виджет. localhost / 127.0.0.1 всегда разрешены во время локальной разработки.

​
Создайте публикуемый ключ

Ответ содержит key, начинающийся с pk_live_.... Публикуемые ключи по своей структуре являются публичными — их можно безопасно включать в пакет фронтенда. Полный список полей приведён в справке по публикуемым ключам.
allowed_domains должен содержать хотя бы одну запись. *.example.com соответствует поддоменам (например, api.example.com), но не корневому домену. Простые подстановочные знаки, такие как * или *.*, отклоняются.

​
Добавьте виджет на сайт

В документации SDK виджета описаны три варианта интеграции:

Компонент React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Хук без интерфейса

useThunderPhone() для пользовательских интерфейсов.

Тег скрипта CDN

ThunderPhone.mount({...}) для сайтов без сборщика.
Все три варианта принимают один и тот же publishableKey и отображают кнопку микрофона вместе с аудиоэлементом во время звонка. context виджета обрезается до 12 000 символов (примерно 3 400 токенов типичного английского текста) и учитывается при расчёте доплаты за размер промпта.

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

Когда mode="webhook", ThunderPhone вызывает ваш webhook_url при запуске каждого сеанса с полезной нагрузкой web.incoming. Верните конфигурацию агента, которую нужно запустить для этого посетителя — она использует ту же схему ответа, что и телефонные звонки:
Вы можете добавлять в промпт контекст из собственного сеанса (какой клиент просматривает сайт, на какой странице он находится) и менять агентов для каждого развертывания.

​
Просмотр сессий

Сессии виджета отображаются в GET /v1/calls с direction="widget" — та же расшифровка, запись, оценка и тарификация, что и у телефонных звонков. Фильтруйте по direction, чтобы создать панель мониторинга только для виджета.

​
Следующие шаги

Справочник SDK виджета

Подробности интеграции с React / хуками / CDN.

Динамическая конфигурация для каждого звонка

Реализуйте поток mode="webhook" от начала до конца.

Справочник публикуемых ключей

Все поля ресурса ключа.

API микрофонных сессий

Пропустите виджет; управляйте LiveKit напрямую для пользовательских интерфейсов.