---
title: "Dinamička konfiguracija za svaki poziv"
description: "Odaberite agenta koji odgovara — ili izmijenite njegov upit i postavke — zasebno za svaki dolazni poziv, na temelju prilagođene logike u webhooku koji sami kontrolirate."
---
Prema zadanim postavkama svakom telefonskom broju i objavljivom ključu
dodijeljen je statični agent. Kada trebate prilagodbu **po pozivatelju** ili
**po posjetitelju** — VIP usmjeravanje, kontekst prijavljenog korisnika, A/B testove uputa — prijeđite na
način webhooka i prepustite odluku svom poslužitelju.
## Kako funkcionira
1. Pretplatite se na događaj [`telephony.incoming`](/hr/webhooks/events)
(telefon) ili [`web.incoming`](/hr/webhooks/events) (widget).
Oba su **blokirajući** webhookovi: ThunderPhone čeka do
10 sekundi na vaš odgovor prije nastavka poziva.
2. ThunderPhone vam šalje `{call_id, from_number, to_number}` (sesije widgeta
sadrže polja specifična za widget umjesto brojeva — pogledajte
[shemu zahtjeva](/hr/webhooks/call-incoming)).
3. Vaš poslužitelj odgovara konfiguracijom agenta (uputa, glas,
proizvod, alati). ThunderPhone upotrebljava tu konfiguraciju za poziv.
4. Ako vratite `{}`, odgovor istekne ili dođe do pogreške, kao zamjenska opcija
upotrebljava se statički dodijeljen agent. Sigurna zadana postavka.
Funkcionira jednako za telefonske pozive (`telephony.incoming`) i sesije
widgeta (`web.incoming`), bez obzira na to isporučuju li se na krajnju točku
webhooka ili na naslijeđeni webhook s jednim URL-om.
**Za pozive konfigurirane ugrađenim webhookom ne reproducira se ThunderPhoneova
obavijest o privoli.** Ovaj put zaobilazi obavijest na početku poziva na razini
agenta i izričito je isključen iz ThunderPhoneova okvira za obavijesti o privoli
(Uvjeti pružanja usluge, odjeljak "Snimanje i privola"). Vaša organizacija snosi
odgovornost za sve obavijesti i privole povezane sa snimanjem, nadzorom,
sudjelovanjem umjetne inteligencije i identifikacijom pozivatelja u tim
pozivima. Navedite ih u vlastitom tijeku — primjerice u uvodnom skriptu
upute — prije omogućavanja ugrađenog načina webhooka. Odgovor webhooka koji upućuje na
spremljeni `agent_id` primjenjuje uobičajena pravila tog agenta za snimanje i objave.
## 1. Konfigurirajte odredište webhooka
Za telefonske brojeve pretplatite svoju krajnju točku na `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"]
}'
```
Odgovor uključuje jednokratni `secret` — spremite ga; upotrijebit ćete ga
za provjeru potpisa.
Za sesije widgeta izradite objavljivi ključ u `mode="webhook"`
s ugrađenim URL-om vaše krajnje točke:
```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 će poslati POST zahtjev na ovaj URL pri svakom pokretanju sesije.
## 2. Implementirajte rukovatelj
Tri praktična pravila:
- **Provjerite potpis** pri svakom zahtjevu (pogledajte
[Provjera potpisa webhookova](/hr/guides/verify-webhook-signatures)).
Nemojte to preskočiti u razvoju — jednom to pravilno implementirajte i ponovno upotrebljavajte.
- **Odgovorite brzo**. Deset sekundi je strogo ograničenje, a svaka sekunda
pozivatelju predstavlja tišinu. Po potrebi obavite pretraživanja baze podataka, ali
nemojte sinkrono pozivati nizvodne LLM-ove — ako želite dinamičko generiranje
upita, unaprijed ih izračunajte i predmemorirajte.
- **Pouzdano primijenite zamjensko rješenje**. Svako neočekivano stanje treba vratiti `{}` kako bi
statički dodijeljeni agent obradio poziv.
```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. Shema odgovora
Tijelo odgovora točno odgovara
[ shemi odgovora za dolazni poziv](/hr/webhooks/call-incoming).
Često korištena polja:
| Polje | Vrsta | Opis |
|-------|------|-------------|
| `prompt` | string (obavezno) | Sistemska uputa za agenta |
| `voice` | string (obavezno) | ID glasa iz [`GET /v1/voices`](/api-reference/agents#voices) |
| `product` | string | Zadana vrijednost je `spark` |
| `background_track` | string \| null | ID ambijentalnog zvuka |
| `acknowledgement_prompt_mode` | string | `auto` ili `manual` (samo Storm s potvrdom) |
| `acknowledgement_prompt` | string | Obavezno kada je način rada `manual` |
| `tools` | array | Umetnute sheme alata funkcija — pogledajte [Alati funkcija](/hr/tools/overview) |
Redoslijed govorenja po pozivu i `max_hold_seconds` nisu dostupni u
odgovoru webhooka. Postavite ih na
[agentu](/api-reference/agents) na kojeg upućujete.
### Zadržite spremljenog agenta i proslijedite varijable
Vratite `{"agent_id": 12, "variables": {"name": "Ada"}}` kako biste upotrijebili
spremljenog agenta te organizacije s podacima za pojedini poziv. Njegova uputa može sadržavati `{{name}}` ili
`{{name|Friend}}`. Varijable webhooka spajaju se preko varijabli na razini zahtjeva; null
upotrebljava zadanu vrijednost rezerviranog mjesta ili prazan tekst ako nije navedena. Konačne
vrijednosti i nerazriješeni nazivi prikazuju se u pojedinostima poziva i webhookovima dovršetka.
Odgovori spremljenog agenta prihvaćaju samo `agent_id` i `variables`. Ako je prisutan `prompt`,
odgovor upotrebljava umetnutu konfiguraciju i zanemaruje `agent_id` (uključujući
null ili necjelobrojne metapodatke); umetnuta uputa i dalje mora biti valjana. Odgovori s umetnutom
konfiguracijom mogu sadržavati i `variables`. Odgovori spremljenog agenta upotrebljavaju
objavljenu A/B raspodjelu agenta za telefonske pozive i pozive iz widgeta, a zatim prikazuju varijable. Pogledajte [varijable poziva](/hr/guides/call-variables)
za ograničenja i podršku za API sesije. Blokirajuća konfiguracija dolazi iz naslijeđenog
URL-a telefonskog broja/organizacije ili ključa widgeta u načinu rada webhooka; dolazni događaji sustava krajnje točke
služe samo za obavijesti.
## Obrasci
### Kontekst prijavljenog korisnika
U widgetima u načinu rada webhooka stranica posjetitelja već zna tko su
oni. Pozovite svoj webhook s parametrom niza upita koji SDK widgeta
prosljeđuje (`?customer_id=123`) i potražite kupca na poslužitelju.
### A/B uvođenje upute
Prije nego što ovo ručno implementirate, imajte na umu da ThunderPhone ima ugrađenu
značajku [Eksperimenti](/hr/guides/concepts)
(`/dashboard/experiments` i karticu **A/B** u alatu za izradu agenata) koja
definira varijante, raspodjeljuje promet i uspoređuje ishode po varijanti —
webhook nije potreban.
Ako vam je ipak potrebna kontrola na strani webhooka: raspršite `call_id` → spremnik;
poslužite uputu A za `0..49` i uputu B za `50..99`. Zabilježite koji ste
spremnik odabrali u vlastitoj bazi podataka i kasnije ga povežite s ocjenom
dovršenog poziva.
### Usmjeravanje prema vremenu
Radno vrijeme → agent za „podršku uživo”; izvan radnog vremena → agent za „primanje poruke”.
Jednostavno prebacivanje na temelju `new Date().getUTCHours()` u vašem rukovatelju.
---
## Sljedeći koraci
Točne sheme zahtjeva i odgovora, uključujući svaki konfiguracijski ključ.
Jednom ispravno postavite HMAC; ponovno ga upotrebljavajte posvuda.
Kombinirajte dinamičko usmjeravanje s alatima po agentu.
Ponovni pokušaji, redoslijed, vremenska ograničenja.