--- title: "telephony.complete / web.complete" description: "Nem blokkoló webhook, amely a hívás befejeződésekor érkezik, átirattal, felvételi URL-lel és mérőszámokkal." --- Minden hívás befejezése után befejezési esemény aktiválódik — bejövő telefonhívás, kimenő telefonhívás, webes hívás vagy teszthívás (a szerkesztő mikrofonos munkamenete) esetén. Ez **nem blokkoló**: válaszoljon bármely 2xx kóddal. Az esemény mindkét útvonalon kézbesítésre kerül: * **A [webhook-végpontok](/hu/webhooks/endpoints)** a `telephony.complete` (telefonhívások) vagy a `web.complete` (webes hívások és a szerkesztő mikrofonos teszthívásai) eseményt kapják meg az alább dokumentált stabil payload-dal, kézbesítésenkénti `event_id` azonosítóval, 30 másodperces időtúllépéssel és [legfeljebb 24 órán át tartó újrapróbálkozásokkal](/hu/webhooks/overview). * **A [régi, egyetlen URL-es webhook](/api-reference/organizations#legacy-single-url-webhook)** egy szinkron próbálkozást kap (10 másodperces időtúllépés, újrapróbálkozás nélkül), kissé eltérő payload-dal — lásd: [A régi payload eltérései](#legacy-payload-differences). ## Kérelemtörzs (végpontkézbesítések) ```json { "data": { "billable_minutes": 1.25, "billing_total_cents": 8, "call_id": 987654321, "direction": "inbound", "duration_seconds": 54, "end_reason": "user_hangup", "end_time": "2026-04-20T18:25:04.822Z", "extracted_data": { "status": "completed", "fields": { "customer_name": "Alex Morgan", "appointment_date": "2026-04-23" }, "evidence": { "customer_name": { "quote": "My name is Alex Morgan", "speaker_role": "caller", "turn_index": 4 }, "appointment_date": { "quote": "April 23 works for me", "speaker_role": "caller", "turn_index": 7 } }, "verification": "verified", "field_reasons": {}, "schema_version": "92850758e231a3c95a..." }, "from_number": "+14155550199", "product": "spark", "recording_url": "https://storage.example.com/…", "start_time": "2026-04-20T18:24:10.113Z", "status": "completed", "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23. The agent read the appointment back and Alex asked for a reminder text the day before.", "to_number": "+15551234567", "transcripts": [ /* see Transcript format */ ], "transfer_number": null, "unresolved_variables": ["campaign_owner"], "variables": {"campaign_name": "Spring renewals"}, "voice": "john" }, "event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d", "type": "telephony.complete" } ``` | Mező | Típus | Leírás | |-------|------|-------------| | `call_id` | integer | Stabil az adott hívás minden eseményében | | `agent_id` | integer \| null | A hívást kezelő ügynök, ha volt hozzárendelve | | `agent_name` | string \| null | A hívást kezelő ügynök, ha volt hozzárendelve | | `direction` | string | `inbound`, `outbound`, `web`, `test`. A korábbi payloadok örökölt `mic` vagy `widget` értékeket tartalmazhatnak | | `from_number`, `to_number` | string | E.164. A `from_number` webes és teszthívásoknál szó szerint `"web"` | | `origin_domain` | string | **Csak web/teszt** — a widgetet hosztoló oldal eredete (mikrofonos munkameneteknél üres) | | `start_time`, `end_time` | timestamp | ISO 8601 UTC | | `duration_seconds` | integer \| null | A kezdési/befejezési időből származtatva | | `status` | string | `completed` vagy `failed` | | `end_reason` | string | Lásd az alábbi táblázatot | | `product`, `voice` | string | A hívás időpontjában érvényes ügynökkonfiguráció | | `variables` | object | A hívás indulásakor rögzített bemeneti változók | | `unresolved_variables` | array | A hívás konfigurációjában hivatkozott, de a hívás indításakor meg nem adott változónevek | | `transfer_number` | string \| null | Be van állítva, amikor a hívást átirányították | | `recording_url` | string \| null | Lejáró, aláírt URL; töltse le mielőbb. `null`, ha nem érhető el hangfelvételi lelet | | `billable_minutes` | number | Számlázott percek, a legközelebbi negyed percre kerekítve (15 másodperces lépésekben, legalább 0,25). A közvetlenül hangpostára irányított hívások itt továbbra is a ténylegesen mért perceket jelentik, de a díj a csomag díjszabása szerint legfeljebb egy percre korlátozódik. | | `billing_total_cents` | integer | USD-cent | | `transcripts` | array | Fordulónkénti átiratbejegyzések; üres lehet, ha nem érhető el átirat | | `summary` | string \| null | Egyszerű nyelvű, hívás utáni összefoglaló (két-négy mondatnyi próza, legfeljebb 2 000 karakter, a hívás nyelvén: az ügynök elsődleges nyelvén, kivéve ha a hívás felülírta azt), amikor az ügynöknél az ügynökszerkesztő **Begyűjtendő adatok** részében be van kapcsolva a **Hívás-összefoglaló létrehozása** opció (`call_summary_enabled` az [Ügynök](/api-reference/agents) esetében), és a generálás sikeres volt; egyébként `null`, beleértve az összefoglaláshoz túl rövid hívásokat, az átirat nélküli hívásokat és a kikapcsolt felvételkészítésű ügynököket. Az összefoglaló a kinyeréssel azonos, hívás utáni lépésben készül, ezért a **Várakozás a kinyert adatokra a hívás befejezéséről szóló webhook elküldése előtt** beállítás (`extraction_blocks_completion`) határozza meg, hogy ez az esemény megvárja-e: várakozási módban az összefoglaló az esemény elküldése előtt elkészül (maga az összefoglaló legfeljebb 30 másodpercet kaphat a lépés 75 másodperces keretén belül); amikor az esemény nem vár (`never`, vagy `except_transfers` szerinti átirányítás esetén), ez a mező `null`, és az összefoglaló **nem** kerül újraküldésre a `call.data_extracted` eseményben, ezért később a [Hívásobjektum](/api-reference/calls#call-object) `summary` mezőjéből olvassa ki. A vezérlőpult hívásoldalán is elérhető | | `extracted_data` | object \| null | Strukturált kinyerési eredmény a következőkkel: `status`, `fields`, `evidence`, `verification`, `field_reasons` és `schema_version`. Minden nem null mező tartalmazza a pontos, szerkezetileg ellenőrzött idézetet (legfeljebb 1 000 karakter), valamint a beszélő szerepét és a forduló indexét; a modell által visszaadott hosszabb idézeteket elutasítjuk, nem csonkoljuk. Az evidence értéke `null`, ha a mező értéke `null`. A `verified` azt jelenti, hogy minden jelölt pontosan egy érvényes, független értékelést kapott. Az `unavailable` a hibásan formázott vagy részleges ellenőrzői kimenetet is lefedi; az érvényes részleges értékelések továbbra is alkalmazásra kerülnek, míg az egy érvényes értékelés nélküli jelöltek értéke null lesz. A `status` értéke `completed`, `failed`, `exhausted`, `skipped` vagy `skipped_recording_disabled`; `null`, ha az ügynöknek nem voltak kinyerési mezői | ### Befejezési okok | Érték | Jelentés | |-------|---------| | `user_hangup` | A távoli fél bontotta először a hívást | | `ai_hangup` | Az AI szándékosan befejezte a hívást | | `ai_transfer` | Az AI átirányította a hívást; a `transfer_number` be van állítva | | `ai_warm_transfer` | Az AI sikeresen végrehajtott egy meleg (felügyelt) átirányítást | | `voicemail_hangup` | Hangpostát észleltünk, és a hívás az Ön `voicemail_action` beállítása szerint véget ért | | `max_duration` | A hívás elérte a maximális időtartamkorlátot | | `superseded` | A munkamenetet egy újabb váltotta fel | | `unknown` | A befejezési okot nem sikerült meghatározni | ## Átirat formátuma A `transcripts` minden bejegyzése egy társalgási forduló. A szerepkörök: `user` (a hívó beszéde), `model` (az ügynök beszéde **és** eszközhívások), `tool` (eszközeredmények), valamint `system` (hívási események, például nyelvváltások). ```json [ { "role": "user", "content_type": "text/plain", "content": "Hi, I'm calling about my appointment.", "start_ms": 1200, "end_ms": 4100, "audio_url": "https://storage.example.com/…" }, { "role": "model", "content_type": "text/plain", "content": "Sure, what date works best?", "start_ms": 4200, "end_ms": 6100 }, { "role": "model", "content_type": "application/json", "content": { "tool_call": "search_appointments", "arguments": { "date": "2026-04-21" } } }, { "role": "tool", "content_type": "application/json", "content": { "tool_name": "search_appointments", "response": { "available_slots": ["9:00 AM", "2:00 PM"] } } } ] ``` | Mező | Típus | Leírás | |-------|------|-------------| | `role` | string | `user`, `model`, `tool` vagy `system` | | `content_type` | string | `text/plain` beszédhez; `application/json` eszközhívásokhoz, eszközeredményekhez és rendszereseményekhez | | `content` | string \| object | Beszédszöveg vagy a fent látható strukturált objektum. Eszközhívások: `{"tool_call": name, "arguments": {…}}`. Eszközeredmények: `{"tool_name": name, "response": {…}}` | | `start_ms`, `end_ms` | integer | Eltolás a hívás kezdetétől, ms-ban. Akkor szerepel, ha az időzítés ismert | | `ttfa_ms` | integer | A mért első hangig eltelt idő egy `model` fordulónál | | `audio_url`, `audio_urls` | string / array | Lejáró aláírt URL-ek a forduló hanganyagához, ha a rögzítés fordulónként történt | A teljesen strukturált fordulóelőzményekhez (megszakításjelölőkkel, visszaigazolási kérésekkel és nyers pozíciókkal) használja a [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history) végpontot. ## Régi hasznos teher különbségei A régi, egyetlen URL-t használó webhook boríték formátuma: `{"type": "telephony.complete" | "web.complete", "data": {…}}`, amely **nem tartalmaz `event_id` értéket**, és a `data` mezője eltér a végpont hasznos terhétől: A régi befejezési hasznos teher `agent_id` és `agent_name` mezőt is tartalmaz. * A fordulótömb a **`history`** alatt található, nem a `transcripts` alatt (a fentiekkel azonos fordulósémával). * A mezőkészlet a nyers hívásvégi jelentés, és a fenti táblázatban szereplőkön kívül további belső mezőket is tartalmazhat — az ismeretlen mezőket kezelje tájékoztató jellegűként. * A webes hívások (`direction: "web"`) **nem tartalmaznak** `from_number` / `to_number` mezőt, és `origin_domain` mezőt adnak hozzá. * A Builder mikrofonteszt-hívások a régi útvonalon `telephony.complete` értékkel jelentkeznek (a végpont rendszere ezeket `web.complete` értékre képezi le). * **Átadás koordinálása:** amikor egy hívás átadással végződik, a régi webhook szinkron módon fut le, és `{"transfer_ready": false}` választ adhat annak jelzésére, hogy az átadás célpontja még nem áll készen. Bármely más válasz (vagy a régi webhook hiánya) lehetővé teszi az átadás folytatását. A végponti kézbesítéseket ehhez soha nem veszi figyelembe a rendszer. --- ## Példakezelő ```python 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, signature: str) -> bool: expected = hmac.new(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"] in ("telephony.complete", "web.complete"): data = event["data"] # Endpoint deliveries use "transcripts"; the legacy webhook uses "history". turns = data.get("transcripts") or data.get("history") or [] await persist_call_record( call_id=data["call_id"], turns=turns, recording_url=data.get("recording_url"), ) if data["end_reason"] in ("ai_transfer", "ai_warm_transfer"): await notify_team(data.get("transfer_number"), data["call_id"]) return {"ok": True} ``` ```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" }), async (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); if (["telephony.complete", "web.complete"].includes(event.type)) { const data = event.data; // Endpoint deliveries use "transcripts"; the legacy webhook uses "history". const turns = data.transcripts ?? data.history ?? []; await persistCallRecord({ ...data, turns }); if (["ai_transfer", "ai_warm_transfer"].includes(data.end_reason)) { await notifyTeam(data.transfer_number, data.call_id); } } res.json({ ok: true }); }, ); ``` --- ## Gyakori felhasználási esetek Tárolja minden hívás átiratát és felvételének URL-jét az ügyféladatok mellett. Továbbítsa az átiratokat egy folyamatba témamodellezéshez, CSAT-jelek kinyeréséhez vagy az átirányítási arány monitorozásához. Nyissa meg a hívásokat egy QA-eszközben emberi felülvizsgálathoz, vagy futtassa át őket saját értékelési modelljén. Átirányítás vagy hiba esetén értesítsen egy emberi csapattagot. --- ## Kapcsolódó tartalmak A hívás indításakor futó blokkoló megfelelője. További eseménytípusok, amelyekre feliratkozhat. Ugyanezek az adatok REST-en keresztül is elérhetők visszatöltéshez vagy újrajátszáshoz.