---
title: "Динамическая конфигурация для каждого звонка"
description: "Выбирайте отвечающего голосового агента или изменяйте его промпт и настройки отдельно для каждого входящего звонка с помощью пользовательской логики в вебхуке под вашим управлением."
---
По умолчанию каждому номеру телефона и публикуемому ключу назначен статический агент. Если нужна настройка **для каждого звонящего** или **для каждого посетителя** — маршрутизация VIP-клиентов, контекст авторизованного пользователя, A/B-тесты промптов — переключитесь в режим вебхука и предоставьте серверу принимать решение.
## Как это работает
1. Вы подписываетесь на событие [`telephony.incoming`](/ru/webhooks/events)
(телефон) или [`web.incoming`](/ru/webhooks/events) (виджет).
Оба вебхука являются **блокирующими**: ThunderPhone ожидает вашего
ответа перед продолжением звонка — до 13 секунд для телефонного
звонка (включая одну повторную попытку) и 10 секунд для сеанса виджета.
2. ThunderPhone отправляет вам `{call_id, from_number, to_number}` (сеансы
виджета содержат поля, специфичные для виджета, вместо номеров — см.
[схему запроса](/ru/webhooks/call-incoming)).
3. Ваш сервер отвечает конфигурацией агента (промпт, голос,
продукт, инструменты). ThunderPhone использует эту конфигурацию для звонка.
4. Резервного агента нет. Если вы возвращаете `{}` или недопустимую
конфигурацию либо запрос по-прежнему завершается ошибкой после
[повторной попытки](/ru/webhooks/call-incoming), телефонный
звонок немедленно завершается и фиксируется с `end_reason`
`inbound_config_webhook_failed`; запрос сеанса виджета завершается ошибкой.
Одинаково работает для телефонных вызовов (`telephony.incoming`) и сеансов
виджета (`web.incoming`), независимо от того, доставляются ли они в конечную
точку вебхука или в устаревший вебхук с единым URL.
**Вызовы с конфигурацией через встроенный вебхук не воспроизводят
уведомление ThunderPhone о согласии.** Этот путь обходит уведомление
агента в начале вызова и прямо исключён из системы уведомлений ThunderPhone
о согласии (Условия обслуживания, раздел «Запись и согласие»). Ваша
организация несёт полную ответственность за все уведомления и согласия,
связанные с записью, мониторингом, участием ИИ и идентификацией звонящего
в таких вызовах. Предоставьте их в собственном сценарии — например,
во вступительном тексте промпта — до включения режима встроенного вебхука.
Ответ вебхука, ссылающийся на сохранённый `agent_id`, использует обычную
политику этого агента в отношении записи и раскрытия информации.
## 1. Настройте конечную точку вебхука
Для номеров телефона подпишите свою конечную точку на `telephony.incoming`:
```bash
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
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)).
Не пропускайте это в разработке — один раз реализуйте правильно и используйте повторно.
- **Отвечайте быстро**. Первая попытка телефонного звонка прерывается через 10
секунд, а весь обмен — через 13, и каждая секунда — это тишина
для звонящего. При необходимости выполняйте поиск в базе данных, но не вызывайте
нижестоящие LLM синхронно — если нужна динамическая генерация промптов,
предварительно вычисляйте и кэшируйте результаты.
- **Корректно используйте резервный вариант**. Для любого непредвиденного состояния отвечайте
значениями `prompt` и `voice` по умолчанию (или сохранённым `agent_id`). Возврат `{}`
или статуса ошибки завершает звонок.
```python FastAPI
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
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), на которого вы ссылаетесь.
### Сохраните агента и передавайте переменные
Верните `{"agent_id": 12, "variables": {"name": "Ada"}}`, чтобы использовать сохранённого агента этой организации
с данными для конкретного вызова. Его промпт может содержать `{{name}}` или
`{{name|Friend}}`. Переменные вебхука объединяются с переменными уровня запроса; null
использует значение по умолчанию для заполнителя или пустой текст, если оно не указано. Итоговые
значения и неразрешённые имена отображаются в сведениях о вызове и вебхуках завершения.
Ответы сохранённого агента принимают только `agent_id`, `variables` и `timezone`. Если `prompt`
присутствует, ответ использует встроенную конфигурацию и игнорирует `agent_id` (включая
метаданные null или нецелочисленные метаданные); встроенный промпт всё равно должен быть корректным. Ответы со встроенной
конфигурацией также могут включать `variables`. Ответы сохранённого агента используют развёрнутое A/B-разделение агента как для телефонных вызовов, так и для вызовов через виджет, а затем подставляют переменные. См. [переменные вызова](/ru/guides/call-variables)
для ограничений и поддержки API сеансов. Блокирующая конфигурация поступает из устаревшего
URL номера телефона/организации или ключа виджета в режиме вебхука; входящие события системы конечных точек являются только уведомлениями.
### Настройка часового пояса для каждого звонка
Один агент может отвечать контактам из разных часовых поясов. Добавьте `timezone` — имя IANA — в ответ для сохранённого агента или встроенный ответ, и агент будет называть дату и время, а также предлагать время в этом часовом поясе для данного звонка, опережая собственный часовой пояс агента:
```json
{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}
```
Передавайте часовой пояс, а не временную метку, в `variables`: часы агента продолжают идти во время звонка, и переданное время устаревает. Значение, не являющееся часовым поясом IANA, игнорируется, и звонок подключается в часовом поясе агента.
## Шаблоны
### Контекст авторизованного пользователя
В виджетах в режиме вебхука страница посетителя уже знает, кто он.
Вызывайте свой вебхук с параметром строки запроса, который передаёт SDK
виджета (`?customer_id=123`), и ищите клиента на стороне сервера.
### A/B-раскатка промптов
Прежде чем реализовывать это самостоятельно, обратите внимание, что ThunderPhone
имеет встроенную функцию [Эксперименты](/ru/guides/concepts)
(`/dashboard/experiments` и вкладка **A/B** в конструкторе агентов), которая
задаёт варианты, распределяет трафик и сравнивает результаты по каждому варианту —
вебхук не требуется.
Если вам всё же нужен контроль на стороне вебхука: хешируйте `call_id` → группа;
отдавайте промпт A для `0..49` и промпт B для `50..99`. Записывайте выбранную
группу в собственной БД, а затем сопоставляйте её с оценкой завершённого звонка.
### Маршрутизация по времени
Рабочие часы → агент «живая поддержка»; нерабочие часы → агент «принять сообщение».
Простое переключение по `new Date().getUTCHours()` в вашем обработчике.
---
## Следующие шаги
Точные схемы запросов и ответов, включая все ключи конфигурации.
Один раз правильно настройте HMAC и используйте его везде.
Сочетайте динамическую маршрутизацию с инструментами для конкретных агентов.
Повторные попытки, порядок, тайм-ауты.