Open in
telephony.complete / web.complete
Neblokuojantis žiniatinklio kabliukas, pateikiamas pasibaigus skambučiui, su transkriptu, įrašo URL ir metrika.
Užbaigimo įvykis suaktyvinamas pasibaigus kiekvienam skambučiui – įeinančios telefonijos, išeinančios telefonijos, žiniatinklio skambučiui arba bandomajam skambučiui (kūrimo priemonės mikrofono seansui). Jis yra neblokuojantis: atsakykite bet kokiu 2xx kodu.
Įvykis pristatomas abiem keliais:
- Webhook galiniai taškai gauna
telephony.complete(telefono skambučiams) arbaweb.complete(žiniatinklio skambučiams ir kūrimo priemonės mikrofono bandomiesiems skambučiams) su toliau dokumentuotu stabiliu paketu, kiekvienam pristatymui skirtuevent_id, 30 s skirtuoju laiku ir pakartotiniais bandymais iki 24 val.. - Senasis vieno URL webhook gauna vieną sinchroninį bandymą (10 s skirtasis laikas, be pakartotinių bandymų) su šiek tiek kitokiu paketu – žr. Senesnio paketo skirtumai.
Užklausos paketas (galinių taškų pristatymai)
{
"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"
}| Laukas | Tipas | Aprašas |
|---|---|---|
call_id | sveikasis skaičius | Pastovus visuose šio skambučio įvykiuose |
agent_id | sveikasis skaičius | null | Skambutį aptarnavęs agentas, jei jis buvo priskirtas |
agent_name | eilutė | null | Skambutį aptarnavusio agento vardas, jei jis buvo priskirtas |
direction | eilutė | inbound, outbound, web, test. Istoriniuose duomenų paketuose gali būti senesnės mic arba widget reikšmės |
from_number, to_number | eilutė | E.164. Žiniatinklio ir bandomiesiems skambučiams from_number yra pažodinė reikšmė "web" |
origin_domain | eilutė | Tik žiniatinklio ir bandomiesiems skambučiams — puslapio, kuriame buvo įterptas valdiklis, kilmė (mikrofono seansams tuščia) |
start_time, end_time | laiko žyma | ISO 8601 UTC |
duration_seconds | sveikasis skaičius | null | Apskaičiuojama pagal pradžios ir pabaigos laiką |
status | eilutė | completed arba failed |
end_reason | eilutė | Žr. toliau pateiktą lentelę |
answered_by | eilutė | null | Tik išeinantiems telefono skambučiams (kitais atvejais nėra): kas atsiliepė — human, voicemail, screener (skambučių tikrinimo asistentas), ivr (telefono meniu) arba unknown. null, kai niekas neatsiliepė, ir visada null migration.call.complete įvykiuose, skirtuose išeinantiems skambučiams, kuriuos aptarnavo platforma, iš kurios pereinate. Tos pačios reikšmės kaip skambučio objekte |
product, voice | eilutė | Skambučio metu galiojusi agento konfigūracija |
variables | objektas | Įvesties kintamųjų momentinė kopija skambučio pradžioje |
unresolved_variables | masyvas | Kintamųjų pavadinimai, nurodyti skambučio konfigūracijoje, bet nepateikti skambučio pradžioje |
transfer_number | eilutė | null | Nustatoma, kai skambutis buvo peradresuotas |
scheduled_send_id | eilutė | Tik skambučiui, atliktam naudojant suplanuotą siuntimą: to siuntimo ID. Visuose kituose skambučiuose nėra |
recording_url | eilutė | null | Laikinai galiojantis pasirašytas URL; atsisiųskite nedelsdami. null, kai nėra įrašo artefakto |
recording_stopped_at | laiko žyma | null | Kai įrašymas buvo sustabdytas prieš skambučio pabaigą; po šio momento įraše nieko nėra. null, kai įrašymas tęsėsi iki skambučio pabaigos arba skambutis nebuvo įrašytas |
recording_stopped_reason | eilutė | null | Kodėl įrašymas buvo sustabdytas anksčiau. warm_transfer: jis sustabdomas prieš pat šiltajam peradresavimui skambinant į paskirties vietą ir lieka išjungtas, net jei peradresavimas nepavyksta ir skambinantysis grįžta pas agentą. Kitas reikšmes laikykite informacinėmis; jų gali būti pridėta daugiau. null, kai recording_stopped_at yra null |
billable_minutes | skaičius | Apmokestintos minutės, suapvalintos iki artimiausio ketvirčio minutės (15 sekundžių intervalais, mažiausiai 0.25). Skambučiai tiesiai į balso paštą čia vis tiek nurodo faktines apskaitytas minutes, tačiau mokestis ribojamas iki vienos minutės pagal plano tarifą. |
billing_total_cents | sveikasis skaičius | null | USD centai. null, kol billing_pending yra true |
billing_pending | loginė reikšmė | Rodoma tik kaip true apskaičiuojamam skambučiui, kurio mokestis dar nenustatytas: apskaičiuojamas skambutis apmokestinamas praėjus kelioms minutėms po jo pabaigos, kai gaunami naudojimo duomenys, todėl billable_minutes ir billing_total_cents čia yra null, o mokestis pateikiamas call.billed. Visuose kituose skambučiuose nėra |
transcripts | masyvas | Pokalbio transkripto įrašai kiekvienam ėjimui; gali būti tuščias, kai transkriptas nepasiekiamas |
summary | eilutė | null | Paprasta kalba parašyta santrauka po skambučio (nuo dviejų iki keturių prozos sakinių, daugiausia 2 000 simbolių, parašyta agento summary_language, kitu atveju organizacijos santraukų kalba, o kitu atveju skambučio kalba: pagrindine agento kalba, nebent skambutis ją pakeitė), kai agentui agento kūrimo priemonėje skiltyje Renkami duomenys įjungta Generuoti skambučio santrauką (call_summary_enabled Agente) ir generavimas pavyko; kitu atveju null, įskaitant skambučius, kurie per trumpi apibendrinti, skambučius be transkripto ir agentus, kuriems įrašymas išjungtas. Santrauka generuojama tame pačiame etape po skambučio kaip ir ištraukimas, todėl nustatymas Laukti ištrauktų duomenų prieš siunčiant skambučio pabaigos žiniatinklio kablį (extraction_blocks_completion) lemia, ar šis įvykis jos laukia: laukimo režimu santrauka paruošiama prieš siunčiant šį įvykį (pačiai santraukai etapo 75 sekundžių biudžete skiriama ne daugiau kaip 30 sekundžių); kai įvykis nelaukia (never, peradresavus arba grįžus į jūsų kontaktų centrą pagal except_transfers), šis laukas yra null, o santrauka nėra iš naujo siunčiama per call.data_extracted, todėl vėliau perskaitykite ją iš summary skambučio objekte. Taip pat pasiekiama skambučio puslapyje valdymo skydelyje |
extracted_data | objektas | null | Struktūrizuotas ištraukimo rezultatas su status, fields, evidence, verification, field_reasons ir schema_version. Kiekvienas ne null laukas turi tikslią struktūriškai patikrintą citatą (daugiausia 1 000 simbolių), taip pat kalbėtojo vaidmenį ir ėjimo indeksą; ilgesnės modelio grąžintos citatos atmetamos, o ne sutrumpinamos. Įrodymai yra null, kai laukas yra null. verified reiškia, kad kiekvienas kandidatas gavo lygiai vieną galiojantį nepriklausomą vertinimą. unavailable taip pat apima netaisyklingą arba dalinę tikrintojo išvestį; galiojantys daliniai vertinimai vis tiek taikomi, o kandidatai be vieno galiojančio vertinimo nustatomi į null. status yra completed, failed, exhausted, skipped arba skipped_recording_disabled; null, kai agentas neturėjo ištraukimo laukų |
steps_trace | masyvas | Tik skambučiams, kurių agentas turi veiksmų arba perdavimų. Tvarka, kuria skambutis judėjo per juos: kiekvienas įrašas turi t_ms (milisekundės nuo skambučio pradžios), agent (agento raktas, a ir jo ID), step (veiksmo ID arba null, perduodant agentui be veiksmų) ir via (start, model, condition, on_enter arba handoff). Saugo tik ID ir laikus, todėl išlaikoma net kai įrašymas išjungtas |
collected_values | objektas | Tik skambučiams, kurių agentas turi veiksmų arba perdavimų. Reikšmės, kurias agentas surinko savo veiksmuose, susietos pagal rinkimo lauko pavadinimą, taip pat <tool>_result kiekvieno veiksmo on_enter_tool rezultatui. Neįtraukiama, kai skambučio turinys neišsaugomas (įrašymas išjungtas) |
Pabaigos priežastys
| Reikšmė | Prasmė |
|---|---|
user_hangup | Nuotolinė šalis pirmoji nutraukė skambutį |
ai_hangup | AI sąmoningai baigė skambutį |
ai_transfer | AI perdavė skambutį; nustatytas transfer_number |
ai_warm_transfer | AI užbaigė šiltąjį perdavimą su dalyvavimu |
returned_to_platform | AI grąžino skambutį į jūsų kontaktų centrą: ji nutraukė skambutį ir, jei jų buvo, į SIP BYE įtraukė grąžinimo įrašo antraštes |
voicemail_hangup | Aptiktas balso paštas, o skambutis baigtas pagal jūsų voicemail_action |
max_duration | Skambutis pasiekė maksimalią trukmės ribą: balso agento, paties skambučio arba 6 valandų platformos ribą. Jei AI arba skambinantysis baigia skambutį po įspėjimo apie laiko limitą, išlieka ai_hangup arba user_hangup |
superseded | Sesiją pakeitė naujesnė |
inbound_config_webhook_failed | Įeinantis skambutis į numerį žiniatinklio kabliuko režimu: konfigūracijos žiniatinklio kabliukas negrąžino tinkamos konfigūracijos, todėl skambutis buvo baigtas prieš balso agentui atsiliepiant. status yra failed, o skambutis neapmokestinamas |
outbound_queue_timeout | Eilėje esantis skambutis 10 minučių laukė, kol atsiras galimybė rinkti numerį. status yra failed, nebuvo surinktas joks numeris, o skambutis neapmokestinamas |
outbound_queue_canceled | Atšaukėte eilėje esantį skambutį prieš jam renkant numerį. status yra failed, o skambutis neapmokestinamas |
unknown | Nepavyko nustatyti baigimo priežasties |
Transkripto formatas
Kiekvienas transcripts įrašas yra vienas pokalbio ėjimas. Vaidmenys yra
user (skambinančiojo kalba), model (agento kalba ir įrankių iškvietimai),
tool (įrankių rezultatai) ir system (skambučio įvykiai, pvz., kalbos
perjungimai).
[
{
"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"] }
}
}
]| Laukas | Tipas | Aprašymas |
|---|---|---|
role | eilutė | user, model, tool arba system |
content_type | eilutė | text/plain kalbai; application/json įrankių iškvietimams, įrankių rezultatams ir sistemos įvykiams |
content | eilutė | objektas | Kalbos tekstas arba pirmiau parodytas struktūrizuotas objektas. Įrankių iškvietimai: {"tool_call": name, "arguments": {…}}. Įrankių rezultatai: {"tool_name": name, "response": {…}} |
start_ms, end_ms | sveikasis skaičius | Poslinkiai nuo skambučio pradžios, ms. Pateikiami, kai žinomas garso laikas |
ttfa_ms | sveikasis skaičius | Laikas iki pirmojo garso model ėjimui, kai išmatuotas |
audio_url, audio_urls | eilutė / masyvas | Baigiančio galioti pasirašyti URL ėjimo garso įrašui, kai įrašoma kiekvienam ėjimui |
Visai struktūrizuotai ėjimų istorijai (su pertraukimo žymenimis,
patvirtinimo raginimais ir neapdorotomis pozicijomis) naudokite
GET /v1/calls/{call_id}/history.
Ankstesnės versijos naudingosios apkrovos skirtumai
Ankstesnės versijos vieno URL žiniatinklio kablio apvalkalas yra
{"type": "telephony.complete" | "web.complete", "data": {…}} be
event_id, o jo data skiriasi nuo galinio taško naudingosios apkrovos:
Ankstesnės versijos užbaigimo naudingoji apkrova taip pat turi agent_id ir agent_name.
- Ėjimų masyvas yra
history, o netranscripts(ta pati ėjimo schema kaip pirmiau). - Laukų rinkinys yra neapdorota skambučio pabaigos ataskaita ir gali apimti papildomus vidinius laukus, kurių nėra pirmiau pateiktoje lentelėje — nežinomus laukus laikykite informaciniais.
- Žiniatinklio skambučiai (
direction: "web") nepateikiafrom_number/to_numberir pridedaorigin_domain. - Konstruktoriaus mikrofono bandomieji skambučiai ankstesnės versijos
kelyje pateikiami kaip
telephony.complete(galinio taško sistema juos susieja suweb.complete). - Perdavimo koordinavimas: kai skambutis baigiasi perdavimu, ankstesnės
versijos žiniatinklio kablys iškviečiamas sinchroniškai ir gali atsakyti
{"transfer_ready": false}, kad nurodytų, jog perdavimo paskirties vieta nėra parengta. Bet koks kitas atsakymas (arba ankstesnės versijos žiniatinklio kablio nebuvimas) leidžia tęsti perdavimą. Galinio taško pristatymai tam niekada nenaudojami.
Pavyzdinė apdorojimo funkcija
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 });
},
);Dažniausi naudojimo atvejai
Išsaugokite kiekvieno skambučio transkriptą ir įrašo URL kartu su klientų įrašais.
Siųskite transkriptus į duomenų srautą temų modeliavimui, CSAT signalų išskyrimui arba perdavimo rodiklio stebėjimui.
Atidarykite skambučius QA įrankyje, kad juos peržiūrėtų žmonės, arba apdorokite juos savo vertinimo modeliu.
Perduodant skambutį arba įvykus klaidai praneškite komandos nariui.