Open in
telephony.complete / web.complete
Неблокирајући вебхук који се испоручује када се позив заврши, са транскриптом, URL-ом снимка и метрикама.
Догађај завршетка се покреће након завршетка сваког позива — долазне телефоније, одлазне телефоније, веб позива или тест позива (сесија микрофона у алату за израду). Он је неблокирајући: одговорите било којим кодом 2xx.
Догађај се испоручује на оба пута:
- Webhook крајње тачке примају
telephony.complete(телефонски позиви) илиweb.complete(веб позиви и тест позиви микрофоном у алату за израду) са стабилним payload-ом документованим у наставку,event_idза сваку испоруку, временским ограничењем од 30 с и поновним покушајима до 24 ч. - Застарели webhook са једним URL-ом прима један синхрони покушај (временско ограничење од 10 с, без поновних покушаја) са мало другачијим payload-ом — погледајте Разлике у застарелом payload-у.
Тело захтева (испоруке крајњој тачки)
{
"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"
}| Поље | Тип | Опис |
|---|---|---|
call_id | integer | Стабилан у сваком догађају за овај позив |
agent_id | integer | null | Агент који је обрадио позив, када је додељен |
agent_name | string | null | Агент који је обрадио позив, када је додељен |
direction | string | inbound, outbound, web, test. Историјски терети могу садржати застареле вредности mic или widget |
from_number, to_number | string | E.164. from_number је дословна вредност "web" за веб позиве и тест позиве |
origin_domain | string | Само за веб/тест — извор странице на којој је виџет хостован (празно за mic сесије) |
start_time, end_time | timestamp | ISO 8601 UTC |
duration_seconds | integer | null | Изведено из времена почетка и завршетка |
status | string | completed или failed |
end_reason | string | Погледајте табелу испод |
answered_by | string | null | Само за одлазне телефонске позиве (иначе није присутно): ко се јавио, human, voicemail, screener (помоћник за филтрирање позива), ivr (телефонски мени) или unknown. null када се нико није јавио, и увек null у догађајима migration.call.complete за одлазне позиве које је обрадила платформа са које прелазите. Исте вредности као у објекту позива |
product, voice | string | Конфигурација агента активна у тренутку позива |
variables | object | Улазне променљиве снимљене када је позив започет |
unresolved_variables | array | Називи променљивих на које се конфигурација позива позива, али које нису достављене при почетку позива |
transfer_number | string | null | Поставља се када је позив преусмерен |
scheduled_send_id | string | Само за позив упућен путем заказаног слања: идентификатор тог слања. Није присутно за сваки други позив |
recording_url | string | null | Потписани URL који истиче; преузмите га одмах. null када артефакт снимка није доступан |
recording_stopped_at | timestamp | null | Када је снимање заустављено пре завршетка позива; ништа након овог тренутка није у снимку. null када је снимање трајало до краја позива или позив није сниман |
recording_stopped_reason | string | null | Зашто је снимање рано заустављено. warm_transfer: зауставља се непосредно пре него што топли трансфер позове одредиште и остаје искључено чак и ако трансфер не успе и позивалац се врати агенту. Остале вредности сматрајте информативним; могу бити додате нове. null када је recording_stopped_at null |
billable_minutes | number | Наплаћени минути, заокружени на најближу четвртину минута (инкременти од 15 секунди, минимум 0.25). Позиви директно на говорну пошту и даље овде пријављују стварне измерене минуте, али је наплата ограничена на један минут по стопи плана. |
billing_total_cents | integer | null | USD центи. null док је billing_pending true |
billing_pending | boolean | Присутно само као true за позив са обрачуном по потрошњи чија наплата још није измирена: позив са обрачуном по потрошњи наплаћује се неколико минута након завршетка, када стигне његова употреба, па су billable_minutes и billing_total_cents овде null, а наплата стиже у call.billed. Није присутно за сваки други позив |
transcripts | array | Уноси транскрипта по потезу; може бити празно када транскрипт није доступан |
summary | string | null | Сажетак након позива написан једноставним језиком (две до четири реченице прозе, највише 2.000 знакова, написан на summary_language агента, у супротном на језику сажетака организације, а у супротном на језику позива: примарном језику агента, осим ако га позив није заменио) када агент има укључено Генеришите сажетак позива у одељку Подаци за прикупљање у градитељу агента (call_summary_enabled на Агенту) и генерисање је успело; у супротном null, укључујући позиве прекратке за сажимање, позиве без транскрипта и агенте са искљученим снимањем. Сажетак се генерише у истом кораку након позива као и издвајање, па подешавање Сачекајте издвојене податке пре слања веб-хука о завршетку позива (extraction_blocks_completion) одређује да ли овај догађај чека на њега: у режиму чекања сажетак је спреман пре слања овог догађаја (сам сажетак има највише 30 секунди у оквиру буџета корака од 75 секунди); када догађај не чека (never, или трансфер или повратак у ваш контакт центар у оквиру except_transfers), ово поље је null и сажетак се не шаље поново у call.data_extracted, па га касније прочитајте из summary у објекту позива. Доступно је и на страници позива на контролној табли |
extracted_data | object | null | Резултат структурираног издвајања са status, fields, evidence, verification, field_reasons и schema_version. Свако поље које није null садржи тачан структурно проверен цитат (највише 1.000 знакова), као и улогу говорника и индекс потеза; дужи цитати које врати модел се одбацују уместо да се скраћују. Доказ је null када је поље null. verified значи да је сваки кандидат добио тачно једну важећу независну пресуду. unavailable такође обухвата неисправан или делимичан излаз проверавача; важеће делимичне пресуде се и даље примењују, док се кандидати без једне важеће пресуде постављају на null. status је completed, failed, exhausted, skipped или skipped_recording_disabled; null када агент нема поља за издвајање |
steps_trace | array | Само за позиве чији агент има кораке или предаје. Редослед којим се позив кретао кроз њих: сваки унос има t_ms (милисекунде од почетка позива), agent (кључ агента, a плус његов ИД), step (ИД корака, или null при предаји агенту без корака) и via (start, model, condition, on_enter или handoff). Садржи само ИД-ове и времена, па се чува чак и када је снимање искључено |
collected_values | object | Само за позиве чији агент има кораке или предаје. Вредности које је агент прикупио у својим корацима, са кључем према називу поља за прикупљање, као и <tool>_result за резултат on_enter_tool сваког корака. Изостављено када се садржај позива не задржава (снимање је искључено) |
Разлози завршетка
| Вредност | Значење |
|---|---|
user_hangup | Удаљена страна је прва прекинула везу |
ai_hangup | AI је намерно завршио позив |
ai_transfer | AI је пренео позив; transfer_number је подешен |
ai_warm_transfer | AI је завршио топли пренос позива (уз присуство) |
returned_to_platform | AI је вратио позив у Ваш контакт центар: прекинуо је везу, са заглављима уноса за повратак у SIP BYE ако постоје |
voicemail_hangup | Откривена је говорна пошта и позив је завршен у складу са Вашим voicemail_action |
max_duration | Позив је достигао ограничење максималног трајања: ограничење агента, ограничење самог позива или ограничење платформе од 6 сати. Позив који AI или позивалац заврши након упозорења о временском ограничењу задржава ai_hangup или user_hangup |
superseded | Сесија је замењена новијом |
inbound_config_webhook_failed | Долазни позив на број у режиму веб-куке: веб-кука за конфигурацију није вратила употребљиву конфигурацију, па је позив завршен пре него што је агент одговорио. status је failed и позив се не наплаћује |
outbound_queue_timeout | Позив у реду је чекао 10 минута без могућности за бирање. status је failed, ништа није бирано и позив се не наплаћује |
outbound_queue_canceled | Отказали сте позив у реду пре бирања. status је failed и позив се не наплаћује |
unknown | Разлог завршетка није могао бити утврђен |
Формат транскрипта
Сваки унос у transcripts представља један разговорни потез. Улоге су
user (говор позиваоца), model (говор агента и позиви алата),
tool (резултати алата) и system (догађаји позива, као што су
промене језика).
[
{
"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"] }
}
}
]| Поље | Тип | Опис |
|---|---|---|
role | ниска | user, model, tool или system |
content_type | ниска | text/plain за говор; application/json за позиве алата, резултате алата и системске догађаје |
content | ниска | објекат | Текст говора или структурисани објекат приказан изнад. Позиви алата: {"tool_call": name, "arguments": {…}}. Резултати алата: {"tool_name": name, "response": {…}} |
start_ms, end_ms | цео број | Помераји од почетка позива, у мс. Присутни када је познато аудио-време |
ttfa_ms | цео број | Време до првог звука за потез model, када је измерено |
audio_url, audio_urls | ниска / низ | Потписани URL-ови са истеком за аудио снимак потеза, када се снима по потезу |
За потпуно структурисану историју потеза (са ознакама прекида,
упитима за потврду и изворним позицијама), користите
GET /v1/calls/{call_id}/history.
Разлике у застарелом садржају
Застарели омотач веб-хука са једним URL-ом је
{"type": "telephony.complete" | "web.complete", "data": {…}} без
event_id, а његов data се разликује од садржаја крајње тачке:
Застарели садржај по завршетку такође садржи agent_id и agent_name.
- Низ потеза се налази у
history, а не уtranscripts(иста шема потеза као изнад). - Скуп поља је изворни извештај на крају позива и може да садржи додатна интерна поља изван горње табеле — непозната поља третирајте као информативна.
- Веб позиви (
direction: "web") изостављајуfrom_number/to_numberи додајуorigin_domain. - Позиви за тестирање микрофона у алату за израду пријављују се као
telephony.completeна застарелој путањи (систем крајње тачке их мапира уweb.complete). - Координација преноса: када се позив заврши преносом, застарели
веб-хук се позива синхроно и може да одговори са
{"transfer_ready": false}како би означио да циљ преноса није спреман. Сваки други одговор (или изостанак застарелог веб-хука) омогућава пренос да се настави. Испоруке крајње тачке се за ово никада не проверавају.
Пример обрађивача
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 });
},
);Уобичајени случајеви употребе
Сачувајте транскрипт и URL снимка сваког позива уз евиденцију о клијенту.
Прослеђујте транскрипте у процес обраде за моделирање тема, издвајање CSAT сигнала или праћење стопе преноса.
Отворите позиве у QA алату за људску проверу или их обрадите кроз сопствени модел за евалуацију.
Обавестите члана тима при преносу / неуспеху.