Як це працює
- Підпишіть кінцеву точку на подію
telephony.incoming(телефон) абоweb.incoming(віджет). Обидві події є блокувальними вебхуками: ThunderPhone очікує до 10 секунд на вашу відповідь, перш ніж продовжити дзвінок. - ThunderPhone надсилає вам
{call_id, from_number, to_number}(сеанси віджета містять поля, специфічні для віджета, замість номерів — див. схему запиту). - Ваш сервер відповідає конфігурацією агента (промпт, голос, продукт, інструменти). ThunderPhone використовує цю конфігурацію для дзвінка.
- Якщо ви повернете
{}, відповідь не надійде вчасно або станеться помилка, як резервний варіант буде використано статично призначеного агента. Безпечне значення за замовчуванням.
Працює однаково для телефонних дзвінків (
telephony.incoming) і сеансів
віджета (web.incoming), незалежно від того, чи доставляються вони до кінцевої
точки вебхука або до застарілого вебхука з єдиною URL-адресою.1. Налаштуйте призначення вебхука
- Телефонні дзвінки
- Вебвіджет
Для номерів телефону підпишіть свою кінцеву точку на Відповідь містить одноразовий
telephony.incoming:secret — збережіть його; він знадобиться
для перевірки підпису.2. Реалізуйте обробник
Три практичні правила:- Перевіряйте підпис у кожному запиті (див. Перевірка підписів вебхуків). Не пропускайте це в dev — налаштуйте правильно один раз і повторно використовуйте.
- Відповідайте швидко. Десять секунд — це жорсткий ліміт, і кожна секунда — тиша для абонента. Виконуйте пошук у базі даних за потреби, але не викликайте нижчестоящі LLM синхронно — якщо потрібне динамічне генерування промптів, попередньо обчислюйте та кешуйте їх.
- Коректно повертайтеся до запасного варіанта. Будь-який неочікуваний стан має повертати
{}, щоб виклик обробив статично призначений агент.
3. Схема відповіді
Тіло відповіді точно відповідає схемі відповіді на вхідний виклик. Поширені поля:Порядок озвучення для окремого виклику та
max_hold_seconds недоступні у
відповіді вебхука. Налаштуйте їх для
агента, на якого ви посилаєтеся.Шаблони
Контекст авторизованого користувача
У віджетах у режимі webhook сторінка відвідувача вже знає, ким він є. Викличте свій webhook із параметром рядка запиту, який SDK віджета пересилає (?customer_id=123), і знайдіть дані клієнта на сервері.
A/B-розгортання промптів
Перш ніж реалізовувати це вручну, зверніть увагу, що ThunderPhone має нативну функцію Експерименти (/dashboard/experiments і вкладка A/B у конструкторі агентів), яка
визначає варіанти, розподіляє трафік і порівнює результати для кожного варіанта —
webhook не потрібен.
Якщо вам усе ж потрібне керування на стороні webhook: хешуйте call_id → сегмент;
подавайте промпт A для 0..49 і промпт B для 50..99. Запишіть вибраний
сегмент у власну БД, а потім зіставте його з оцінкою завершеного дзвінка.
Маршрутизація за часом
Робочий час → агент «жива підтримка»; поза робочим часом → агент «прийом повідомлень». Просте перемикання заnew Date().getUTCHours() у вашому обробнику.
Наступні кроки
Довідник webhook для вхідних дзвінків
Точні схеми запитів і відповідей, зокрема кожен ключ конфігурації.
Перевірка підписів webhook
Один раз правильно налаштуйте HMAC; використовуйте всюди.
Створення інтеграції інструменту
Поєднайте динамічну маршрутизацію з інструментами для кожного агента.
Семантика доставки
Повторні спроби, порядок, тайм-аути.