Open in
telephony.complete / web.complete
ట్రాన్స్క్రిప్ట్, రికార్డింగ్ URL మరియు మెట్రిక్లతో కాల్ ముగిసినప్పుడు పంపబడే నాన్-బ్లాకింగ్ వెబ్హుక్.
ప్రతి కాల్ ముగిసిన తర్వాత ఒక completion ఈవెంట్ ట్రిగ్గర్ అవుతుంది — ఇన్బౌండ్ టెలిఫోనీ, అవుట్బౌండ్ టెలిఫోనీ, వెబ్ కాల్ లేదా టెస్ట్ కాల్ (బిల్డర్ మైక్ సెషన్). ఇది బ్లాకింగ్ కానిది: ఏదైనా 2xxతో స్పందించండి.
ఈవెంట్ రెండు మార్గాల్లో పంపబడుతుంది:
- Webhook ఎండ్పాయింట్లు స్థిరమైన పేలోడ్తో
telephony.complete(ఫోన్ కాల్లు) లేదాweb.complete(వెబ్ కాల్లు మరియు బిల్డర్ మైక్ టెస్ట్ కాల్లు)ను స్వీకరిస్తాయి. దిగువన డాక్యుమెంట్ చేసిన విధంగా, ప్రతి డెలివరీకి ఒకevent_id, 30 సెకన్ల టైమ్అవుట్, మరియు గరిష్ఠంగా 24 గంటల వరకు రీట్రైలు ఉంటాయి. - లెగసీ సింగిల్-URL webhook కొద్దిగా భిన్నమైన పేలోడ్తో ఒక సింక్రోనస్ ప్రయత్నాన్ని (10 సెకన్ల టైమ్అవుట్, రీట్రైలు లేవు) స్వీకరిస్తుంది — వివరాలకు లెగసీ పేలోడ్ తేడాలు చూడండి.
అభ్యర్థన పేలోడ్ (ఎండ్పాయింట్ డెలివరీలు)
{
"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_url": "https://storage.example.com/…",
"start_time": "2026-04-20T18:24:10.113Z",
"status": "completed",
"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 | వెబ్/టెస్ట్కు మాత్రమే — విడ్జెట్ను హోస్ట్ చేసిన పేజీ ఆరిజిన్ (మైక్ సెషన్లకు ఖాళీగా ఉంటుంది) |
start_time, end_time | timestamp | ISO 8601 UTC |
duration_seconds | integer | null | ప్రారంభం/ముగింపు సమయాల నుంచి పొందబడుతుంది |
status | string | completed లేదా failed |
end_reason | string | దిగువ పట్టికను చూడండి |
product, voice | string | కాల్ సమయంలో అమల్లో ఉన్న ఏజెంట్ కాన్ఫిగరేషన్ |
variables | object | కాల్ ప్రారంభమైనప్పుడు స్నాప్షాట్ చేసిన ఇన్పుట్ వేరియబుల్స్ |
unresolved_variables | array | కాల్ కాన్ఫిగరేషన్ సూచించినప్పటికీ కాల్ ప్రారంభంలో అందించబడని వేరియబుల్ పేర్లు |
transfer_number | string | null | కాల్ బదిలీ చేయబడినప్పుడు సెట్ అవుతుంది |
recording_url | string | null | గడువు ముగిసే సంతకం చేసిన URL; వెంటనే డౌన్లోడ్ చేయండి. రికార్డింగ్ ఆర్టిఫాక్ట్ అందుబాటులో లేనప్పుడు null |
billable_minutes | number | బిల్ చేయబడిన నిమిషాలు, సమీప క్వార్టర్ నిమిషానికి రౌండ్ చేయబడతాయి (15-సెకన్ల ఇంక్రిమెంట్లు, కనిష్ఠం 0.25). నేరుగా వాయిస్మెయిల్కు వెళ్లే కాల్లు కూడా వాటి వాస్తవ మీటర్ చేసిన నిమిషాలను ఇక్కడ నివేదిస్తాయి, కానీ ఛార్జీ ప్లాన్ రేటు వద్ద ఒక నిమిషానికి పరిమితం చేయబడుతుంది. |
billing_total_cents | integer | USD సెంట్లు |
transcripts | array | ప్రతి టర్న్కు ట్రాన్స్క్రిప్ట్ ఎంట్రీలు; ట్రాన్స్క్రిప్ట్ అందుబాటులో లేనప్పుడు ఖాళీగా ఉండవచ్చు |
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 |
ముగింపు కారణాలు
| విలువ | అర్థం |
|---|---|
user_hangup | రిమోట్ పక్షం ముందుగా కాల్ను ముగించింది |
ai_hangup | AI ఉద్దేశపూర్వకంగా కాల్ను ముగించింది |
ai_transfer | AI కాల్ను బదిలీ చేసింది; transfer_number సెట్ చేయబడుతుంది |
ai_warm_transfer | AI వార్మ్ (అటెండెడ్) బదిలీని పూర్తి చేసింది |
voicemail_hangup | వాయిస్మెయిల్ గుర్తించబడింది మరియు మీ voicemail_action ప్రకారం కాల్ ముగిసింది |
max_duration | కాల్ గరిష్ఠ వ్యవధి పరిమితిని చేరుకుంది |
superseded | సెషన్ను కొత్తది భర్తీ చేసింది |
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 | string | user, model, tool, లేదా system |
content_type | string | మాటల కోసం text/plain; టూల్ కాల్లు, టూల్ ఫలితాలు, మరియు సిస్టమ్ ఈవెంట్ల కోసం application/json |
content | string | object | మాటల టెక్స్ట్ లేదా పైన చూపిన నిర్మాణాత్మక ఆబ్జెక్ట్. టూల్ కాల్లు: {"tool_call": name, "arguments": {…}}. టూల్ ఫలితాలు: {"tool_name": name, "response": {…}} |
start_ms, end_ms | integer | కాల్ ప్రారంభం నుంచి ఆఫ్సెట్లు, ms. ఆడియో టైమింగ్ తెలిసినప్పుడు ఉంటుంది |
ttfa_ms | integer | కొలిచినప్పుడు, model టర్న్ కోసం మొదటి ఆడియో వరకు సమయం |
audio_url, audio_urls | string / array | ప్రతి టర్న్కు రికార్డ్ చేసినప్పుడు, ఆ టర్న్ ఆడియో కోసం గడువు ముగిసే సంతకంతో కూడిన URLలు |
ఇంటరప్షన్ మార్కర్లు, అంగీకార promptలు, మరియు రా పొజిషన్లతో పూర్తి
నిర్మాణాత్మక టర్న్ హిస్టరీ కోసం,
GET /v1/calls/{call_id}/history ఉపయోగించండి.
లెగసీ పేలోడ్ తేడాలు
లెగసీ సింగిల్-URL వెబ్హుక్ ఎన్వలప్
{"type": "telephony.complete" | "web.complete", "data": {…}}; ఇందులో
event_id ఉండదు, మరియు దాని data, ఎండ్పాయింట్ పేలోడ్కు భిన్నంగా ఉంటుంది:
లెగసీ కంప్లీషన్ పేలోడ్లో agent_id మరియు agent_name కూడా ఉంటాయి.
- టర్న్ అరే
transcriptsకింద కాకుండాhistoryకింద ఉంటుంది (పైన ఉన్నదే టర్న్ స్కీమా). - ఫీల్డ్ సెట్ అనేది కాల్ ముగింపు సమయంలోని రా రిపోర్ట్; ఇందులో పైన ఉన్న పట్టికకు మించిన అదనపు అంతర్గత ఫీల్డ్లు ఉండవచ్చు — తెలియని ఫీల్డ్లను సమాచారంగా పరిగణించండి.
- వెబ్ కాల్లు (
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 టూల్లో తెరవండి లేదా వాటిని మీ స్వంత మూల్యాంకన మోడల్ ద్వారా అమలు చేయండి.
ట్రాన్స్ఫర్ / వైఫల్యంపై మానవ సహచరుడిని ట్రిగ్గర్ చేయండి.