Developer cookbook

Вбудуйте вебвіджет

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

Вебвіджет надає відвідувачам вашого сайту можливість розмовляти з AI-агентом натисканням кнопки, використовуючи мікрофон браузера. Це окремий 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, щоб створити панель керування лише для віджета.

Наступні кроки#