--- title: "telephony.incoming / web.incoming" description: "Blokkoló webhook, amely valós időben alakítja a bejövő hívás konfigurációját." --- Amikor egy bejövő telefonhívás egy **hozzárendelt AI-ügynök nélküli** számot ér el, vagy egy webes widget-munkamenet egy közzétehető kulcson indul `mode="webhook"` módban, a ThunderPhone **blokkoló** `telephony.incoming` / `web.incoming` kérést küld az Ön [régi webhook URL-címére](/api-reference/organizations#legacy-single-url-webhook), és konfigurációs válaszra vár: telefonhívás esetén legfeljebb **13 másodpercig**, egy újrapróbálkozást is beleértve, widget-munkamenet esetén pedig legfeljebb **10 másodpercig** (lásd: [Időtúllépések és újrapróbálkozások](#timeouts-and-retries)). Ezzel a kommunikációval hívásonként dinamikusan választhat promptot, hangot és eszközöket — a teljes körű mintáért lásd a [dinamikus híváskonfiguráció útmutatóját](/hu/guides/dynamic-call-config). A feliratkozott [webhook-végpontok](/hu/webhooks/endpoints) is megkapják a `telephony.incoming` / `web.incoming` eseményeket — **minden** bejövő hívás és webes munkamenet esetében, függetlenül attól, hogy van-e ügynökkonfiguráció — de ezek a kézbesítések `event_id` azonosítót tartalmazó, nem blokkoló, indítás utáni értesítések. Az ezen az oldalon ismertetett konfigurációs cserét kizárólag a régi egyetlen URL-es webhook végzi. A végpontértesítések formátumát az [eseménykatalógusban](/hu/webhooks/events) találja. ## Időtúllépések és újrapróbálkozások Válaszoljon gyorsan: a hívó a vonalban vár, amíg Ön dönt. Telefonhívás esetén (`telephony.incoming`): - Az első kísérlet legfeljebb **10 másodpercig** tarthat. - Ha időtúllépés történik, nem sikerül kapcsolódni, vagy `5xx`, `408` vagy `429` választ kap, a ThunderPhone még egyszer megpróbálja. Az újrapróbálkozás a teljes műveletre rendelkezésre álló **13 másodperces** időkeretből fennmaradó időt kapja: egy időtúllépéssel végződő első kísérlet után körülbelül 3 másodpercet, gyors hiba után pedig majdnem mind a 13 másodpercet. Nincs újrapróbálkozás, ha kevesebb mint 2 másodperc maradna. - Bármely egyéb `4xx` válasz, a [méretkorlátot](#response-size-limit) meghaladó válasz, illetve olyan `2xx` válasz, amelynek törzse nem érvényes konfiguráció, végleges, és nincs újrapróbálkozás. - Mindkét kísérlet ugyanazt a törzset, ugyanazt az `X-ThunderPhone-Signature` és ugyanazt az `X-ThunderPhone-Idempotency-Key` fejlécet küldi (`telephony-incoming-`), így a mellékhatásokat végrehajtó kezelő felismerheti az újrapróbálkozást. Nincs tartalék ügynök. Ha nem érkezik használható konfiguráció, a hívás azonnal befejeződik ahelyett, hogy a hívó néma vonalban várakozna. A híváselőzményekben sikertelen, számlázatlan hívásként jelenik meg `end_reason` `inbound_config_webhook_failed` értékkel, és a szokásos [`telephony.complete`](/hu/webhooks/call-complete) esemény elküldésre kerül. Egy widgetmunkamenet (`web.incoming`) esetében egyetlen, legfeljebb 10 másodpercig tartó kísérlet történik. Ha ez sikertelen, a munkamenet-kérés `502` vagy `422` hibával meghiúsul. **A webhookkal konfigurált hívásokhoz nem tartozik ThunderPhone hozzájárulási tájékoztató.** Az ezen a cserén keresztül konfigurált hívások megkerülik az ügynökszintű hívásindítási tájékoztatót, és kifejezetten nem tartoznak a ThunderPhone hozzájárulási tájékoztatási keretrendszerébe (Szolgáltatási feltételek, „Rögzítés és hozzájárulás” szakasz). Az Ön szervezete kizárólagosan felelős az ezekhez a hívásokhoz szükséges minden rögzítési, megfigyelési, AI-részvételi és hívóazonosítási tájékoztatásért és hozzájárulásért — a hívások továbbra is rögzíthetők, átírhatók, elemezhetők és AI által kezelhetők. Mielőtt engedélyezné ezt az útvonalat, építse be a szükséges tájékoztatásokat saját hívásfolyamatába. ## Kérés hasznos adatai Telefonhívásokhoz (`telephony.incoming`): ```json { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` | Mező | Típus | Leírás | |-------|------|-------------| | `call_id` | integer | Hívásazonosító — a hívás minden eseményében változatlan | | `from_number` | string | A hívó E.164-es száma | | `to_number` | string | E.164-es célállomás (az Ön egyik ThunderPhone-száma) | Webes widgetmunkameneteknél (`web.incoming`) a `data` telefonos számok helyett a beágyazó oldalt azonosítja: ```json { "type": "web.incoming", "data": { "call_id": 987654322, "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2" } } ``` | Mező | Típus | Leírás | |-------|------|-------------| | `call_id` | integer | Hívásazonosító | | `origin_domain` | string | A widgetet tároló oldal eredete a böngésző által elküldött formában. Nem böngészős kliens bármilyen értéket küldhet, ezért ne tekintse bizonyítéknak arra, honnan érkezett a kérés | | `publishable_key_prefix` | string | A munkamenetet megnyitó publikálható kulcs első karakterei | | `language`, `primary_language` | string | Akkor van jelen, ha a widget munkamenete nyelvi felülbírálást kért | | `voice` | string | Akkor van jelen, ha a widget munkamenete hangfelülbírálást kért | | `website_context` | string | Akkor van jelen, ha a widget munkamenete munkamenetenkénti oldalkontextust adott át | A felülbírálási mezők (`language`, `voice`, `website_context` és bármely böngészőbeli `variables`) csak akkor érkeznek meg, ha a publikálható kulcs engedélyezi őket a [böngészőfelülbírálásokban](/hu/guides/embed-web-widget). Az olyan munkamenetkérést, amely a kulcs által nem engedélyezett felülbírálást tartalmaz, a rendszer elutasítja, mielőtt ezt a webhookot meghívná. Webhook módú widgetek ezt a kérést a közzétehető kulcs saját `webhook_url` címére küldik, ha az be van állítva, egyébként a szervezeti szintű webhook-URL-re. Mindkét esetben a szervezeti webhook `secret` értékével van aláírva. --- ## Válaszséma Adjon vissza egy JSON-objektumot, amely leírja az ügynök konfigurációját ehhez a híváshoz. A `prompt` és a `voice` kötelező; minden más opcionális. ```json { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | Mező | Típus | Kötelező | Leírás | |-------|------|----------|-------------| | `prompt` | string | igen | Az ügynököt vezérlő rendszerprompt | | `voice` | string | igen | Hangazonosító a [`GET /v1/voices`](/api-reference/agents#voices) végpontból, például `john`. A `voice_name` aliasként is elfogadott. Az ismeretlen hangok nem felelnek meg az ellenőrzésnek, és a hívás elutasításra kerül | | `product` | string | nem | Alapértelmezett értéke: `spark`. Engedélyezett értékek: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | string | nem | `minimal`, `base` (alapértelmezett) vagy `extra`. Storm termékeknél felülíródik: a `storm-extra*` az `extra` értéket kényszeríti, a többi `storm-*` a `base` értéket | | `audio_context_mode` | string | nem | `full` (alapértelmezett) vagy `reduced` | | `watchdog_enabled` | boolean | nem | Felügyelet engedélyezése ehhez a híváshoz. Alapértelmezett érték: `false` | | `additional_audio_context` | boolean \| null | nem | A hívó hanganyagának utolsó néhány megszólalását is tartalmazza a legutóbbi megszólalás helyett, ami kis késleltetési- és költségtöbblet mellett javítja a javításokat, valamint a betűzés- és számigényes adatgyűjtést. Bejövő munkameneteknél alapértelmezetten be van kapcsolva, kimenő telefonhívásoknál ki van kapcsolva; a `null` megtartja az alapértelmezett értéket | | `storm_feedback_mode` | string | nem | `none`, `acknowledgement` (alapértelmezett) vagy `tick` | | `language` | string | nem | A `primary_language` rövidítése | | `primary_language` | string | nem | Nyelvkód, normalizálva (alapértelmezett: `en`). A nem feloldható kódok elutasítják a hívást | | `has_additional_languages` | boolean | nem | Alapértelmezett érték: `false` | | `additional_languages` | array of string | nem | További nyelvek, amelyekre az ügynök átválthat | | `native_voice_switching` | boolean | nem | Alapértelmezett érték: `false`. Amikor a hívás másik nyelvre vált, a beállított hang megtartása helyett az adott nyelvhez anyanyelvi hangra vált (nem alapján egyeztetve) | | `language_switching` | string \| null | nem | `ask_first` (alapértelmezett) vagy `follow_caller`; a `null` megegyezik az `ask_first` értékkel. Meghatározza, hogyan kezeli a többnyelvű ügynök, ha a másik fél az egyik másik nyelvén beszél. Az `ask_first` azonnal vált, amikor a hívó kéri a nyelvet, vagy teljes mondatot mond rajta, rövid megszólalás, például egy „igen” után pedig megkérdezi, hogy folytassák-e azon a nyelven. A `follow_caller` bármely beállított nyelvre vált, amelyet a hívó beszél, akár egyetlen szó esetén is. Csak akkor érvényes, ha az `additional_languages` be van állítva | | `background_track` | string \| null | nem | Környezeti hang azonosítója vagy `null` | | `acknowledgement_prompt_mode` | string | nem | `auto` (alapértelmezett) vagy `manual` (Storm-with-ack termékeknél) | | `acknowledgement_prompt` | string | nem | Akkor használatos, ha az `acknowledgement_prompt_mode="manual"` | | `silence_interval_seconds` | integer \| null | nem | 5–120. A hívó csendjének másodpercei, mielőtt az ügynök rákérdez | | `silence_max_checkins` | integer \| null | nem | 1–10 | | `silence_checkins_enabled` | boolean | nem | Alapértelmezett érték: `true` | | `connect_tone_enabled` | boolean | nem | Alapértelmezett érték: `false` | | `pronunciation_dicts` | boolean \| null | nem | Alapértelmezett érték: `false`; a `null` megegyezik a `false` értékkel. Ha `true`, a hívás Cartesia beszédhangja a ThunderPhone kiejtési szótárát használja a hívás nyelvéhez, ahol elérhető. Telefonos és widgetes hívásoknál is működik. Csak a ThunderPhone saját Cartesia hangjaira vonatkozik, a saját Cartesia API-kulcsán lévő hangokra nem. `agent_id` használatakor nem érvényes, ekkor a mentett ügynök beállításai érvényesek | | `voicemail_action` | string | nem | `prompt` (alapértelmezett), `hangup` vagy `message` | | `voicemail_message` | string | nem | Akkor használatos, ha a `voicemail_action="message"` | | `agent_name` | string | nem | Az irányítópultokon és a widgetben megjelenített név | | `org_name` | string | nem | Az ügynök személyiségéhez tartozó szervezet megjelenített neve | | `tools` | array | nem | Beágyazott függvényeszköz-sémák (lásd: [Függvényeszközök](/hu/tools/overview)) | | `transfer_destinations` | array of object \| null | nem | Legfeljebb 50 `{name, number}` bejegyzés, amelyekre ez a hívás átirányítható, és amelyek ellenőrzése ugyanúgy történik, mint egy ügynök [átirányítási számai](/api-reference/agents#transfer-numbers) esetén. Az ügynök név alapján és csak ezekre irányít át; a `[]` azt jelenti, hogy nincs átirányítás. Hagyja ki, vagy küldjön `null` értéket, hogy az ügynök az általa választott számra irányíthasson át | | `timezone` | string | nem | A hívás IANA időzónája, például `America/Chicago`. Az ügynök ebben adja meg a dátumot és az időt, az ügynök saját időzónája helyett. Az `agent_id` mellett is engedélyezett. Azok az értékek, amelyek nem IANA időzónák, figyelmen kívül maradnak. Lásd: [Időzóna beállítása hívásonként](/hu/guides/dynamic-call-config) | | `call_id` | integer | nem | A kérés hívásazonosítójának opcionális visszhangja; figyelmen kívül marad | Az ismeretlen legfelső szintű kulcsok csendben **figyelmen kívül maradnak** — egy elgépelt mezőnév nem utasítja el a konfigurációt, csak nem kerül alkalmazásra. A Speak-order és a `max_hold_seconds` itt nem elfogadott; csak magán az [Ügynökön](/api-reference/agents) konfigurálhatók. Mivel a `prompt` és a `voice` kötelező, a `{}` vagy bármely, az ellenőrzésen megbukó válasz elutasítja a hívást: a telefonhívás a [Időtúllépések és újrapróbálkozások](#timeouts-and-retries) című részben leírtak szerint megszakad, a widget-munkamenet kérése pedig `422` hibával meghiúsul. Ezen az útvonalon nincs statikus ügynökes visszaesés (webhook módban egy számhoz vagy kulcshoz nincs ügynök hozzárendelve). --- ## Válaszméret-korlát A konfigurációs válaszok mérete legfeljebb **5 MiB** lehet. Ha egy kezelő ennél nagyobb választ ad vissza, akár `2xx` állapotkóddal is, a ThunderPhone jelzi, hogy a válasz túllépte a korlátot, és elutasítja a hívást vagy a widget-munkamenetet. A válasz csak a hívás beállításához szükséges mezőket tartalmazza; a nagy méretű adatokat funkcióeszközök vagy más szolgáltatás mögött tárolja ahelyett, hogy beágyazná őket a konfigurációba. --- ## Példakezelő ```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({}); }, ); ``` --- ## Válasz funkcióeszközökkel Csatoljon eszközöket, hogy az AI a beszélgetés közben meghívhassa az API-jait: ```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" } } } ] } ``` Az eszközvégpont-kérések aláírásához ugyanazt a **szervezeti webhooktitkot** használja a rendszer, amely ezt a cserét is aláírta. A pontos struktúrát és az aláírt kérésformátumot a [Funkcióeszközök](/hu/tools/overview) oldalon találja. --- ## Termékszint áttekintő | Termék | Késleltetés | Érvelés | Visszaigazolás | |---------|---------|-----------|-----------------| | `spark` | Legalacsonyabb | Alapszintű | — | | `bolt` | Alacsony | Fejlettebb | — | | `storm-base` | Közepes | Erős | — | | `storm-base-with-ack` | Közepes | Erős | Automatikus kitöltő szöveg gondolkodás közben | | `storm-extra` | Magasabb | Mélyreható | — | | `storm-extra-with-ack` | Magasabb | Mélyreható | Automatikus kitöltő szöveg gondolkodás közben | --- ## Kapcsolódó A hívás végét jelző, nem blokkoló esemény. A `tools[]` teljes JSON-sémája és az aláírt végpont szerződése. Több URL feliratkoztatása a `telephony.incoming` / `web.incoming` eseményekre. Minták hívónkénti prompthoz, eszközökhöz és A/B tesztekhez.