Skip to main content
За замовчуванням кожному номеру телефону та публічному ключу призначено статичного агента. Якщо вам потрібне налаштування для кожного абонента або для кожного відвідувача — VIP-маршрутизація, контекст авторизованого користувача, A/B-тестування промптів — перейдіть у режим вебхуків і дозвольте вашому серверу ухвалювати рішення.

Як це працює

  1. Підпишіть кінцеву точку на подію telephony.incoming (телефон) або web.incoming (віджет). Обидві події є блокувальними вебхуками: ThunderPhone очікує до 10 секунд на вашу відповідь, перш ніж продовжити дзвінок.
  2. ThunderPhone надсилає вам {call_id, from_number, to_number} (сеанси віджета містять поля, специфічні для віджета, замість номерів — див. схему запиту).
  3. Ваш сервер відповідає конфігурацією агента (промпт, голос, продукт, інструменти). ThunderPhone використовує цю конфігурацію для дзвінка.
  4. Якщо ви повернете {}, відповідь не надійде вчасно або станеться помилка, як резервний варіант буде використано статично призначеного агента. Безпечне значення за замовчуванням.
Працює однаково для телефонних дзвінків (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; використовуйте всюди.

Створення інтеграції інструменту

Поєднайте динамічну маршрутизацію з інструментами для кожного агента.

Семантика доставки

Повторні спроби, порядок, тайм-аути.