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

Как это работает

  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. Реализуйте обработчик

Три практических правила:
  • Проверяйте подпись в каждом запросе (см. Проверка подписей вебхуков). Не пропускайте это в разработке — один раз настройте правильно и используйте повторно.
  • Отвечайте быстро. Десять секунд — это жёсткий предел, и каждая секунда — тишина для звонящего. При необходимости выполняйте поиск в базе данных, но не вызывайте нижестоящие 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 и используйте его везде.

Создание интеграции с инструментом

Объедините динамическую маршрутизацию с инструментами для каждого агента.

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

Повторные попытки, порядок, тайм-ауты.