Встраиваемый голосовой виджет

Добавьте голосового ИИ-агента на любой сайт с помощью нескольких строк кода

Встраиваемый голосовой виджет ThunderPhone позволяет посетителям вашего сайта общаться с ИИ-агентом прямо из браузера. Телефонный звонок не требуется — пользователи нажимают кнопку и начинают голосовой разговор в реальном времени на базе ThunderPhone.

Виджет отображается в виде стеклянной панели, адаптирующейся к светлой и тёмной темам, с настраиваемыми акцентными цветами и расположением. Он распространяется как npm-пакет @thunderphone/widget и также доступен через CDN для сред без сборщиков.

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

Перед встраиванием виджета выполните эти 3 этапа в панели управления ThunderPhone:

1. Создайте веб-виджет

   Перейдите в раздел Веб-виджеты на панели управления и создайте виджет. Выберите агента, которого хотите сделать доступным. У каждого виджета есть собственный публикуемый ключ (pk_live_...), который безопасно включать в клиентский код; агент определяется по ключу.

2. Настройте разрешённые домены

   В этом же виджете добавьте домены, на которых он будет встроен. Поддерживаются подстановочные знаки (например, *.example.com). Этот список не позволяет виджету работать, если кто-то скопирует ваш ключ на другой сайт; это не аутентификация, поскольку скрипт вне браузера может отправить любой заголовок Origin. localhost не разрешён автоматически в продакшене: добавьте его в список, чтобы локально тестировать с API продакшена.

3. Выберите переопределения браузера

   Если ваша страница задаёт language, voice или context, включите каждый из них в разделе Переопределения браузера. Для новых виджетов ни одно из них не включено, а запрос сеанса с отключённой настройкой завершается ошибкой 400 override_not_allowed. См. Переопределения браузера.

Быстрый старт#

Установите пакет:

npm install @thunderphone/widget

Добавьте виджет в приложение:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}

Готово. Пользователи увидят стеклянную панель звонка, которая подключит их к вашему ИИ-агенту одним нажатием.

Настройка#

Виджет имеет 4 свойства внешнего вида:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>

Ещё 3 свойства настраивают сеанс, а не внешний вид: все они передаются в запрос сеанса при начале звонка. Каждое работает только в том случае, если публичный ключ виджета разрешает его в разделе Переопределения браузера; в противном случае запрос сеанса завершается ошибкой 400 override_not_allowed:

Полную таблицу свойств смотрите в справочнике React-компонента.

Для полностью настраиваемого интерфейса используйте headless-хук для управления голосовым сеансом при создании собственного интерфейса. Хук предоставляет уровни звука в реальном времени для создания визуализаций, реагирующих на аудио.

Каждый разговор в виджете считается звонком. Он учитывается в лимите одновременных звонков вашей организации (по умолчанию 20 звонков в процессе, общий с телефонными и другими звонками), а также в ограничении виджета — 25 активных сеансов (или в вашем лимите одновременных звонков, если он выше). При достижении любого из лимитов новый разговор нельзя начать, пока не завершится звонок.

Варианты интеграции#

Выберите метод интеграции, подходящий для вашего стека:

Стилизация#

Виджет поставляется со встроенными светлой и тёмной темами, управляемыми свойством theme, а также с акцентным цветом, управляемым свойством primaryColor. Для более глубокой настройки можно переопределить пользовательские свойства и классы CSS. Подробнее см. в руководстве по стилизации.