--- title: "telephony.incoming / web.incoming" description: "Blokujúci webhook, ktorý v reálnom čase formuje konfiguráciu prichádzajúceho hovoru." --- Keď prichádzajúci telefonát dorazí na číslo **bez priradeného agenta** alebo sa relácia webového widgetu spustí na verejnom kľúči v režime `mode="webhook"`, ThunderPhone odošle **blokujúcu** požiadavku `telephony.incoming` / `web.incoming` na vašu [staršiu URL webhooku](/api-reference/organizations#legacy-single-url-webhook) a na odpoveď s konfiguráciou čaká až **10 sekúnd**. Túto výmenu použite na dynamický výber výzvy, hlasu a nástrojov pre každý hovor — kompletný postup nájdete v [sprievodcovi dynamickou konfiguráciou hovorov](/sk/guides/dynamic-call-config). Prihlásené [koncové body webhookov](/sk/webhooks/endpoints) tiež prijímajú `telephony.incoming` / `web.incoming` — pre **každý** prichádzajúci hovor a webovú reláciu, bez ohľadu na konfiguráciu agenta — tieto doručenia sú však oznámenia bez čakania s hodnotou `event_id`, nikdy nie blokujúce. Konfiguračnú výmenu na tejto stránke prenáša iba starší webhook s jednou URL. Formáty oznámení koncových bodov nájdete v [katalógu udalostí](/sk/webhooks/events). Blokujúca výmena nemá náhradné riešenie: ak váš obslužný program vráti stav iný než 2xx, vyprší časový limit alebo vráti konfiguráciu, ktorá neprejde overením, hovor sa odmietne (telefonát sa nespojí; požiadavka na reláciu widgetu zlyhá s `502`/`422`). Odpovedzte rýchlo — volajúci počas vášho rozhodovania počuje vyzváňací tón. **Hovory konfigurované webhookom neobsahujú oznámenie o súhlase ThunderPhone.** Hovory konfigurované prostredníctvom tejto výmeny obchádzajú oznámenie na začiatku hovoru na úrovni agenta a sú 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 je výhradne zodpovedná za každé oznámenie a súhlas týkajúce sa nahrávania, monitorovania, účasti AI a identifikácie volajúceho, ktoré sú pri týchto hovoroch vyžadované — hovory možno stále nahrávať, prepisovať, analyzovať a obsluhovať pomocou AI. Pred povolením tejto možnosti zapracujte požadované oznámenia do vlastného toku hovoru. ## Telo požiadavky Pre telefonáty (`telephony.incoming`): ```json { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` | Pole | Typ | Popis | |-------|------|-------------| | `call_id` | celé číslo | ID hovoru — nemenné vo všetkých udalostiach tohto hovoru | | `from_number` | reťazec | Číslo volajúceho vo formáte E.164 | | `to_number` | reťazec | Cieľ vo formáte E.164 (jedno z vašich čísel ThunderPhone) | Pre relácie webového widgetu (`web.incoming`) identifikuje `data` namiesto telefónnych čísel stránku s vloženým widgetom: ```json { "type": "web.incoming", "data": { "call_id": 987654322, "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2" } } ``` | Pole | Typ | Popis | |-------|------|-------------| | `call_id` | celé číslo | ID hovoru | | `origin_domain` | reťazec | Pôvod stránky hostujúcej widget | | `publishable_key_prefix` | reťazec | Prvé znaky verejného kľúča, ktorý otvoril reláciu | | `language`, `primary_language` | reťazec | Prítomné, keď relácia widgetu vyžiadala prepísanie jazyka | | `voice` | reťazec | Prítomné, keď relácia widgetu vyžiadala prepísanie hlasu | | `website_context` | reťazec | Prítomné, keď widget odovzdal kontext stránky pre jednotlivú reláciu | Widgety v režime webhooku doručujú túto požiadavku na vlastnú `webhook_url` verejného kľúča, ak je nastavená; inak použijú URL webhooku na úrovni organizácie. V oboch prípadoch je podpísaná webhookovým `secret` organizácie. --- ## Schéma odpovede Vráťte objekt JSON popisujúci konfiguráciu agenta pre tento hovor. `prompt` a `voice` sú povinné; všetko ostatné je voliteľné. ```json { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | Pole | Typ | Povinné | Popis | |-------|------|----------|-------------| | `prompt` | string | áno | Systémový prompt riadiaci agenta | | `voice` | string | áno | ID hlasu z [`GET /v1/voices`](/api-reference/agents#voices), napr. `john`. `voice_name` je akceptovaný ako alias. Neznáme hlasy neprejdú overením a hovor sa odmietne | | `product` | string | nie | Predvolene `spark`. Povolené: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | string | nie | `minimal`, `base` (predvolené) alebo `extra`. Pre produkty Storm sa prepíše: `storm-extra*` vynúti `extra`, ostatné `storm-*` vynútia `base` | | `audio_context_mode` | string | nie | `full` (predvolené) alebo `reduced` | | `watchdog_enabled` | boolean | nie | Povolí dohľad pre tento hovor. Predvolené `false` | | `additional_audio_context` | boolean \| null | nie | Zahrnie posledných niekoľko ťahov zvuku volajúceho namiesto iba najnovšieho ťahu, čím zlepší opravy a zhromažďovanie údajov náročných na hláskovanie/čísla za cenu mierne vyššej latencie a nákladov. Pre prichádzajúce relácie je predvolene zapnuté a pre odchádzajúce telefonické hovory vypnuté; `null` zachová predvolené nastavenie | | `storm_feedback_mode` | string | nie | `none`, `acknowledgement` (predvolené) alebo `tick` | | `language` | string | nie | Skrátený zápis pre `primary_language` | | `primary_language` | string | nie | Kód jazyka, normalizovaný (predvolené `en`). Nerozpoznateľné kódy sa pri hovore odmietnu | | `has_additional_languages` | boolean | nie | Predvolené `false` | | `additional_languages` | array of string | nie | Ďalšie jazyky, na ktoré môže agent prepnúť | | `native_voice_switching` | boolean | nie | Predvolené `false`. Keď hovor prepne do iného jazyka, namiesto zachovania nakonfigurovaného hlasu sa použije hlas prirodzený pre daný jazyk (zodpovedajúci rodu) | | `background_track` | string \| null | nie | ID zvuku prostredia alebo `null` | | `acknowledgement_prompt_mode` | string | nie | `auto` (predvolené) alebo `manual` (produkty Storm s potvrdením) | | `acknowledgement_prompt` | string | nie | Používa sa, keď `acknowledgement_prompt_mode="manual"` | | `silence_interval_seconds` | integer \| null | nie | 5–120. Sekundy ticha volajúceho pred kontrolným oslovením | | `silence_max_checkins` | integer \| null | nie | 1–10 | | `silence_checkins_enabled` | boolean | nie | Predvolené `true` | | `connect_tone_enabled` | boolean | nie | Predvolené `false` | | `voicemail_action` | string | nie | `prompt` (predvolené), `hangup` alebo `message` | | `voicemail_message` | string | nie | Používa sa, keď `voicemail_action="message"` | | `agent_name` | string | nie | Zobrazovaný názov uvádzaný na paneloch a vo widgete | | `org_name` | string | nie | Zobrazovaný názov organizácie pre personu agenta | | `tools` | array | nie | Vložené schémy funkčných nástrojov (pozrite si [Funkčné nástroje](/sk/tools/overview)) | | `call_id` | integer | nie | Voliteľné zopakovanie ID hovoru požiadavky; ignoruje sa | Neznáme kľúče najvyššej úrovne sa potichu **ignorujú** — pole s preklepom v názve konfiguráciu neodmietne, iba sa nepoužije. Poradie hovorenia a `max_hold_seconds` tu nie sú akceptované; konfigurovať ich môžete iba priamo v [Agentovi](/api-reference/agents). Keďže `prompt` a `voice` sú povinné, vrátenie `{}` alebo akejkoľvek odpovede, ktorá neprejde overením, odmietne hovor s kódom `422` — na tejto ceste neexistuje záložný statický agent (číslo alebo kľúč v režime webhook nemá priradeného agenta). --- ## Limit veľkosti odpovede Odpovede konfigurácie sú obmedzené na **5 MiB**. Ak obslužná funkcia vráti väčšiu odpoveď, a to aj so stavom `2xx`, ThunderPhone oznámi, že odpoveď prekročila limit, a odmietne hovor alebo reláciu widgetu. V odpovedi ponechajte iba polia potrebné na nastavenie hovoru; veľké údaje hostujte za funkčnými nástrojmi alebo inou službou namiesto ich vloženia do konfigurácie. --- ## Príklad obslužnej funkcie ```python Python (FastAPI) import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, signature: str) -> bool: expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature or "") @app.post("/thunderphone-webhook") async def webhook(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(status_code=401) event = json.loads(body) if event["type"] == "telephony.incoming": caller = event["data"]["from_number"] prompt = ( "Greet the caller as a San Francisco local…" if caller.startswith("+1415") else "You are a friendly customer support agent…" ) return { "prompt": prompt, "voice": "john", "product": "spark", } if event["type"] == "web.incoming": return { "prompt": "You are the website's helpful voice assistant…", "voice": "john", "product": "spark", } return {} ``` ```javascript Node.js (Express) import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, signature) { const expected = crypto .createHmac("sha256", SECRET) .update(body) .digest("hex"); return signature && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } app.post( "/thunderphone-webhook", express.raw({ type: "application/json" }), (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); if (event.type === "telephony.incoming" || event.type === "web.incoming") { const caller = event.data.from_number || "web"; const prompt = caller.startsWith("+1415") ? "Greet the caller as a San Francisco local…" : "You are a friendly customer support agent…"; return res.json({ prompt, voice: "john", product: "spark", }); } res.json({}); }, ); ``` --- ## Odpoveď s funkčnými nástrojmi Pripojte nástroje, aby AI mohla počas konverzácie volať vaše API: ```json { "prompt": "You are a booking assistant. Use the available tools to help customers schedule appointments.", "voice": "john", "product": "spark", "tools": [ { "type": "function", "function": { "name": "search_appointments", "description": "Find available appointment slots", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" }, "service": { "type": "string" } }, "required": ["date"] } }, "endpoint": { "url": "https://api.example.com/appointments/search", "method": "POST", "headers": { "X-Api-Key": "your-key" } } } ] } ``` Požiadavky na koncové body nástrojov sú podpísané tým **istým tajomstvom webhooku organizácie**, ktorým bola podpísaná táto výmena. Presný tvar a formát podpísanej požiadavky nájdete v časti [Funkčné nástroje](/sk/tools/overview). --- ## Prehľad produktových úrovní | Produkt | Latencia | Uvažovanie | Potvrdenie | |---------|---------|-----------|-----------------| | `spark` | Najnižšia | Základné | — | | `bolt` | Nízka | Vylepšené | — | | `storm-base` | Stredná | Silné | — | | `storm-base-with-ack` | Stredná | Silné | Automatická výplň počas uvažovania | | `storm-extra` | Vyššia | Hlboké | — | | `storm-extra-with-ack` | Vyššia | Hlboké | Automatická výplň počas uvažovania | --- ## Súvisiace Neblokujúca udalosť ukončenia hovoru. Úplná schéma JSON pre `tools[]` a kontrakt podpisovaného koncového bodu. Prihláste viacero adries URL na odber udalostí `telephony.incoming` / `web.incoming`. Vzory pre výzvy, nástroje a A/B testy pre jednotlivých volajúcich.