> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Динамическая настройка для каждого звонка > Выбирайте агента или изменяйте промпт для каждого входящего звонка на основе пользовательской логики в вебхуке. По умолчанию каждому номеру телефона и публикуемому ключу назначен статический агент. Если вам нужна настройка **для каждого звонящего** или **для каждого посетителя** — VIP-маршрутизация, контекст авторизованного пользователя, A/B-тесты промптов — перейдите в режим webhook и позвольте серверу принимать решение. ## Как это работает 1. Подпишитесь на событие [`telephony.incoming`](/ru/webhooks/events) (телефон) или [`web.incoming`](/ru/webhooks/events) (виджет). Оба являются **блокирующими** вебхуками: ThunderPhone ожидает до 10 секунд ваш ответ, прежде чем продолжить звонок. 2. ThunderPhone отправляет вам `{call_id, from_number, to_number}` (сеансы виджета содержат поля для виджета вместо номеров — см. [схему запроса](/ru/webhooks/call-incoming)). 3. Ваш сервер отвечает конфигурацией агента (промпт, голос, продукт, инструменты). ThunderPhone использует эту конфигурацию для звонка. 4. Если вы возвращаете `{}`, превышаете время ожидания или возникает ошибка, в качестве резервного варианта используется статически назначенный агент. Безопасное значение по умолчанию. Одинаково работает для телефонных звонков (`telephony.incoming`) и сеансов виджета (`web.incoming`), независимо от того, доставляются ли они на конечную точку вебхука или в устаревший вебхук с единым URL. ## 1. Настройте назначение вебхука Для телефонных номеров подпишите конечную точку на `telephony.incoming`: ```bash theme={null} curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Prod call-incoming", "url": "https://example.com/thunderphone/incoming", "events": ["telephony.incoming"] }' ``` Ответ содержит одноразовый `secret` — сохраните его; он понадобится для проверки подписи. Для сеансов виджета создайте публикуемый ключ в `mode="webhook"` со встроенным URL конечной точки: ```bash theme={null} curl -X POST https://api.thunderphone.com/v1/publishable-key \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Dynamic widget", "mode": "webhook", "webhook_url": "https://example.com/thunderphone/widget-incoming", "allowed_domains": ["example.com"] }' ``` Виджет будет отправлять POST-запрос на этот URL при начале каждого сеанса. ## 2. Реализуйте обработчик Три практических правила: * **Проверяйте подпись** в каждом запросе (см. [Проверка подписей вебхуков](/ru/guides/verify-webhook-signatures)). Не пропускайте это в разработке — один раз настройте правильно и используйте повторно. * **Отвечайте быстро**. Десять секунд — это жёсткий предел, и каждая секунда — тишина для звонящего. При необходимости выполняйте поиск в базе данных, но не вызывайте нижестоящие LLM синхронно — если нужна динамическая генерация промптов, заранее вычисляйте и кэшируйте их. * **Корректно используйте резервный вариант**. При любом непредвиденном состоянии возвращайте `{}`, чтобы вызов обработал статически назначенный агент. ```python FastAPI theme={null} import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, sig: str) -> bool: expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, sig or "") @app.post("/thunderphone/incoming") async def incoming(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(401) event = json.loads(body) if event["type"] not in ("telephony.incoming", "web.incoming"): return {} # fall back to default caller = event["data"]["from_number"] # Cheap DB lookup: is this a known VIP? customer = lookup_customer(caller) if customer and customer.tier == "vip": return { "prompt": f"You are a VIP concierge for {customer.name}. Be proactive…", "voice": "john", "product": "storm-base", } return {} # default agent handles non-VIPs def lookup_customer(phone: str): # ... your CRM integration ... pass ``` ```javascript Express theme={null} import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, sig) { const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex"); return sig && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)); } app.post( "/thunderphone/incoming", express.raw({ type: "application/json" }), async (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); const IMPORTANT_TYPES = new Set([ "telephony.incoming", "web.incoming", ]); if (!IMPORTANT_TYPES.has(event.type)) return res.json({}); const customer = await lookupCustomer(event.data.from_number); if (customer?.tier === "vip") { return res.json({ prompt: `You are a VIP concierge for ${customer.name}. Be proactive…`, voice: "john", product: "storm-base", }); } res.json({}); // fall back to default agent }, ); ``` ## 3. Схема ответа Тело ответа в точности соответствует [схеме ответа на входящий вызов](/ru/webhooks/call-incoming). Часто используемые поля: | Поле | Тип | Описание | | ----------------------------- | -------------------- | ------------------------------------------------------------------------------------- | | `prompt` | строка (обязательно) | Системный промпт для агента | | `voice` | строка (обязательно) | Идентификатор голоса из [`GET /v1/voices`](/api-reference/agents#voices) | | `product` | строка | По умолчанию — `spark` | | `background_track` | строка \| null | Идентификатор фонового аудио | | `acknowledgement_prompt_mode` | строка | `auto` или `manual` (только Storm с подтверждением) | | `acknowledgement_prompt` | строка | Обязательно, когда режим — `manual` | | `tools` | массив | Встроенные схемы инструментов-функций — см. [Инструменты-функции](/ru/tools/overview) | Порядок реплик для каждого вызова и `max_hold_seconds` недоступны в ответе вебхука. Настройте их для [Агента](/api-reference/agents), на которого вы ссылаетесь. ## Паттерны ### Контекст вошедшего в систему пользователя В виджетах в режиме webhook страница посетителя уже знает, кто он. Вызовите свой webhook с параметром строки запроса, который SDK виджета перенаправляет (`?customer_id=123`), и найдите клиента на стороне сервера. ### A/B-раскатка промптов Прежде чем реализовывать это вручную, учтите, что в ThunderPhone есть встроенная функция [Эксперименты](/ru/guides/concepts) (`/dashboard/experiments` и вкладка **A/B** в конструкторе агента), которая определяет варианты, распределяет трафик и сравнивает результаты по вариантам — webhook не требуется. Если вам всё же нужен контроль на стороне webhook: хешируйте `call_id` → сегмент; отдавайте промпт A для `0..49` и промпт B для `50..99`. Запишите выбранный сегмент в собственной БД, а затем сопоставьте его с оценкой завершённого звонка. ### Маршрутизация по времени Рабочие часы → агент «поддержка в реальном времени»; нерабочие часы → агент «принять сообщение». Обычное переключение по `new Date().getUTCHours()` в вашем обработчике. *** ## Следующие шаги Точные схемы запроса и ответа, включая каждый ключ конфигурации. Один раз правильно настройте HMAC и используйте его везде. Объедините динамическую маршрутизацию с инструментами для каждого агента. Повторные попытки, порядок, тайм-ауты.