Open in
telephony.complete / web.complete
Neblokirajoč webhook, poslan ob koncu klica, s prepisom, URL-jem posnetka in metrikami.
Dogodek dokončanja se sproži po koncu vsakega klica — dohodne telefonije, odhodne telefonije, spletnega klica ali preskusnega klica (seja z mikrofonom v gradniku). Je neblokirajoč: odgovorite s katerim koli 2xx.
Dogodek je dostavljen po obeh poteh:
- Končne točke webhookov prejmejo
telephony.complete(telefonski klici) aliweb.complete(spletni klici in preskusni klici z mikrofonom v gradniku) s spodaj dokumentiranim stabilnim koristnim tovorom,event_idza vsako dostavo, 30-sekundno časovno omejitvijo in ponovnimi poskusi do 24 ur. - Podedovani webhook z enim URL-jem prejme en sinhroni poskus (10-sekundna časovna omejitev, brez ponovnih poskusov) z nekoliko drugačnim koristnim tovorom — glejte Razlike v podedovanem koristnem tovoru.
Telo zahteve (dostave končne točke)
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
call_id | integer | Nespremenljiv v vseh dogodkih za ta klic |
agent_id | integer | null | Glasovni agent, ki je obravnaval klic, kadar je bil dodeljen |
agent_name | string | null | Glasovni agent, ki je obravnaval klic, kadar je bil dodeljen |
direction | string | inbound, outbound, web, test. Zgodovinski koristni podatki lahko vsebujejo podedovani vrednosti mic ali widget |
from_number, to_number | string | E.164. from_number je dobesedna vrednost "web" za spletne klice in preskusne klice |
origin_domain | string | Samo za spletne/preskusne klice — izvor strani, ki je gostila gradnik (prazno za seje mikrofona) |
start_time, end_time | timestamp | ISO 8601 UTC |
duration_seconds | integer | null | Izpeljano iz časa začetka/konca |
status | string | completed ali failed |
end_reason | string | Glejte spodnjo tabelo |
answered_by | string | null | Samo odhodni telefonski klici (sicer ni prisotno): kdo je odgovoril, human, voicemail, screener (pomočnik za pregledovanje klicev), ivr (telefonski meni) ali unknown. null, kadar ni odgovoril nihče, in vedno null v dogodkih migration.call.complete za odhodne klice, ki jih je obravnavala platforma, s katere se selite. Enake vrednosti kot pri objektu klica |
product, voice | string | Konfiguracija agenta, veljavna ob času klica |
variables | object | Vhodne spremenljivke, zajete ob začetku klica |
unresolved_variables | array | Imena spremenljivk, na katere se sklicuje konfiguracija klica, vendar ob začetku klica niso bile podane |
transfer_number | string | null | Nastavljeno, ko je bil klic preusmerjen |
scheduled_send_id | string | Samo pri klicu, opravljenem z načrtovanim pošiljanjem: ID tega pošiljanja. Pri vseh drugih klicih ni prisotno |
recording_url | string | null | Časovno omejen podpisan URL; prenesite ga takoj. null, kadar posnetek ni na voljo |
recording_stopped_at | timestamp | null | Kdaj je bilo snemanje ustavljeno pred koncem klica; po tem trenutku na posnetku ni ničesar. null, kadar je snemanje trajalo do konca klica ali klic ni bil posnet |
recording_stopped_reason | string | null | Zakaj se je snemanje predčasno ustavilo. warm_transfer: ustavi se tik preden topla preusmeritev pokliče cilj, in ostane izklopljeno tudi, če preusmeritev ne uspe in se klicatelj vrne k agentu. Druge vrednosti obravnavajte kot informativne; lahko bodo dodane nove. null, kadar je recording_stopped_at null |
billable_minutes | number | Zaračunane minute, zaokrožene na najbližjo četrt minute (15-sekundni koraki, najmanj 0.25). Klici neposredno v glasovno pošto tukaj še vedno navajajo dejansko merjene minute, vendar je strošek omejen na eno minuto po ceni paketa. |
billing_total_cents | integer | null | Centi USD. null, dokler je billing_pending true |
billing_pending | boolean | Prisotno samo kot true pri merjenem klicu, katerega strošek še ni poravnan: merjeni klic se zaračuna nekaj minut po koncu, ko je njegova poraba zabeležena, zato sta billable_minutes in billing_total_cents tukaj null, strošek pa prispe v call.billed. Pri vseh drugih klicih ni prisotno |
transcripts | array | Vnosi prepisa po posameznih potezah; lahko je prazno, kadar prepis ni na voljo |
summary | string | null | Povzetek po klicu v običajnem jeziku (dva do štirje stavki proze, največ 2.000 znakov, napisan v agentovem jeziku summary_language, sicer v jeziku povzetkov organizacije, sicer v jeziku klica: primarnem jeziku agenta, razen če ga je klic preglasil), kadar ima agent v gradniku agenta v razdelku Podatki za zbiranje vklopljeno možnost Ustvari povzetek klica (call_summary_enabled pri Agentu) in je ustvarjanje uspelo; sicer null, vključno pri klicih, prekratkih za povzemanje, klicih brez prepisa in agentih z izklopljenim snemanjem. Povzetek se ustvari v istem koraku po klicu kot ekstrakcija, zato nastavitev Počakajte na ekstrahirane podatke pred pošiljanjem webhooka ob koncu klica (extraction_blocks_completion) določa, ali ta dogodek čaka nanj: v načinu čakanja je povzetek pripravljen pred pošiljanjem tega dogodka (sam povzetek ima znotraj 75-sekundnega proračuna koraka na voljo največ 30 sekund); kadar dogodek ne čaka (never ali preusmeritev oziroma vrnitev v vaš kontaktni center v okviru except_transfers), je to polje null in povzetek se ne pošlje znova v call.data_extracted, zato ga pozneje preberite iz summary v objektu klica. Na voljo je tudi na strani klica na nadzorni plošči |
extracted_data | object | null | Strukturiran rezultat ekstrakcije s status, fields, evidence, verification, field_reasons in schema_version. Vsako polje, ki ni null, vsebuje natančen strukturno preverjen citat (največ 1.000 znakov) ter vlogo govorca in indeks poteze; daljši citati, ki jih vrne model, so zavrnjeni namesto okrajšani. Dokaz je null, kadar je polje null. verified pomeni, da je vsak kandidat prejel natanko eno veljavno neodvisno presojo. unavailable zajema tudi nepravilno oblikovan ali delen izhod preverjevalnika; veljavne delne presoje še vedno veljajo, kandidati brez ene veljavne presoje pa so nastavljeni na null. status je completed, failed, exhausted, skipped ali skipped_recording_disabled; null, kadar agent ni imel polj za ekstrakcijo |
steps_trace | array | Samo pri klicih, katerih agent ima korake ali predaje. Vrstni red, po katerem je klic potoval skozi njih: vsak vnos ima t_ms (milisekunde od začetka klica), agent (ključ agenta, a in njegov ID), step (ID koraka ali null pri predaji agentu brez korakov) in via (start, model, condition, on_enter ali handoff). Vsebuje samo ID-je in čase, zato se ohrani tudi, kadar je snemanje izklopljeno |
collected_values | object | Samo pri klicih, katerih agent ima korake ali predaje. Vrednosti, ki jih je agent zbral v svojih korakih, razvrščene po imenu polja zbiranja, ter <tool>_result za rezultat on_enter_tool vsakega koraka. Izpuščeno, kadar vsebina klica ni shranjena (snemanje je izklopljeno) |
Razlogi za konec
| Vrednost | Pomen |
|---|---|
user_hangup | Oddaljena stranka je prva prekinila klic |
ai_hangup | UI je klic namerno končala |
ai_transfer | UI je klic preusmerila; transfer_number je nastavljen |
ai_warm_transfer | UI je dokončala toplo (sprejeto) preusmeritev |
returned_to_platform | UI je vrnila klic v vaš kontaktni center: prekinila je klic, pri čemer so bile glave vnosa za vrnitev v SIP BYE, če obstajajo |
voicemail_hangup | Zaznan je bil glasovni predal, klic pa se je končal v skladu z vašim voicemail_action |
max_duration | Klic je dosegel omejitev najdaljšega trajanja: omejitev agenta, lastno omejitev klica ali 6-urno omejitev platforme. Klic, ki ga UI ali klicatelj konča po opozorilu o časovni omejitvi, ohrani ai_hangup ali user_hangup |
superseded | Sejo je zamenjala novejša seja |
inbound_config_webhook_failed | Dohodni klic na številko v načinu webhook: konfiguracijski webhook ni vrnil uporabne konfiguracije, zato se je klic končal, preden je agent odgovoril. status je failed in klic se ne zaračuna |
outbound_queue_timeout | Klic v čakalni vrsti je čakal 10 minut brez možnosti za klicanje. status je failed, nič ni bilo poklicano in klic se ne zaračuna |
outbound_queue_canceled | Preklicali ste klic v čakalni vrsti, preden se je začelo klicanje. status je failed in klic se ne zaračuna |
unknown | Razloga za konec ni bilo mogoče določiti |
Oblika prepisa
Vsak vnos v transcripts predstavlja en pogovorni obrat. Vloge so
user (govor klicatelja), model (govor agenta in klici orodij),
tool (rezultati orodij) in system (dogodki klica, kot so preklopi
jezika).
[
{
"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"] }
}
}
]| Polje | Vrsta | Opis |
|---|---|---|
role | niz | user, model, tool ali system |
content_type | niz | text/plain za govor; application/json za klice orodij, rezultate orodij in sistemske dogodke |
content | niz | objekt | Besedilo govora ali strukturirani objekt, prikazan zgoraj. Klici orodij: {"tool_call": name, "arguments": {…}}. Rezultati orodij: {"tool_name": name, "response": {…}} |
start_ms, end_ms | celo število | Odmika od začetka klica v ms. Prisotna, kadar je časovni potek zvoka znan |
ttfa_ms | celo število | Čas do prvega zvoka za obrat model, kadar je izmerjen |
audio_url, audio_urls | niz / polje | URL-ji s podpisom in omejenim rokom veljavnosti za zvok obrata, kadar se zvok snema za posamezni obrat |
Za celotno strukturirano zgodovino obratov (z oznakami prekinitev,
pozivi za potrditev in neobdelanimi položaji) uporabite
GET /v1/calls/{call_id}/history.
Razlike v starejšem podatkovnem paketu
Starejša ovojnica webhooka z enim URL-jem je
{"type": "telephony.complete" | "web.complete", "data": {…}} brez
event_id, njen data pa se razlikuje od podatkovnega paketa končne točke:
Starejši podatkovni paket ob zaključku vsebuje tudi agent_id in agent_name.
- Polje obratov je pod
history, ne podtranscripts(z enako shemo obratov kot zgoraj). - Nabor polj je neobdelano poročilo ob koncu klica in lahko vključuje dodatna interna polja poleg zgornje tabele — neznana polja obravnavajte kot informativna.
- Spletni klici (
direction: "web") ne vključujejofrom_number/to_numberin dodajoorigin_domain. - Klici za preizkus mikrofona v orodju Builder se na starejši poti poročajo kot
telephony.complete(sistem končne točke jih preslika vweb.complete). - Usklajevanje prenosa: kadar se klic konča s prenosom, se
starejši webhook pokliče sinhrono in lahko vrne
{"transfer_ready": false}, kar sporoča, da cilj prenosa še ni pripravljen. Vsak drug odgovor (ali odsotnost starejšega webhooka) omogoči nadaljevanje prenosa. Dostave končne točke se za to nikoli ne preverjajo.
Primer obdelovalnika
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 });
},
);Pogosti primeri uporabe
Shranite prepis in URL posnetka vsakega klica skupaj z zapisi o strankah.
Pretakajte prepise v cevovod za modeliranje tem, pridobivanje signalov CSAT ali spremljanje stopnje preusmeritev.
Odprite klice v orodju QA za človeški pregled ali jih obdelajte z lastnim modelom za ocenjevanje.
Ob preusmeritvi / napaki obvestite člana ekipe.