Open in
telephony.complete / web.complete
Neblokirajući webhook isporučen po završetku poziva, s transkriptom, URL-om snimke i metrikama.
Događaj dovršetka pokreće se nakon završetka svakog poziva — dolazne telefonije, odlazne telefonije, web-poziva ili probnog poziva (sesija mikrofona u alatu za izradu). On je neblokirajući: odgovorite bilo kojim statusom 2xx.
Događaj se isporučuje na oba puta:
- Krajnje točke webhooka primaju
telephony.complete(telefonski pozivi) iliweb.complete(web-pozivi i probni pozivi mikrofonom u alatu za izradu) sa stabilnim korisnim opterećenjem dokumentiranim u nastavku,event_idza svaku isporuku, vremenskim ograničenjem od 30 s i ponovnim pokušajima do 24 h. - Naslijeđeni webhook s jednim URL-om prima jedan sinkroni pokušaj (vremensko ograničenje od 10 s, bez ponovnih pokušaja) s neznatno drugačijim korisnim opterećenjem — pogledajte Razlike u naslijeđenom korisnom opterećenju.
Tijelo zahtjeva (isporuke krajnjoj točki)
{
"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 | Stabilan u svim događajima za ovaj poziv |
agent_id | integer | null | Agent koji je obradio poziv, ako je dodijeljen |
agent_name | string | null | Agent koji je obradio poziv, ako je dodijeljen |
direction | string | inbound, outbound, web, test. Povijesni payloadi mogu sadržavati zastarjele vrijednosti mic ili widget |
from_number, to_number | string | E.164. from_number doslovno je "web" za web-pozive i testne pozive |
origin_domain | string | Samo za web/test — ishodište stranice na kojoj je hostan widget (prazno za mic sesije) |
start_time, end_time | timestamp | ISO 8601 UTC |
duration_seconds | integer | null | Izvedeno iz početka/završetka |
status | string | completed ili failed |
end_reason | string | Pogledajte tablicu u nastavku |
answered_by | string | null | Samo odlazni telefonski pozivi (inače nije prisutno): tko se javio, human, voicemail, screener (pomoćnik za provjeru poziva), ivr (telefonski izbornik) ili unknown. null kada se nitko nije javio te uvijek null u događajima migration.call.complete za odlazne pozive koje je obradila platforma s koje prelazite. Iste vrijednosti kao u objektu poziva |
product, voice | string | Konfiguracija agenta aktivna u trenutku poziva |
variables | object | Ulazne varijable snimljene pri početku poziva |
unresolved_variables | array | Nazivi varijabli na koje se poziva konfiguracija poziva, ali nisu dostavljene pri početku poziva |
transfer_number | string | null | Postavljeno kada je poziv preusmjeren |
scheduled_send_id | string | Samo za poziv upućen zakazanim slanjem: ID tog slanja. Nije prisutno ni u jednom drugom pozivu |
recording_url | string | null | Potpisani URL s istekom; odmah preuzmite. null kada snimka nije dostupna |
recording_stopped_at | timestamp | null | Vrijeme kada je snimanje zaustavljeno prije završetka poziva; ništa nakon tog trenutka nije u snimci. null kada je snimanje trajalo do kraja poziva ili poziv nije snimljen |
recording_stopped_reason | string | null | Zašto je snimanje rano zaustavljeno. warm_transfer: zaustavlja se neposredno prije nego što toplo preusmjeravanje nazove odredište i ostaje isključeno čak i ako preusmjeravanje ne uspije te se pozivatelj vrati agentu. Ostale vrijednosti smatrajte informativnima; mogu se dodati nove. null kada je recording_stopped_at null |
billable_minutes | number | Naplaćene minute, zaokružene na najbližu četvrtinu minute (intervali od 15 sekundi, najmanje 0.25). Pozivi izravno na govornu poštu ovdje i dalje prikazuju svoje stvarne izmjerene minute, ali je naknada ograničena na jednu minutu po cijeni plana. |
billing_total_cents | integer | null | Američki centi. null dok je billing_pending true |
billing_pending | boolean | Prisutan samo kao true za poziv s mjerenom naplatom čija naknada još nije obrađena: poziv s mjerenom naplatom naplaćuje se nekoliko minuta nakon završetka, kada se zaprimi njegova potrošnja, pa su billable_minutes i billing_total_cents ovdje null, a naknada stiže u call.billed. Nije prisutan ni u jednom drugom pozivu |
transcripts | array | Unosi transkripta po potezu; može biti prazno kada transkript nije dostupan |
summary | string | null | Sažetak nakon poziva na običnom jeziku (dvije do četiri rečenice proznog teksta, najviše 2.000 znakova, napisan na agentovu jeziku summary_language, inače na jeziku sažetaka organizacije, inače na jeziku poziva: primarnom jeziku agenta, osim ako ga poziv nije nadjačao) kada agent ima uključenu opciju Generiraj sažetak poziva u odjeljku Podaci za prikupljanje u alatu za izradu agenta (call_summary_enabled na Agentu) i generiranje je uspjelo; inače null, uključujući pozive prekratke za sažimanje, pozive bez transkripta i agente s isključenim snimanjem. Sažetak se generira u istom koraku nakon poziva kao i ekstrakcija, pa postavka Pričekajte izdvojene podatke prije slanja webhooka o završenom pozivu (extraction_blocks_completion) određuje čeka li ovaj događaj na njega: u načinu čekanja sažetak je spreman prije slanja ovog događaja (sam sažetak ima najviše 30 sekundi unutar proračuna koraka od 75 sekundi); kada događaj ne čeka (never, ili preusmjeravanje ili povratak u vaš kontaktni centar uz except_transfers), ovo je polje null i sažetak se ne šalje ponovno u call.data_extracted, stoga ga kasnije pročitajte iz summary u objektu poziva. Dostupno je i na stranici poziva na nadzornoj ploči |
extracted_data | object | null | Strukturirani rezultat ekstrakcije s poljima status, fields, evidence, verification, field_reasons i schema_version. Svako polje koje nije null ima točan strukturno provjeren citat (najviše 1.000 znakova), uz ulogu govornika i indeks poteza; dulji citati koje vrati model odbacuju se umjesto skraćivanja. Dokaz je null kada je polje null. verified znači da je svaki kandidat primio točno jednu valjanu neovisnu presudu. unavailable obuhvaća i neispravan ili djelomičan izlaz provjeravatelja; valjane djelomične presude i dalje se primjenjuju, dok se kandidati bez jedne valjane presude postavljaju na null. status je completed, failed, exhausted, skipped ili skipped_recording_disabled; null kada agent nije imao polja za ekstrakciju |
steps_trace | array | Samo za pozive čiji agent ima korake ili predaje. Redoslijed kojim je poziv prolazio kroz njih: svaki unos ima t_ms (milisekunde od početka poziva), agent (ključ agenta, a plus njegov ID), step (ID koraka ili null pri predaji agentu bez koraka) i via (start, model, condition, on_enter ili handoff). Sadrži samo ID-ove i vremena, stoga se čuva i kada je snimanje isključeno |
collected_values | object | Samo za pozive čiji agent ima korake ili predaje. Vrijednosti koje je agent prikupio u svojim koracima, označene nazivom polja za prikupljanje, uz <tool>_result za rezultat on_enter_tool svakog koraka. Izostavljeno kada se sadržaj poziva ne zadržava (snimanje je isključeno) |
Razlozi završetka
| Vrijednost | Značenje |
|---|---|
user_hangup | Udaljena strana prva je prekinula vezu |
ai_hangup | AI je namjerno završio poziv |
ai_transfer | AI je preusmjerio poziv; transfer_number je postavljen |
ai_warm_transfer | AI je dovršio topli (najavljeni) prijenos |
returned_to_platform | AI je vratio poziv u vaš kontaktni centar: prekinuo je vezu, s zaglavljima povratnog unosa u SIP poruci BYE ako postoje |
voicemail_hangup | Otkrivena je govorna pošta i poziv je završen prema vašem voicemail_action |
max_duration | Poziv je dosegnuo ograničenje maksimalnog trajanja: ograničenje agenta, vlastito ograničenje poziva ili ograničenje platforme od 6 sati. Poziv koji AI ili pozivatelj završi nakon upozorenja o vremenskom ograničenju zadržava ai_hangup ili user_hangup |
superseded | Sesiju je zamijenila novija sesija |
inbound_config_webhook_failed | Dolazni poziv na broj u načinu rada webhooka: webhook za konfiguraciju nije vratio upotrebljivu konfiguraciju, pa je poziv završen prije nego što se agent javio. status je failed i poziv se ne naplaćuje |
outbound_queue_timeout | Poziv u redu čekanja čekao je 10 minuta bez dostupnog kapaciteta za biranje. status je failed, ništa nije birano i poziv se ne naplaćuje |
outbound_queue_canceled | Otkazali ste poziv u redu čekanja prije nego što je biran. status je failed i poziv se ne naplaćuje |
unknown | Razlog završetka nije se mogao utvrditi |
Format prijepisa
Svaki unos u transcripts predstavlja jedan razgovorni potez. Uloge su
user (govor pozivatelja), model (govor agenta i pozivi alata),
tool (rezultati alata) i system (događaji poziva kao što su promjene
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 | string | user, model, tool ili system |
content_type | string | text/plain za govor; application/json za pozive alata, rezultate alata i sistemske događaje |
content | string | object | Tekst govora ili strukturirani objekt prikazan iznad. Pozivi alata: {"tool_call": name, "arguments": {…}}. Rezultati alata: {"tool_name": name, "response": {…}} |
start_ms, end_ms | integer | Pomaci od početka poziva, u ms. Prisutni kada je poznato vremensko usklađivanje zvuka |
ttfa_ms | integer | Vrijeme do prvog zvuka za potez model, kada je izmjereno |
audio_url, audio_urls | string / array | Istječući potpisani URL-ovi za zvuk poteza, kada se zvuk snima po potezu |
Za potpuno strukturiranu povijest poteza (s oznakama prekida,
upitima za potvrdu i sirovim pozicijama) upotrijebite
GET /v1/calls/{call_id}/history.
Razlike u naslijeđenom payloadu
Naslijeđena omotnica webhooka s jednim URL-om je
{"type": "telephony.complete" | "web.complete", "data": {…}} bez
event_id, a njezin se data razlikuje od payloada krajnje točke:
Naslijeđeni payload dovršetka također sadrži agent_id i agent_name.
- Niz poteza nalazi se pod
history, a ne podtranscripts(ista shema poteza kao iznad). - Skup polja predstavlja sirovi izvještaj na kraju poziva i može sadržavati dodatna interna polja izvan gornje tablice — nepoznata polja tretirajte kao informativna.
- Web-pozivi (
direction: "web") izostavljajufrom_number/to_numberi dodajuorigin_domain. - Pozivi za testiranje mikrofona u Builderu prijavljuju se kao
telephony.completena naslijeđenoj putanji (sustav krajnje točke mapira ih naweb.complete). - Koordinacija prijenosa: kada poziv završi prijenosom, naslijeđeni webhook
poziva se sinkrono i može odgovoriti s
{"transfer_ready": false}kako bi signalizirao da cilj prijenosa nije spreman. Svaki drugi odgovor (ili izostanak naslijeđenog webhooka) omogućuje nastavak prijenosa. Isporuke krajnjoj točki nikada se ne provjeravaju u tu svrhu.
Primjer rukovatelja
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 });
},
);Uobičajeni slučajevi upotrebe
Pohranite transkript i URL snimke svakog poziva uz evidenciju svojih korisnika.
Šaljite transkripte u proces obrade za modeliranje tema, izdvajanje CSAT signala ili praćenje stope prijenosa.
Otvorite pozive u alatu za osiguranje kvalitete radi pregleda od strane ljudi ili ih obradite vlastitim modelom za evaluaciju.
Obavijestite člana tima pri prijenosu / neuspjehu.