Open in
telephony.complete / web.complete
Неблокиращ уебкук, изпращан при приключване на разговор, с транскрипция, URL адрес на записа и показатели.
Събитие за завършване се задейства след края на всяко обаждане — входяща телефония, изходяща телефония, уеб обаждане или тестово обаждане (сесия с микрофона в конструктора). То е неблокиращо: отговорете с произволен 2xx.
Събитието се доставя и по двата пътя:
- Webhook крайни точки получават
telephony.complete(телефонни обаждания) илиweb.complete(уеб обаждания и тестови обаждания с микрофона в конструктора) със стабилния payload, документиран по-долу,event_idза всяка доставка, изчакване от 30 s и повторни опити до 24 h. - Остарелият webhook с един URL получава един синхронен опит (изчакване от 10 s, без повторни опити) с леко различен 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 | цяло число | Стабилен за всяко събитие за това обаждане |
agent_id | цяло число | null | Агентът, обработил обаждането, когато е бил назначен такъв |
agent_name | низ | null | Агентът, обработил обаждането, когато е бил назначен такъв |
direction | низ | inbound, outbound, web, test. Историческите полезни товари може да съдържат остарели стойности mic или widget |
from_number, to_number | низ | E.164. from_number е буквалната стойност "web" за уеб обаждания и тестови обаждания |
origin_domain | низ | Само за уеб/тест — произходът на страницата, която хоства уиджета (празно за сесии с микрофон) |
start_time, end_time | времеви отпечатък | ISO 8601 UTC |
duration_seconds | цяло число | null | Изведено от началото/края |
status | низ | completed или failed |
end_reason | низ | Вижте таблицата по-долу |
answered_by | низ | null | Само за изходящи телефонни обаждания (иначе липсва): кой е отговорил — human, voicemail, screener (асистент за филтриране на обаждания), ivr (телефонно меню) или unknown. null, когато никой не е отговорил, и винаги null в събития migration.call.complete за изходящи обаждания, обработени от платформата, от която мигрирате. Същите стойности като в обекта за обаждане |
product, voice | низ | Конфигурацията на агента, действаща към момента на обаждането |
variables | обект | Входни променливи, заснети в момента на започване на обаждането |
unresolved_variables | масив | Имена на променливи, посочени от конфигурацията на обаждането, но непредоставени при започването му |
transfer_number | низ | null | Задава се, когато обаждането е прехвърлено |
scheduled_send_id | низ | Само при обаждане, извършено чрез планирано изпращане: идентификаторът на това изпращане. Липсва при всяко друго обаждане |
recording_url | низ | null | Подписан URL адрес с изтичащ срок; изтеглете го своевременно. null, когато няма наличен артефакт на запис |
recording_stopped_at | времеви отпечатък | null | Кога записът е бил спрян преди края на обаждането; нищо след този момент не присъства в записа. null, когато записът е продължил до края на обаждането или обаждането не е било записано |
recording_stopped_reason | низ | null | Защо записът е спрял по-рано. warm_transfer: записът спира непосредствено преди топло прехвърляне да се обади на целевия номер и остава изключен дори ако прехвърлянето не успее и обаждащият се се върне при агента. Третирайте другите стойности като информационни; може да бъдат добавени още. null, когато recording_stopped_at е null |
billable_minutes | число | Таксувани минути, закръглени до най-близката четвърт минута (интервали от 15 секунди, минимум 0.25). Обажданията, насочени директно към гласова поща, все още отчитат тук действителните си измерени минути, но таксата е ограничена до една минута по тарифата на плана. |
billing_total_cents | цяло число | null | Американски центове. null, докато billing_pending е true |
billing_pending | булева стойност | Присъства само като true при измервано обаждане, чиято такса все още не е уредена: измерваното обаждане се таксува няколко минути след приключването му, след като потреблението му бъде отчетено, така че billable_minutes и billing_total_cents тук са null, а таксата пристига в call.billed. Липсва при всяко друго обаждане |
transcripts | масив | Записи в транскрипцията за всеки ход; може да е празен, когато транскрипция не е налична |
summary | низ | null | Резюме след обаждането на разбираем език (две до четири изречения проза, най-много 2 000 знака, написано на summary_language на агента, иначе на езика за резюмета на организацията, иначе на езика на обаждането: основния език на агента, освен ако обаждането не го е заменило), когато за агента е включено Генериране на резюме на обаждането в Данни за събиране в създателя на агента (call_summary_enabled в Агент) и генерирането е успешно; в противен случай null, включително за обаждания, които са твърде кратки за обобщаване, обаждания без транскрипция и агенти с изключен запис. Резюмето се генерира в същата стъпка след обаждането като извличането, затова настройката Изчакване на извлечените данни преди изпращане на уебкуката за приключено обаждане (extraction_blocks_completion) определя дали това събитие го изчаква: в режим на изчакване резюмето е готово преди изпращането на това събитие (самото резюме получава най-много 30 секунди в рамките на 75-секундния бюджет на стъпката); когато събитието не изчаква (never, или прехвърляне, или връщане към вашия контактен център при except_transfers), това поле е null и резюмето не се изпраща отново в call.data_extracted, затова го прочетете по-късно от summary в обекта за обаждане. Налично е и на страницата на обаждането в таблото |
extracted_data | обект | null | Резултат от структурирано извличане с status, fields, evidence, verification, field_reasons и schema_version. Всяко ненулево поле съдържа точния структурно проверен цитат (най-много 1 000 знака), както и ролята на говорещия и индекса на хода му; по-дългите цитати, върнати от модела, се отхвърлят вместо да бъдат съкратени. Доказателството е null, когато полето е null. verified означава, че всеки кандидат е получил точно едно валидно независимо заключение. unavailable обхваща и неправилен или частичен изход от проверяващия механизъм; валидните частични заключения все пак се прилагат, докато кандидатите без едно валидно заключение се зануляват. status е completed, failed, exhausted, skipped или skipped_recording_disabled; null, когато агентът няма полета за извличане |
steps_trace | масив | Само при обаждания, чийто агент има стъпки или предавания. Редът, в който обаждането е преминало през тях: всеки запис съдържа t_ms (милисекунди от началото на обаждането), agent (ключът на агента, a плюс неговия идентификатор), step (идентификаторът на стъпката или null при предаване към агент без стъпки) и via (start, model, condition, on_enter или handoff). Съдържа само идентификатори и времена, затова се запазва дори когато записът е изключен |
collected_values | обект | Само при обаждания, чийто агент има стъпки или предавания. Стойностите, които агентът е събрал в стъпките си, въведени по име на поле за събиране, плюс <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.
Разлики в наследения payload
Наследеният webhook контейнер с един URL е
{"type": "telephony.complete" | "web.complete", "data": {…}} без
event_id, а неговият data се различава от payload на крайната точка:
Наследеният payload при завършване съдържа също agent_id и agent_name.
- Масивът с ходове е в
history, а не вtranscripts(същата схема на ходовете като по-горе). - Наборът от полета е необработеният отчет в края на обаждането и може да включва допълнителни вътрешни полета извън таблицата по-горе — третирайте непознатите полета като информативни.
- Уеб обажданията (
direction: "web") пропускатfrom_number/to_numberи добавятorigin_domain. - Тестовите обаждания с микрофон в конструктора се отчитат като
telephony.completeпо наследения път (системата на крайната точка ги преобразува вweb.complete). - Координация на прехвърлянето: когато обаждане завърши с прехвърляне, наследеният
webhook се извиква синхронно и може да върне
{"transfer_ready": false}, за да сигнализира, че целта на прехвърлянето не е готова. Всеки друг отговор (или липсата на наследен webhook) позволява прехвърлянето да продължи. Доставките до крайната точка никога не се вземат предвид за това.
Примерен обработчик
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 сигнали или наблюдение на процента прехвърлени обаждания.
Отваряйте обажданията в инструмент за осигуряване на качеството за човешки преглед или ги обработвайте чрез собствения си модел за оценяване.
Известявайте член на екипа при прехвърляне / неуспех.