Developer cookbook

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

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

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

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

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

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

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

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

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

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

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 и отображают кнопку микрофона вместе с аудиоэлементом во время вызова.

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, чтобы создать панель управления только для виджета.

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