Open in
telephony.complete / web.complete
ট্রান্সক্রিপ্ট, রেকর্ডিং URL এবং মেট্রিক্সসহ কল শেষ হলে নন-ব্লকিং webhook পাঠানো হয়।
প্রতিটি কল শেষ হওয়ার পরে একটি completion ইভেন্ট ফায়ার হয় — ইনবাউন্ড টেলিফোনি, আউটবাউন্ড টেলিফোনি, ওয়েব কল বা টেস্ট কল (builder mic সেশন)। এটি ব্লকিং নয়: যেকোনো 2xx দিয়ে সাড়া দিন।
ইভেন্টটি উভয় পথে ডেলিভার করা হয়:
- Webhook এন্ডপয়েন্ট গ্রহণ করে
telephony.complete(ফোন কল) বাweb.complete(ওয়েব কল এবং builder mic টেস্ট কল), নিচে নথিভুক্ত স্থিতিশীল payload, প্রতি-ডেলিভারিরevent_id, 30 s timeout এবং 24 h পর্যন্ত পুনরায় চেষ্টা সহ। - লিগ্যাসি single-URL webhook সামান্য ভিন্ন payload সহ একটি synchronous চেষ্টা গ্রহণ করে (10 s timeout, কোনো পুনরায় চেষ্টা নেই) — দেখুন লিগ্যাসি 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। ঐতিহাসিক payload-এ পুরোনো mic বা widget মান থাকতে পারে |
from_number, to_number | string | E.164। ওয়েব কল এবং টেস্ট কলের জন্য from_number-এর আক্ষরিক মান "web" |
origin_domain | string | শুধু ওয়েব/টেস্ট — যে পৃষ্ঠার origin-এ widget হোস্ট করা ছিল (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 এবং আপনি যে প্ল্যাটফর্ম থেকে স্থানান্তর করছেন সেটি পরিচালিত আউটবাউন্ড কলের migration.call.complete ইভেন্টে সবসময় null। কল অবজেক্ট-এর মতোই মান |
product, voice | string | কলের সময় কার্যকর এজেন্ট config |
variables | object | কল শুরু হওয়ার সময় snapshot নেওয়া ইনপুট ভেরিয়েবল |
unresolved_variables | array | কল config-এ উল্লেখিত কিন্তু কল শুরুর সময় সরবরাহ না করা ভেরিয়েবলের নাম |
transfer_number | string | null | কল ট্রান্সফার হলে সেট করা হয় |
scheduled_send_id | string | শুধু একটি নির্ধারিত পাঠানো থেকে করা কলে: সেই পাঠানোর id। অন্য সব কলে অনুপস্থিত |
recording_url | string | null | মেয়াদ শেষ হওয়া স্বাক্ষরিত URL; দ্রুত ডাউনলোড করুন। কোনো রেকর্ডিং আর্টিফ্যাক্ট উপলব্ধ না থাকলে null |
recording_stopped_at | timestamp | null | কল শেষ হওয়ার আগে রেকর্ডিং কখন বন্ধ করা হয়েছিল; এই সময়ের পরের কিছুই রেকর্ডিংয়ে থাকে না। রেকর্ডিং কলের শেষ পর্যন্ত চললে বা কল রেকর্ড করা না হলে null |
recording_stopped_reason | string | null | রেকর্ডিং আগে কেন বন্ধ হয়েছে। warm_transfer: একটি উষ্ণ ট্রান্সফার গন্তব্যে কল করার ঠিক আগে এটি বন্ধ হয় এবং ট্রান্সফার ব্যর্থ হয়ে কলার এজেন্টের কাছে ফিরে এলেও বন্ধই থাকে। অন্য মানগুলোকে তথ্যমূলক হিসেবে বিবেচনা করুন; আরও মান যোগ হতে পারে। recording_stopped_at null হলে null |
billable_minutes | number | বিল করা মিনিট, নিকটতম এক-চতুর্থাংশ মিনিটে রাউন্ড করা (15-সেকেন্ডের বৃদ্ধি, সর্বনিম্ন 0.25)। সরাসরি voicemail-এ যাওয়া কলও এখানে তাদের প্রকৃত মিটার করা মিনিট জানায়, তবে চার্জ প্ল্যান রেটে এক মিনিটে সীমাবদ্ধ থাকে। |
billing_total_cents | integer | null | USD সেন্ট। billing_pending true থাকা অবস্থায় null |
billing_pending | boolean | শুধু এমন মিটার করা কলে true হিসেবে থাকে যার চার্জ এখনো নিষ্পত্তি হয়নি: ব্যবহার গণনায় আসার পর, কল শেষ হওয়ার কয়েক মিনিট পরে মিটার করা কলের চার্জ করা হয়, তাই এখানে billable_minutes এবং billing_total_cents null থাকে এবং চার্জটি call.billed-এ আসে। অন্য সব কলে অনুপস্থিত |
transcripts | array | প্রতি টার্নের transcript এন্ট্রি; transcript উপলব্ধ না হলে খালি হতে পারে |
summary | string | null | সরল ভাষায় কল-পরবর্তী সারসংক্ষেপ (2 থেকে 4টি গদ্য বাক্য, সর্বোচ্চ 2,000 অক্ষর, এজেন্টের summary_language-এ লেখা; তা না থাকলে প্রতিষ্ঠানের সারসংক্ষেপের ভাষায়; সেটিও না থাকলে কলের ভাষায়: কলটি অন্যভাবে নির্ধারণ না করলে এজেন্টের প্রাথমিক ভাষা) যখন এজেন্ট বিল্ডারের সংগ্রহের জন্য ডেটা-র অধীনে এজেন্টের কলের সারসংক্ষেপ তৈরি করুন চালু থাকে (Agent-এ call_summary_enabled) এবং তৈরি সফল হয়; অন্যথায় null, যার মধ্যে সারসংক্ষেপের জন্য অতিরিক্ত ছোট কল, transcript-বিহীন কল এবং রেকর্ডিং বন্ধ থাকা এজেন্টও অন্তর্ভুক্ত। extraction-এর মতো একই কল-পরবর্তী ধাপে সারসংক্ষেপ তৈরি হয়, তাই কল-সমাপ্ত webhook পাঠানোর আগে extracted data-এর জন্য অপেক্ষা করুন সেটিং (extraction_blocks_completion) নির্ধারণ করে এই ইভেন্ট এটির জন্য অপেক্ষা করবে কি না: অপেক্ষা মোডে এই ইভেন্ট পাঠানোর আগে সারসংক্ষেপ প্রস্তুত থাকে (ধাপের 75-সেকেন্ড বাজেটের মধ্যে সারসংক্ষেপটি সর্বোচ্চ 30 সেকেন্ড পায়); ইভেন্ট অপেক্ষা না করলে (never, অথবা except_transfers-এর অধীনে একটি ট্রান্সফার বা আপনার contact center-এ ফেরা) এই ক্ষেত্রটি null থাকে এবং সারসংক্ষেপটি call.data_extracted-এ পুনরায় পাঠানো হয় না, তাই পরে কল অবজেক্ট-এর summary থেকে পড়ুন। ড্যাশবোর্ডের কল পৃষ্ঠাতেও উপলব্ধ |
extracted_data | object | null | status, fields, evidence, verification, field_reasons এবং schema_version-সহ কাঠামোবদ্ধ extraction ফলাফল। প্রতিটি non-null ক্ষেত্রে সঠিকভাবে কাঠামোগত যাচাই করা উদ্ধৃতি (সর্বোচ্চ 1,000 অক্ষর), সঙ্গে তার বক্তার ভূমিকা ও টার্ন সূচক থাকে; মডেল-ফেরত দীর্ঘ উদ্ধৃতি সংক্ষিপ্ত করার পরিবর্তে প্রত্যাখ্যান করা হয়। ক্ষেত্রটি null হলে evidence null। verified অর্থ প্রতিটি প্রার্থী ঠিক একটি বৈধ স্বতন্ত্র রায় পেয়েছে। unavailable বিকৃত বা আংশিক verifier আউটপুটও অন্তর্ভুক্ত করে; বৈধ আংশিক রায় এখনও প্রযোজ্য হয়, আর একটি বৈধ রায় ছাড়া প্রার্থীগুলোকে null করা হয়। status হলো completed, failed, exhausted, skipped, অথবা skipped_recording_disabled; এজেন্টের কোনো extraction ক্ষেত্র না থাকলে null |
steps_trace | array | শুধু সেই কলগুলোর জন্য যাদের এজেন্টের ধাপ বা handoff আছে। কলটি যেসব ক্রমে সেগুলোর মধ্য দিয়ে গেছে: প্রতিটি এন্ট্রিতে t_ms (কল শুরুর পর থেকে মিলিসেকেন্ড), agent (এজেন্টের key, a এবং তার ID), step (ধাপের ID, অথবা ধাপবিহীন এজেন্টে handoff হলে null) এবং via (start, model, condition, on_enter অথবা handoff) থাকে। শুধু ID ও সময় ধারণ করে, তাই রেকর্ডিং বন্ধ থাকলেও এটি রাখা হয় |
collected_values | object | শুধু সেই কলগুলোর জন্য যাদের এজেন্টের ধাপ বা handoff আছে। collect ক্ষেত্রের নাম অনুসারে key করা, এজেন্ট তার ধাপগুলোতে সংগ্রহ করা মান এবং প্রতিটি ধাপের 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 | 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 |
সম্পূর্ণ কাঠামোবদ্ধ টার্ন ইতিহাসের জন্য (ইন্টারাপশন মার্কার,
ack-prompt এবং কাঁচা অবস্থানসহ), ব্যবহার করুন
GET /v1/calls/{call_id}/history।
লিগ্যাসি পেলোডের পার্থক্য
লিগ্যাসি একক-URL webhook এনভেলপ হলো
{"type": "telephony.complete" | "web.complete", "data": {…}}, যেখানে
কোনো event_id নেই, এবং এর data এন্ডপয়েন্ট পেলোড থেকে আলাদা:
লিগ্যাসি কমপ্লিশন পেলোডে agent_id এবং agent_name-ও থাকে।
- টার্ন অ্যারেটি
transcriptsনয়,history-এর অধীনে থাকে (উপরের মতো একই টার্ন স্কিমা)। - ক্ষেত্র সেটটি কাঁচা কল-শেষ রিপোর্ট এবং এতে উপরের টেবিলের বাইরেও অতিরিক্ত অভ্যন্তরীণ ক্ষেত্র থাকতে পারে — অজানা ক্ষেত্রগুলোকে তথ্যগত হিসেবে বিবেচনা করুন।
- ওয়েব কল (
direction: "web")from_number/to_numberবাদ দেয় এবংorigin_domainযোগ করে। - Builder মাইক টেস্ট কল লিগ্যাসি
পাথে
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 সিগন্যাল নিষ্কাশন বা ট্রান্সফার-রেট পর্যবেক্ষণের জন্য ট্রান্সক্রিপ্ট একটি পাইপলাইনে স্ট্রিম করুন।
মানব পর্যালোচনার জন্য কল QA টুলে খুলুন, অথবা আপনার নিজস্ব মূল্যায়ন মডেলের মাধ্যমে চালান।
ট্রান্সফার / ব্যর্থতার ক্ষেত্রে একজন মানব সহকর্মীকে ট্রিগার করুন।