Open in
telephony.complete / web.complete
कॉल समाप्त झाल्यावर ट्रान्सक्रिप्ट, रेकॉर्डिंग URL आणि मेट्रिक्ससह वितरित केला जाणारा नॉन-ब्लॉकिंग webhook.
प्रत्येक कॉल संपल्यानंतर पूर्णता इव्हेंट ट्रिगर होतो — इनबाउंड टेलिफोनी, आउटबाउंड टेलिफोनी, वेब कॉल किंवा टेस्ट कॉल (बिल्डर माइक सत्र). तो नॉन-ब्लॉकिंग आहे: कोणत्याही 2xx सह प्रतिसाद द्या.
इव्हेंट दोन्ही मार्गांवर वितरित केला जातो:
- Webhook एंडपॉइंट्स यांना
telephony.complete(फोन कॉल) किंवाweb.complete(वेब कॉल आणि बिल्डर माइक टेस्ट कॉल) खाली दस्तऐवजीकरण केलेल्या स्थिर पेलोडसह, प्रत्येक वितरणासाठीevent_id, 30 s टाइमआउट आणि 24 h पर्यंत पुनःप्रयत्न प्राप्त होतात. - लेगसी सिंगल-URL webhook ला किंचित वेगळ्या पेलोडसह एक समकालिक प्रयत्न प्राप्त होतो (10 s टाइमआउट, पुनःप्रयत्न नाहीत) — पहा लेगसी पेलोडमधील फरक.
विनंती पेलोड (endpoint वितरणांसाठी)
{
"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 | स्ट्रिंग | केवळ वेब/चाचणीसाठी — विजेट होस्ट करणाऱ्या पेजचा उगम (mic सत्रांसाठी रिक्त) |
start_time, end_time | टाइमस्टॅम्प | ISO 8601 UTC |
duration_seconds | पूर्णांक | null | सुरुवात/समाप्तीवरून व्युत्पन्न |
status | स्ट्रिंग | completed किंवा failed |
end_reason | स्ट्रिंग | खालील तक्ता पहा |
answered_by | स्ट्रिंग | null | केवळ आउटबाउंड फोन कॉलसाठी (अन्यथा अनुपस्थित): कोणी उत्तर दिले, human, voicemail, screener (कॉल स्क्रीनिंग सहाय्यक), ivr (फोन मेनू) किंवा unknown. कोणीही उत्तर न दिल्यास null, आणि तुम्ही ज्या प्लॅटफॉर्मवरून स्थलांतर करत आहात त्या प्लॅटफॉर्मने हाताळलेल्या आउटबाउंड कॉलसाठी migration.call.complete इव्हेंटमध्ये नेहमी null. कॉल ऑब्जेक्ट प्रमाणेच मूल्ये |
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: वॉर्म ट्रान्सफर गंतव्याला कॉल करण्यापूर्वी ते थांबते, आणि ट्रान्सफर अयशस्वी होऊन कॉलर एजंटकडे परत आला तरी बंदच राहते. इतर मूल्यांना माहितीपर माना; आणखी मूल्ये जोडली जाऊ शकतात. recording_stopped_at हे null असल्यास null |
billable_minutes | संख्या | बिल केलेली मिनिटे, जवळच्या पाव मिनिटापर्यंत पूर्णांकित (15-सेकंद वाढी, किमान 0.25). थेट व्हॉइसमेलवर जाणारे कॉलही येथे त्यांची वास्तविक मोजलेली मिनिटे नोंदवतात, परंतु शुल्क प्लॅन दराने एका मिनिटापुरते मर्यादित असते. |
billing_total_cents | पूर्णांक | null | USD सेंट. billing_pending हे true असताना null |
billing_pending | बूलियन | केवळ ज्या मोजलेल्या कॉलचे शुल्क अद्याप निकाली निघालेले नाही अशा कॉलवर true म्हणून उपस्थित: मोजलेल्या कॉलचे शुल्क तो संपल्यानंतर काही मिनिटांनी, त्याचा वापर प्राप्त झाल्यावर आकारले जाते, म्हणून येथे billable_minutes आणि billing_total_cents हे null असतात आणि शुल्क call.billed मध्ये येते. इतर प्रत्येक कॉलवर अनुपस्थित |
transcripts | अॅरे | प्रत्येक टर्नसाठी ट्रान्सक्रिप्ट नोंदी; ट्रान्सक्रिप्ट उपलब्ध नसल्यास रिक्त असू शकतात |
summary | स्ट्रिंग | null | साध्या भाषेतील कॉलनंतरचा सारांश (गद्याची दोन ते चार वाक्ये, कमाल 2,000 वर्ण, एजंटच्या summary_language मध्ये, अन्यथा संस्थेच्या सारांश भाषेत, अन्यथा कॉलच्या भाषेत: कॉलने ती बदलली नसल्यास एजंटची प्राथमिक भाषा) जेव्हा एजंट बिल्डरमध्ये कॉल सारांश तयार करा हे गोळा करायचा डेटा अंतर्गत चालू असते (call_summary_enabled हे Agent वर) आणि निर्मिती यशस्वी होते; अन्यथा null, यामध्ये सारांशासाठी खूप लहान कॉल, ट्रान्सक्रिप्ट नसलेले कॉल आणि रेकॉर्डिंग बंद असलेले एजंट समाविष्ट आहेत. सारांश एक्स्ट्रॅक्शनप्रमाणेच कॉलनंतरच्या टप्प्यात तयार होतो, म्हणून कॉल-पूर्ण वेबहुक पाठवण्यापूर्वी एक्स्ट्रॅक्ट केलेल्या डेटाची प्रतीक्षा करा ही सेटिंग (extraction_blocks_completion) हा इव्हेंट त्याची प्रतीक्षा करतो की नाही हे ठरवते: प्रतीक्षा मोडमध्ये हा इव्हेंट पाठवण्यापूर्वी सारांश तयार असतो (सारांशाला स्वतःला टप्प्याच्या 75-सेकंद बजेटमध्ये जास्तीत जास्त 30 सेकंद मिळतात); इव्हेंट प्रतीक्षा करत नसल्यास (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 | ऑब्जेक्ट | केवळ ज्या कॉलच्या एजंटकडे स्टेप्स किंवा हँडऑफ्स आहेत अशा कॉलवर. एजंटने त्याच्या स्टेप्समध्ये गोळा केलेली मूल्ये, गोळा फील्डच्या नावानुसार की केलेली, तसेच प्रत्येक स्टेपच्या on_enter_tool निकालासाठी <tool>_result. कॉलची सामग्री जतन केली नसल्यास वगळले जाते (रेकॉर्डिंग बंद) |
समाप्तीची कारणे
| मूल्य | अर्थ |
|---|---|
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 | पूर्णांक | कॉल सुरू झाल्यापासूनचे ऑफसेट, ms. ऑडिओची वेळ ज्ञात असल्यास उपस्थित |
ttfa_ms | पूर्णांक | मोजले असल्यास, model टर्नसाठी पहिल्या ऑडिओपर्यंतचा वेळ |
audio_url, audio_urls | स्ट्रिंग / अॅरे | प्रत्येक टर्नसाठी रेकॉर्ड केले असल्यास, त्या टर्नच्या ऑडिओसाठी कालबाह्य होणारे स्वाक्षरीत URL |
पूर्ण संरचित टर्न इतिहासासाठी (व्यत्यय मार्कर,
ack-prompts, आणि कच्च्या पोझिशन्ससह), हे वापरा
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 टूलमध्ये कॉल उघडा किंवा त्यांना तुमच्या स्वतःच्या मूल्यांकन मॉडेलद्वारे चालवा.
ट्रान्सफर / अयशस्वीतेवर मानवी सहकाऱ्याला सूचित करा.