Open in
telephony.complete / web.complete
کال ختم ہونے پر فراہم کیا جانے والا نان بلاکنگ webhook، جس میں ٹرانسکرپٹ، ریکارڈنگ URL، اور میٹرکس شامل ہوتے ہیں۔
ہر کال ختم ہونے کے بعد ایک تکمیلی ایونٹ فائر ہوتا ہے — ان باؤنڈ ٹیلی فونی، آؤٹ باؤنڈ ٹیلی فونی، ویب کال، یا ٹیسٹ کال (بلڈر مائیک سیشن)۔ یہ نان بلاکنگ ہے: کسی بھی 2xx کے ساتھ جواب دیں۔
ایونٹ دونوں راستوں پر ڈیلیور کیا جاتا ہے:
- ویب ہُک اینڈ پوائنٹس کو
telephony.complete(فون کالز) یاweb.complete(ویب کالز اور بلڈر مائیک ٹیسٹ کالز) مستحکم پے لوڈ کے ساتھ موصول ہوتا ہے جو نیچے دستاویزی ہے، ہر ڈیلیوری کے لیے ایکevent_id، 30 سیکنڈ کا ٹائم آؤٹ، اور 24 گھنٹے تک دوبارہ کوششیں۔ - لیگیسی سنگل-URL ویب ہُک کو ایک قدرے مختلف پے لوڈ کے ساتھ ایک سنکرونس کوشش موصول ہوتی ہے (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_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۔ تاریخی payloads میں پرانی mic یا widget قدریں شامل ہو سکتی ہیں |
from_number, to_number | string | E.164۔ ویب کالز اور ٹیسٹ کالز کے لیے from_number کی لفظی قدر "web" ہوتی ہے |
origin_domain | string | صرف ویب/ٹیسٹ کے لیے — وہ صفحہ origin جس نے وِجٹ کو ہوسٹ کیا تھا (مائیک سیشنز کے لیے خالی) |
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 | کال کے وقت نافذ ایجنٹ کنفیگ |
variables | object | کال شروع ہونے پر محفوظ کیے گئے ان پٹ variables |
unresolved_variables | array | وہ variable نام جن کا حوالہ کال کنفیگ میں دیا گیا ہو لیکن کال شروع ہونے پر فراہم نہ کیے گئے ہوں |
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 | امریکی ڈالر سینٹس۔ جب 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 میں لکھا گیا، ورنہ تنظیم کی خلاصہ زبان میں، ورنہ کال کی زبان میں: ایجنٹ کی بنیادی زبان، جب تک کال نے اسے اووررائیڈ نہ کیا ہو) جب ایجنٹ بلڈر میں کال کا خلاصہ بنائیں کو جمع کرنے کے لیے ڈیٹا کے تحت فعال کیا گیا ہو (ایجنٹ پر call_summary_enabled) اور تخلیق کامیاب ہوئی ہو؛ ورنہ null، بشمول ان کالز کے جو خلاصے کے لیے بہت مختصر ہوں، جن کا کوئی transcript نہ ہو، اور ان ایجنٹس کے لیے جن کی ریکارڈنگ بند ہو۔ خلاصہ extraction کے ساتھ اسی post-call مرحلے میں بنایا جاتا ہے، اس لیے کال مکمل ہونے والا webhook بھیجنے سے پہلے اخذ کردہ ڈیٹا کا انتظار کریں کی ترتیب (extraction_blocks_completion) طے کرتی ہے کہ آیا یہ ایونٹ اس کا انتظار کرتا ہے: انتظار والے موڈ میں اس ایونٹ کے بھیجے جانے سے پہلے خلاصہ تیار ہوتا ہے (خلاصے کو خود مرحلے کے 75 سیکنڈ کے بجٹ میں زیادہ سے زیادہ 30 سیکنڈ ملتے ہیں)؛ جب ایونٹ انتظار نہیں کرتا (never، یا except_transfers کے تحت ٹرانسفر یا آپ کے رابطہ مرکز کو واپسی) تو یہ فیلڈ 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 | صرف ان کالز پر جن کے ایجنٹ کے پاس steps یا handoffs ہوں۔ وہ ترتیب جس میں کال ان سے گزری: ہر اندراج میں t_ms (کال شروع ہونے کے بعد ملی سیکنڈز)، agent (ایجنٹ کی کلید، a کے بعد اس کی ID)، step (step ID، یا steps کے بغیر ایجنٹ کو handoff ہونے پر null) اور via (start، model، condition، on_enter یا handoff) شامل ہوتے ہیں۔ صرف IDs اور اوقات رکھتا ہے، اس لیے ریکارڈنگ بند ہونے پر بھی محفوظ رہتا ہے |
collected_values | object | صرف ان کالز پر جن کے ایجنٹ کے پاس steps یا handoffs ہوں۔ وہ قدریں جو ایجنٹ نے اپنے steps میں جمع کیں، collect فیلڈ نام کے لحاظ سے کلید بند، نیز ہر step کے 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 | باری کی آڈیو کے لیے میعاد ختم ہونے والے سائن شدہ URLs، جب آڈیو ہر باری کے لیے ریکارڈ کی گئی ہو |
مکمل اسٹرکچرڈ باری کی ہسٹری کے لیے (جس میں مداخلت کے مارکرز،
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 ٹول میں کھولیں، یا انہیں اپنے تشخیصی ماڈل کے ذریعے چلائیں۔
ٹرانسفر یا ناکامی پر انسانی ٹیم کے رکن کو متحرک کریں۔