Встройте веб-виджет

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

Веб-виджет позволяет посетителям вашего сайта начать разговор с ИИ-агентом по нажатию кнопки, используя микрофон браузера. Это отдельный JavaScript / React SDK с собственной справочной документацией SDK — в этом руководстве описана настройка на стороне ThunderPhone, необходимая для виджета.

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

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

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

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

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

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

   Определите, какие настройки сеанса может отправлять ваша страница. Новые ключи не принимают ни одной; см. Переопределения браузера.

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

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"],
    "allowed_overrides": ["context"]
  }'

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"]
  }'

Ответ содержит key, начинающийся с pk_live_.... Публикуемые ключи по своей конструкции являются публичными — их можно безопасно включать в сборку фронтенда. Полный список полей см. в справочнике публикуемых ключей.

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

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

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

Переопределения в браузере#

Виджет может отправлять со страницы четыре настройки для каждого сеанса:

Ваш публикуемый ключ является общедоступным, поэтому любой, у кого он есть, может отправлять эти настройки, в том числе из скрипта, который имитирует ваш домен. Поэтому каждая из них отключена, пока вы не разрешите её для ключа: установите флажок в разделе Переопределения браузера при создании или редактировании виджета в панели управления либо задайте allowed_overrides через API публикуемых ключей. Разрешайте только те настройки, которые действительно отправляет ваша страница.

Запрос сеанса, содержащий настройку, которую ключ не разрешает, завершается ошибкой 400 и указывает её:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

Проверка применяется в обоих режимах. В режиме вебхука разрешённая настройка также пересылается в ваш вебхук web.incoming (context поступает как website_context). Ключи, созданные до появления этой настройки, разрешают все четыре, поэтому существующие встраивания продолжают работать; отключите то, чем не пользуетесь.

Значение context виджета обрезается до 12 000 символов (примерно 3 400 токенов типичного английского текста) и учитывается в доплате за размер промпта. Агенту указано воспринимать его как содержимое страницы, а не как инструкции.

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

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

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

Вы можете добавлять в промпт контекст из собственного сеанса (какой клиент просматривает сайт, на какой он странице) и менять агентов для каждого этапа развёртывания.

Отслеживание сессий#

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

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