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

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

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

Перевірка застосовується в обох режимах. У режимі webhook дозволене налаштування також пересилається до вашого webhook 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, щоб створити панель керування лише для віджета.

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