Skip to main content
Когда входящий телефонный звонок поступает на номер без назначенного агента или начинается сеанс веб-виджета с публикуемым ключом в mode="webhook", ThunderPhone отправляет блокирующий запрос telephony.incoming / web.incoming на ваш устаревший URL вебхука и ждёт до 10 секунд ответа с конфигурацией. Используйте этот обмен, чтобы динамически выбирать промпт, голос и инструменты для каждого звонка — полный шаблон описан в руководстве по динамической конфигурации звонков.
Подписанные конечные точки вебхуков также получают telephony.incoming / web.incoming — для каждого входящего звонка и веб-сеанса, независимо от настройки агента, — однако эти доставки являются неблокирующими уведомлениями с event_id. Только устаревший вебхук с одним URL передаёт обмен конфигурацией, описанный на этой странице. Форматы уведомлений конечных точек приведены в каталоге событий.
У блокирующего обмена нет резервного варианта: если ваш обработчик возвращает статус не 2xx, превышает время ожидания или возвращает конфигурацию, не прошедшую проверку, звонок отклоняется (телефонный звонок не соединяется; запрос веб-сеанса виджета завершается ошибкой 502/422). Отвечайте быстро — пока вы принимаете решение, звонящий слышит сигнал вызова.

Полезная нагрузка запроса

Для телефонных звонков (telephony.incoming):
Для сеансов веб-виджета (web.incoming) поле data определяет встраивающую страницу вместо телефонных номеров:
Виджеты в режиме вебхука отправляют этот запрос на собственный webhook_url публикуемого ключа, если он задан, иначе используют URL вебхука на уровне организации. В обоих случаях запрос подписывается секретом вебхука организации secret.

Схема ответа

Верните JSON-объект с конфигурацией агента для этого вызова. prompt и voice обязательны; всё остальное необязательно.
Неизвестные ключи верхнего уровня молча игнорируются — поле с опечаткой не отклоняет конфигурацию, а просто не применяется. Порядок речи и max_hold_seconds здесь не принимаются; их можно настроить только у самого агента.
Поскольку prompt и voice обязательны, возврат {} или любого ответа, не прошедшего валидацию, отклоняет вызов с кодом 422 — на этом пути нет резервного статического агента (номер или ключ в режиме webhook не имеют назначенного агента).

Пример обработчика


Ответ с инструментами функций

Добавьте инструменты, чтобы ИИ мог вызывать ваши API в ходе разговора:
Запросы к конечным точкам инструментов подписываются тем же секретом вебхука организации, которым подписан этот обмен. Точную структуру и формат подписанного запроса см. в разделе Инструменты функций.

Краткая справка по уровням продуктов


Связанные материалы

telephony.complete / web.complete

Неблокирующее событие завершения звонка.

Инструменты функций

Полная JSON-схема для tools[] и контракт подписанного эндпоинта.

Эндпоинты вебхуков

Подпишите несколько URL на telephony.incoming / web.incoming.

Динамическая конфигурация звонка

Шаблоны для промптов, инструментов и A/B-тестов для каждого звонящего.