Как это работает
- Подпишитесь на событие
telephony.incoming(телефон) илиweb.incoming(виджет). Оба являются блокирующими вебхуками: ThunderPhone ожидает до 10 секунд ваш ответ, прежде чем продолжить звонок. - ThunderPhone отправляет вам
{call_id, from_number, to_number}(сеансы виджета содержат поля для виджета вместо номеров — см. схему запроса). - Ваш сервер отвечает конфигурацией агента (промпт, голос, продукт, инструменты). ThunderPhone использует эту конфигурацию для звонка.
- Если вы возвращаете
{}, превышаете время ожидания или возникает ошибка, в качестве резервного варианта используется статически назначенный агент. Безопасное значение по умолчанию.
Одинаково работает для телефонных звонков (
telephony.incoming) и сеансов
виджета (web.incoming), независимо от того, доставляются ли они на конечную
точку вебхука или в устаревший вебхук с единым URL.1. Настройте назначение вебхука
- Телефонные звонки
- Веб-виджет
Для телефонных номеров подпишите конечную точку на Ответ содержит одноразовый
telephony.incoming:secret — сохраните его; он понадобится
для проверки подписи.2. Реализуйте обработчик
Три практических правила:- Проверяйте подпись в каждом запросе (см. Проверка подписей вебхуков). Не пропускайте это в разработке — один раз настройте правильно и используйте повторно.
- Отвечайте быстро. Десять секунд — это жёсткий предел, и каждая секунда — тишина для звонящего. При необходимости выполняйте поиск в базе данных, но не вызывайте нижестоящие 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 и используйте его везде.
Создание интеграции с инструментом
Объедините динамическую маршрутизацию с инструментами для каждого агента.
Семантика доставки
Повторные попытки, порядок, тайм-ауты.