Open in
telephony.complete / web.complete
Neblokujúci webhook doručený po ukončení hovoru s prepisom, URL nahrávky a metrikami.
Udalosť dokončenia sa spustí po skončení každého hovoru — prichádzajúcej telefónie, odchádzajúcej telefónie, webového hovoru alebo testovacieho hovoru (relácia mikrofónu v nástroji na tvorbu). Je neblokujúca: odpovedzte ľubovoľným kódom 2xx.
Udalosť sa doručuje oboma cestami:
- Koncové body webhookov prijímajú
telephony.complete(telefónne hovory) aleboweb.complete(webové hovory a testovacie hovory mikrofónu v nástroji na tvorbu) so stabilným obsahom zdokumentovaným nižšie, identifikátoromevent_idpre každé doručenie, časovým limitom 30 s a opakovanými pokusmi až 24 h. - Starší webhook s jednou adresou URL prijíma jeden synchrónny pokus (časový limit 10 s, bez opakovaných pokusov) s mierne odlišným obsahom — pozrite si Rozdiely staršieho obsahu.
Telo požiadavky (doručenia endpointu)
{
"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_stopped_at": null,
"recording_stopped_reason": null,
"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"
}| Pole | Typ | Popis |
|---|---|---|
call_id | celé číslo | Stabilné vo všetkých udalostiach pre tento hovor |
agent_id | celé číslo | null | Agent, ktorý spracoval hovor, ak bol priradený |
agent_name | reťazec | null | Agent, ktorý spracoval hovor, ak bol priradený |
direction | reťazec | inbound, outbound, web, test. Historické payloady môžu obsahovať staršie hodnoty mic alebo widget |
from_number, to_number | reťazec | E.164. from_number je doslovná hodnota "web" pre webové a testovacie hovory |
origin_domain | reťazec | Len pre web/test — pôvod stránky, na ktorej bol hostovaný widget (prázdne pre relácie mic) |
start_time, end_time | časová značka | ISO 8601 UTC |
duration_seconds | celé číslo | null | Odvodené od času začiatku a konca |
status | reťazec | completed alebo failed |
end_reason | reťazec | Pozrite si tabuľku nižšie |
answered_by | reťazec | null | Len pre odchádzajúce telefonické hovory (inak chýba): kto odpovedal, human, voicemail, screener (asistent na filtrovanie hovorov), ivr (telefónne menu) alebo unknown. null, keď nikto neodpovedal, a vždy null v udalostiach migration.call.complete pre odchádzajúce hovory, ktoré spracovala platforma, z ktorej prechádzate. Rovnaké hodnoty ako v objekte hovoru |
product, voice | reťazec | Konfigurácia agenta platná v čase hovoru |
variables | objekt | Vstupné premenné zachytené pri začatí hovoru |
unresolved_variables | pole | Názvy premenných, na ktoré odkazuje konfigurácia hovoru, ale neboli poskytnuté pri začatí hovoru |
transfer_number | reťazec | null | Nastavené pri presmerovaní hovoru |
scheduled_send_id | reťazec | Len pri hovore uskutočnenom prostredníctvom naplánovaného odoslania: ID daného odoslania. Pri všetkých ostatných hovoroch chýba |
recording_url | reťazec | null | Podpísaná adresa URL s obmedzenou platnosťou; stiahnite ju bezodkladne. null, keď nie je k dispozícii žiadny záznam |
recording_stopped_at | časová značka | null | Keď sa nahrávanie zastavilo pred ukončením hovoru; nič po tomto okamihu sa v nahrávke nenachádza. null, keď nahrávanie pokračovalo až do konca hovoru alebo hovor nebol nahrávaný |
recording_stopped_reason | reťazec | null | Prečo sa nahrávanie zastavilo predčasne. warm_transfer: zastaví sa tesne predtým, ako teplé presmerovanie zavolá cieľovému kontaktu, a zostane vypnuté aj v prípade zlyhania presmerovania a návratu volajúceho k agentovi. Ostatné hodnoty považujte za informatívne; môžu pribudnúť ďalšie. null, keď recording_stopped_at je null |
billable_minutes | číslo | Fakturované minúty zaokrúhlené na najbližšiu štvrťminútu (15-sekundové intervaly, minimum 0.25). Hovory priamo do hlasovej schránky tu stále uvádzajú skutočné merané minúty, ale poplatok je obmedzený na jednu minútu podľa sadzby plánu. |
billing_total_cents | celé číslo | null | Centy USD. null, kým billing_pending je true |
billing_pending | boolean | Prítomné iba ako true pri meranom hovore, ktorého poplatok ešte nebol vyúčtovaný: meraný hovor sa účtuje niekoľko minút po skončení, po prijatí údajov o jeho využití, takže billable_minutes a billing_total_cents sú tu null a poplatok príde v call.billed. Pri všetkých ostatných hovoroch chýba |
transcripts | pole | Záznamy prepisu jednotlivých ťahov; môžu byť prázdne, keď prepis nie je k dispozícii |
summary | reťazec | null | Súhrn po hovore v prirodzenom jazyku (dve až štyri vety prózy, najviac 2 000 znakov, napísaný v summary_language agenta, inak v jazyku súhrnov organizácie, inak v jazyku hovoru: primárnom jazyku agenta, ak ho hovor neprepísal), keď má agent v nástroji na vytváranie agentov v časti Údaje na zhromaždenie zapnutú možnosť Generovať súhrn hovoru (call_summary_enabled v Agentovi) a generovanie bolo úspešné; inak null, vrátane hovorov príliš krátkych na zhrnutie, hovorov bez prepisu a agentov s vypnutým nahrávaním. Súhrn sa generuje v rovnakom kroku po hovore ako extrakcia, takže nastavenie Počkať na extrahované údaje pred odoslaním webhooku o ukončení hovoru (extraction_blocks_completion) určuje, či naň táto udalosť čaká: v režime čakania je súhrn pripravený pred odoslaním tejto udalosti (samotný súhrn má v rámci 75-sekundového rozpočtu kroku najviac 30 sekúnd); keď udalosť nečaká (never, alebo presmerovanie či návrat do vášho kontaktného centra pri except_transfers), toto pole je null a súhrn sa neodosiela znova v call.data_extracted, preto ho neskôr načítajte z summary v objekte hovoru. K dispozícii je aj na stránke hovoru v ovládacom paneli |
extracted_data | objekt | null | Výsledok štruktúrovanej extrakcie s položkami status, fields, evidence, verification, field_reasons a schema_version. Každé pole, ktoré nie je null, obsahuje presnú štrukturálne overenú citáciu (najviac 1 000 znakov), ako aj rolu hovoriaceho a index ťahu; dlhšie citácie vrátené modelom sa namiesto skrátenia odmietnu. Dôkaz je null, keď je pole null. verified znamená, že každý kandidát dostal presne jeden platný nezávislý verdikt. unavailable zahŕňa aj nesprávne formátovaný alebo neúplný výstup overovača; platné čiastočné verdikty sa naďalej použijú, zatiaľ čo kandidáti bez jedného platného verdiktu sa nastavia na null. status je completed, failed, exhausted, skipped alebo skipped_recording_disabled; null, keď agent nemal žiadne extrakčné polia |
steps_trace | pole | Len pri hovoroch, ktorých agent má kroky alebo odovzdania. Poradie, v akom hovor nimi prechádzal: každá položka obsahuje t_ms (milisekundy od začatia hovoru), agent (kľúč agenta, a plus jeho ID), step (ID kroku alebo null pri odovzdaní agentovi bez krokov) a via (start, model, condition, on_enter alebo handoff). Obsahuje len ID a časy, takže sa uchováva aj pri vypnutom nahrávaní |
collected_values | objekt | Len pri hovoroch, ktorých agent má kroky alebo odovzdania. Hodnoty, ktoré agent zhromaždil vo svojich krokoch, s kľúčom podľa názvu poľa zhromažďovania, plus <tool>_result pre výsledok on_enter_tool každého kroku. Vynechá sa, keď sa obsah hovoru neuchováva (nahrávanie je vypnuté) |
Dôvody ukončenia
| Hodnota | Význam |
|---|---|
user_hangup | Vzdialená strana zavesila ako prvá |
ai_hangup | AI zámerne ukončila hovor |
ai_transfer | AI presmerovala hovor; transfer_number je nastavené |
ai_warm_transfer | AI dokončila teplé (asistované) presmerovanie |
returned_to_platform | AI vrátila hovor do vášho kontaktného centra: zavesila a pri existujúcich hlavičkách záznamu o vrátení ich zahrnula do SIP BYE |
voicemail_hangup | Bola zistená hlasová schránka a hovor sa ukončil podľa vášho voicemail_action |
max_duration | Hovor dosiahol limit maximálneho trvania: limit agenta, vlastný limit hovoru alebo 6-hodinový limit platformy. Hovor, ktorý AI alebo volajúci ukončí po upozornení na časový limit, si zachová ai_hangup alebo user_hangup |
superseded | Relácia bola nahradená novšou |
inbound_config_webhook_failed | Prichádzajúci hovor na číslo v režime webhooku: konfiguračný webhook nevrátil použiteľnú konfiguráciu, preto bol hovor ukončený pred odpoveďou agenta. status je failed a hovor nie je spoplatnený |
outbound_queue_timeout | Hovor vo fronte čakal 10 minút bez dostupnej kapacity na vytočenie. status je failed, nič sa nevytočilo a hovor nie je spoplatnený |
outbound_queue_canceled | Zrušili ste hovor vo fronte pred jeho vytočením. status je failed a hovor nie je spoplatnený |
unknown | Dôvod ukončenia sa nepodarilo určiť |
Formát prepisu
Každá položka v transcripts predstavuje jeden konverzačný ťah. Roly sú
user (reč volajúceho), model (reč agenta a volania nástrojov),
tool (výsledky nástrojov) a system (udalosti hovoru, napríklad zmeny
jazyka).
[
{
"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"] }
}
}
]| Pole | Typ | Popis |
|---|---|---|
role | string | user, model, tool alebo system |
content_type | string | text/plain pre reč; application/json pre volania nástrojov, výsledky nástrojov a systémové udalosti |
content | string | object | Text reči alebo štruktúrovaný objekt zobrazený vyššie. Volania nástrojov: {"tool_call": name, "arguments": {…}}. Výsledky nástrojov: {"tool_name": name, "response": {…}} |
start_ms, end_ms | integer | Posuny od začiatku hovoru v ms. Uvádzajú sa, keď je známe časovanie zvuku |
ttfa_ms | integer | Čas do prvého zvuku pre ťah model, ak sa meria |
audio_url, audio_urls | string / array | URL s časovo obmedzeným podpisom pre zvuk daného ťahu, ak sa zaznamenáva pre jednotlivé ťahy |
Pre úplne štruktúrovanú históriu ťahov (so značkami prerušení,
výzvami na potvrdenie a nespracovanými pozíciami) použite
GET /v1/calls/{call_id}/history.
Rozdiely staršieho payloadu
Starší obal webhooku s jednou URL je
{"type": "telephony.complete" | "web.complete", "data": {…}} bez
event_id a jeho data sa líši od payloadu endpointu:
Starší payload dokončenia obsahuje aj agent_id a agent_name.
- Pole ťahov je v
history, nie vtranscripts(s rovnakou schémou ťahov ako vyššie). - Sada polí predstavuje nespracovaný report po ukončení hovoru a môže obsahovať ďalšie interné polia nad rámec tabuľky vyššie — neznáme polia považujte za informatívne.
- Webové hovory (
direction: "web") neobsahujúfrom_number/to_numbera pridávajúorigin_domain. - Testovacie hovory mikrofónu v nástroji Builder sa na staršej ceste hlásia ako
telephony.complete(systém endpointu ich mapuje naweb.complete). - Koordinácia presmerovania: keď sa hovor skončí presmerovaním, starší
webhook sa volá synchrónne a môže odpovedať
{"transfer_ready": false}, čím signalizuje, že cieľ presmerovania nie je pripravený. Akákoľvek iná odpoveď (alebo žiadny starší webhook) umožní pokračovanie presmerovania. Doručenia endpointu sa na tento účel nikdy nekontrolujú.
Ukážkový obslužný program
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}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 });
},
);Bežné prípady použitia
Uložte prepis každého hovoru a adresu URL nahrávky spolu so záznamami o zákazníkoch.
Streamujte prepisy do pipeline na modelovanie tém, extrakciu signálov CSAT alebo monitorovanie miery presmerovaní.
Otvorte hovory v nástroji QA na kontrolu človekom alebo ich spustite cez vlastný hodnotiaci model.
Pri presmerovaní alebo zlyhaní upozornite člena tímu.