---
title: "Dynamická konfigurácia pre každý hovor"
description: "Pre každý prichádzajúci hovor samostatne vyberte hlasového agenta, ktorý ho prijme, alebo upravte jeho pokyn a nastavenia na základe vlastnej logiky vo webhooku, ktorý spravujete."
---
Každé telefónne číslo a publikovateľný kľúč má predvolene
priradeného statického agenta. Keď potrebujete prispôsobenie **pre jednotlivých volajúcich** alebo **pre jednotlivých návštevníkov**
— smerovanie VIP, kontext prihláseného používateľa, A/B testy promptov — prepnite do
režimu webhooku a nechajte rozhodnúť svoj server.
## Ako to funguje
1. Prihlásite sa na odber udalosti [`telephony.incoming`](/sk/webhooks/events)
(telefón) alebo [`web.incoming`](/sk/webhooks/events) (widget).
Obe sú **blokujúce** webhooky: ThunderPhone čaká na vašu odpoveď až
10 sekúnd, než bude pokračovať v hovore.
2. ThunderPhone vám odošle `{call_id, from_number, to_number}` (relácie widgetu
namiesto čísel obsahujú polia špecifické pre widget — pozrite si
[schému požiadavky](/sk/webhooks/call-incoming)).
3. Váš server odpovie konfiguráciou agenta (prompt, hlas,
produkt, nástroje). ThunderPhone túto konfiguráciu použije pre hovor.
4. Ak vrátite `{}`, dôjde k časovému limitu alebo chybe, ako záložné riešenie sa použije
staticky priradený agent. Bezpečné predvolené nastavenie.
Funguje rovnako pre telefonické hovory (`telephony.incoming`) aj relácie
widgetu (`web.incoming`), či sa doručujú na koncový bod webhooku
alebo na starší webhook s jednou URL.
**Pri hovoroch konfigurovaných vloženým webhookom sa neprehráva žiadne oznámenie o súhlase ThunderPhone.** Táto cesta obchádza oznámenie na začiatku hovoru na úrovni agenta
a je výslovne vylúčená z rámca oznámení o súhlase ThunderPhone
(Podmienky používania, časť „Nahrávanie a súhlas“). Vaša
organizácia zodpovedá za všetky oznámenia a súhlasy týkajúce sa nahrávania,
monitorovania, účasti AI a identifikácie volajúceho pri týchto hovoroch.
Poskytnite ich vo vlastnom postupe — napríklad v úvodnom skripte promptu —
pred povolením režimu vloženého webhooku. Odpoveď webhooku, ktorá odkazuje na
uložené `agent_id`, používa bežné pravidlá nahrávania a zverejňovania informácií daného agenta.
## 1. Nakonfigurujte cieľ webhooku
Pre telefónne čísla prihláste svoj koncový bod na odber `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"]
}'
```
Odpoveď obsahuje jednorazový `secret` — uložte ho; použijete ho
na overenie podpisu.
Pre relácie widgetu vytvorte publikovateľný kľúč v režime `mode="webhook"`
s URL vášho koncového bodu vloženou priamo v ňom:
```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"]
}'
```
Widget odošle na túto URL požiadavku POST pri každom začatí relácie.
## 2. Implementujte obslužnú funkciu
Tri základné pravidlá:
- **Overujte podpis** pri každej požiadavke (pozrite si
[Overenie podpisov webhookov](/sk/guides/verify-webhook-signatures)).
Nevynechávajte to ani vo vývoji — nastavte to správne raz a potom to znova použite.
- **Odpovedajte rýchlo**. Desať sekúnd je pevný limit a každá sekunda znamená
ticho pre volajúceho. Ak potrebujete, vykonajte vyhľadávanie v databáze, ale
nevolajte nadväzujúce LLM synchrónne — ak chcete dynamické generovanie promptov, vopred ich vypočítajte a uložte do vyrovnávacej pamäte.
- **Zabezpečte čistý náhradný postup**. Každý neočakávaný stav by mal vrátiť `{}`, aby
hovor spracoval staticky priradený agent.
```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. Schéma odpovede
Telo odpovede presne zodpovedá
[schéme odpovede na prichádzajúci hovor](/sk/webhooks/call-incoming).
Bežne používané polia:
| Pole | Typ | Popis |
|-------|------|-------------|
| `prompt` | reťazec (povinné) | Systémový prompt pre agenta |
| `voice` | reťazec (povinné) | ID hlasu z [`GET /v1/voices`](/api-reference/agents#voices) |
| `product` | reťazec | Predvolene `spark` |
| `background_track` | reťazec \| null | ID ambientného zvuku |
| `acknowledgement_prompt_mode` | reťazec | `auto` alebo `manual` (iba Storm s potvrdením) |
| `acknowledgement_prompt` | reťazec | Povinné, keď je režim `manual` |
| `tools` | pole | Vložené schémy funkčných nástrojov — pozrite si [Funkčné nástroje](/sk/tools/overview) |
Poradie hovorenia pre jednotlivý hovor a `max_hold_seconds` nie sú v
odpovedi webhooku k dispozícii. Nastavte ich pri
[Agentovi](/api-reference/agents), na ktorého odkazujete.
### Zachovajte uloženého agenta a zadajte premenné
Vráťte `{"agent_id": 12, "variables": {"name": "Ada"}}`, aby ste použili uloženého
agenta danej organizácie s údajmi pre jednotlivý hovor. Jeho prompt môže obsahovať
`{{name}}` alebo `{{name|Friend}}`. Premenné webhooku sa zlúčia cez premenné na
úrovni požiadavky; hodnota null použije predvolenú hodnotu zástupného symbolu alebo
prázdny text, ak nie je zadaná. Konečné hodnoty a nevyriešené názvy sa zobrazia v
podrobnostiach hovoru a webhookoch po dokončení. Odpovede uloženého agenta prijímajú
iba `agent_id` a `variables`. Ak je prítomný `prompt`, odpoveď používa vloženú
konfiguráciu a ignoruje `agent_id` (vrátane metadát null alebo neceločíselných
metadát); vložený prompt musí byť stále platný. Odpovede s vloženou konfiguráciou
môžu obsahovať aj `variables`. Odpovede uloženého agenta používajú nasadené A/B
rozdelenie agenta pri telefonických hovoroch aj hovoroch z widgetu a potom vykreslia
premenné. Informácie o limitoch a podpore API relácií nájdete v časti
[premenné hovoru](/sk/guides/call-variables). Blokujúca konfigurácia pochádza zo
staršej adresy URL telefónneho čísla/organizácie alebo z kľúča widgetu v režime
webhooku; prichádzajúce udalosti systému endpointu sú iba oznámenia.
## Vzory
### Kontext prihláseného používateľa
Vo widgetoch v režime webhooku stránka návštevníka už vie, kto
je. Zavolajte svoj webhook s parametrom reťazca dotazu, ktorý SDK widgetu
prepošle (`?customer_id=123`), a zákazníka vyhľadajte na strane servera.
### Zavedenie A/B promptov
Skôr než to vytvoríte ručne, všimnite si, že ThunderPhone má natívnu
funkciu [Experimenty](/sk/guides/concepts)
(`/dashboard/experiments` a kartu **A/B** v nástroji na vytváranie agentov), ktorá
definuje varianty, rozdeľuje návštevnosť a porovnáva výsledky jednotlivých variantov —
webhook nie je potrebný.
Ak napriek tomu potrebujete riadenie na strane webhooku: hašujte `call_id` → segment;
pre `0..49` použite prompt A a pre `50..99` prompt B. Zaznamenajte, ktorý
segment ste vybrali, do vlastnej databázy a neskôr ho korelujte s hodnotením
dokončeného hovoru.
### Smerovanie podľa času
Pracovné hodiny → agent „živá podpora“; mimo pracovných hodín → agent „prijať správu“.
Vo svojom obslužnom programe stačí prepínať podľa `new Date().getUTCHours()`.
---
## Ďalšie kroky
Presné schémy požiadaviek a odpovedí vrátane každého konfiguračného kľúča.
Správne nastavte HMAC raz a používajte ho všade.
Skombinujte dynamické smerovanie s nástrojmi pre jednotlivých agentov.
Opakovania, poradie, časové limity.