--- title: "Dynamická konfigurace pro jednotlivé hovory" description: "Pro každý příchozí hovor samostatně vyberte odpovídajícího agenta nebo upravte jeho prompt a nastavení podle vlastní logiky ve webhooku, který spravujete." --- Ve výchozím nastavení má každé telefonní číslo a publikovatelný klíč přiřazeného statického agenta. Pokud potřebujete přizpůsobení **pro jednotlivé volající** nebo **pro jednotlivé návštěvníky** — směrování VIP, kontext přihlášeného uživatele, A/B testy promptů — přepněte do režimu webhooku a nechte rozhodnout svůj server. ## Jak to funguje 1. Přihlásíte se k odběru události [`telephony.incoming`](/cs/webhooks/events) (telefon) nebo [`web.incoming`](/cs/webhooks/events) (widget). Obě jsou **blokující** webhooky: ThunderPhone před pokračováním hovoru čeká na vaši odpověď až 13 sekund u telefonního hovoru (včetně jednoho opakování) a 10 sekund u relace widgetu. 2. ThunderPhone vám odešle `{call_id, from_number, to_number}` (relace widgetu obsahují místo čísel pole specifická pro widget — viz [schéma požadavku](/cs/webhooks/call-incoming)). 3. Váš server odpoví konfigurací agenta (prompt, hlas, produkt, nástroje). ThunderPhone tuto konfiguraci použije pro daný hovor. 4. Neexistuje žádný záložní agent. Pokud vrátíte `{}` nebo neplatnou konfiguraci, nebo požadavek stále selže po [opakování](/cs/webhooks/call-incoming), telefonní hovor se ihned ukončí a zaznamená se s `end_reason` `inbound_config_webhook_failed`; požadavek relace widgetu selže. Funguje shodně pro telefonní hovory (`telephony.incoming`) i relace widgetu (`web.incoming`), bez ohledu na to, zda jsou doručeny do endpointu webhooku nebo do staršího webhooku s jedinou URL. **Při hovorech konfigurovaných pomocí inline webhooku se nepřehrává oznámení o souhlasu ThunderPhone.** Tato cesta obchází oznámení na začátku hovoru na úrovni agenta a je výslovně vyloučena z rámce oznámení o souhlasu ThunderPhone (Podmínky služby, část „Nahrávání a souhlas“). Vaše organizace nese plnou odpovědnost za všechna oznámení a souhlasy týkající se nahrávání, monitorování, účasti AI a identifikace volajícího u těchto hovorů. Poskytněte je ve svém vlastním procesu — například v úvodním skriptu promptu — před povolením inline režimu webhooku. Odpověď webhooku, která odkazuje na uložené `agent_id`, používá běžné zásady nahrávání a zveřejňování informací daného agenta. ## 1. Nakonfigurujte cíl webhooku Pro telefonní čísla přihlaste svůj endpoint k odběru `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"] }' ``` Odpověď obsahuje jednorázový `secret` — uložte jej; použijete ho pro ověření podpisu. Pro relace widgetu vytvořte publikovatelný klíč v `mode="webhook"` s URL endpointu přímo zahrnutou: ```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 bude při každém zahájení relace odesílat POST na tuto URL. ## 2. Implementujte obslužnou funkci Tři základní pravidla: - **Ověřte podpis** u každého požadavku (viz [Ověření podpisů webhooků](/cs/guides/verify-webhook-signatures)). V vývojovém prostředí tento krok nevynechávejte — nastavte jej správně jednou a znovu ho používejte. - **Odpovídejte rychle**. První pokus telefonního hovoru se ukončí po 10 sekundách a celá výměna po 13 sekundách; každá sekunda znamená pro volajícího ticho. V případě potřeby provádějte vyhledávání v databázi, ale nevolejte následné LLM synchronně — pokud chcete dynamicky generovat prompty, předem je vypočítejte a uložte do mezipaměti. - **Použijte čistý záložní postup**. Pro jakýkoli neočekávaný stav odpovězte výchozím `prompt` a `voice` (nebo uloženým `agent_id`). Vrácení `{}` nebo chybového stavu hovor ukončí. ```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 odpovědi Tělo odpovědi přesně odpovídá [schématu odpovědi na příchozí hovor](/cs/webhooks/call-incoming). Běžně používaná pole: | Pole | Typ | Popis | |-------|------|-------------| | `prompt` | řetězec (povinné) | Systémový prompt pro agenta | | `voice` | řetězec (povinné) | ID hlasu z [`GET /v1/voices`](/api-reference/agents#voices) | | `product` | řetězec | Výchozí hodnota je `spark`. Experimentální produkty jsou dostupné pouze pro organizace na seznamu povolených. | | `background_track` | řetězec \| null | ID ambientního zvuku | | `acknowledgement_prompt_mode` | řetězec | `auto` nebo `manual` (pouze Storm s potvrzením) | | `acknowledgement_prompt` | řetězec | Povinné, pokud je režim `manual` | | `tools` | pole | Schémata funkčních nástrojů vložená přímo — viz [Funkční nástroje](/cs/tools/overview) | Pořadí promluv a `max_hold_seconds` pro jednotlivé hovory nejsou v odpovědi webhooku k dispozici. Nastavte je u [agenta](/api-reference/agents), na kterého odkazujete. ### Zachovejte uloženého agenta a dodejte proměnné Vraťte `{"agent_id": 12, "variables": {"name": "Ada"}}`, chcete-li použít uloženého agenta dané organizace s daty pro konkrétní hovor. Jeho výzva může obsahovat `{{name}}` nebo `{{name|Friend}}`. Proměnné webhooku se sloučí s proměnnými na úrovni požadavku; hodnota null použije výchozí hodnotu zástupného symbolu nebo prázdný text, pokud žádná není zadána. Konečné hodnoty a nevyřešené názvy se zobrazí v podrobnostech hovoru a webhookách po dokončení. Odpovědi uloženého agenta přijímají pouze `agent_id`, `variables` a `timezone`. Pokud je přítomen `prompt`, odpověď použije vloženou konfiguraci a ignoruje `agent_id` (včetně hodnot null nebo neceločíselných metadat); vložená výzva musí být stále platná. Odpovědi s vloženou konfigurací mohou také obsahovat `variables`. Odpovědi uloženého agenta používají nasazené A/B rozdělení agenta pro telefonní hovory i hovory z widgetu a poté vykreslí proměnné. Informace o [proměnných hovoru](/cs/guides/call-variables) včetně omezení a podpory rozhraní API relací. Blokující konfigurace pochází ze starší adresy URL telefonního čísla/organizace nebo z klíče widgetu v režimu webhooku; příchozí události systému koncových bodů jsou pouze oznámení. ### Nastavte časové pásmo pro každý hovor Jeden agent může odpovídat kontaktům v různých časových pásmech. Přidejte `timezone`, název IANA, do odpovědi uloženého agenta nebo vložené odpovědi a agent pro tento hovor uvede datum a čas a nabídne termíny v daném pásmu, před časovým pásmem samotného agenta: ```json {"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}} ``` Místo časového razítka v `variables` odešlete pásmo: hodiny agenta během hovoru běží dál a předaný čas zastará. Hodnota, která není pásmem IANA, se ignoruje a hovor se spojí v časovém pásmu agenta. ## Vzory ### Kontext přihlášeného uživatele Ve widgetech v režimu webhooku stránka návštěvníka již ví, kdo návštěvník je. Zavolejte webhook s parametrem řetězce dotazu, který SDK widgetu přeposílá (`?customer_id=123`), a zákazníka vyhledejte na straně serveru. ### Zavádění A/B výzev Než to začnete vytvářet ručně, vezměte na vědomí, že ThunderPhone má nativní funkci [Experimenty](/cs/guides/concepts) (`/dashboard/experiments` a kartu **A/B** v nástroji pro tvorbu agentů), která definuje varianty, rozděluje provoz a porovnává výsledky pro jednotlivé varianty — webhook není potřeba. Pokud přesto potřebujete řízení na straně webhooku: zahashujte `call_id` → segment; pro `0..49` použijte výzvu A a pro `50..99` výzvu B. Zaznamenejte, který segment jste vybrali, do vlastní databáze a později jej propojte s hodnocením dokončeného hovoru. ### Směrování podle času Pracovní doba → agent „živá podpora“; mimo pracovní dobu → agent „přijmout zprávu“. Ve vašem handleru stačí přepnutí podle `new Date().getUTCHours()`. --- ## Další kroky Přesná schémata požadavků a odpovědí včetně všech konfiguračních klíčů. Nastavte HMAC správně jednou a používejte jej všude. Kombinujte dynamické směrování s nástroji pro jednotlivé agenty. Opakované pokusy, řazení, časové limity.