ThunderPhone v3 اب لائیو ہے۔سیلف سرو، قیمت 2¢ فی منٹ سے شروع۔اعلان پڑھیں

Webhooks

telephony.complete / web.complete

کال ختم ہونے پر فراہم کیا جانے والا نان بلاکنگ webhook، جس میں ٹرانسکرپٹ، ریکارڈنگ URL، اور میٹرکس شامل ہوتے ہیں۔

ہر کال ختم ہونے کے بعد ایک تکمیلی ایونٹ فائر ہوتا ہے — ان باؤنڈ ٹیلی فونی، آؤٹ باؤنڈ ٹیلی فونی، ویب کال، یا ٹیسٹ کال (بلڈر مائیک سیشن)۔ یہ نان بلاکنگ ہے: کسی بھی 2xx کے ساتھ جواب دیں۔

ایونٹ دونوں راستوں پر ڈیلیور کیا جاتا ہے:

درخواست کا پے لوڈ (اینڈ پوائنٹ ڈیلیوریز)

{
  "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_idintegerاس کال کے ہر ایونٹ میں مستقل رہتا ہے
agent_idinteger | nullکال سنبھالنے والا ایجنٹ، جب کوئی ایجنٹ مقرر کیا گیا ہو
agent_namestring | nullکال سنبھالنے والا ایجنٹ، جب کوئی ایجنٹ مقرر کیا گیا ہو
directionstringinbound، outbound، web، test۔ تاریخی payloads میں پرانی mic یا widget قدریں شامل ہو سکتی ہیں
from_number, to_numberstringE.164۔ ویب کالز اور ٹیسٹ کالز کے لیے from_number کی لفظی قدر "web" ہوتی ہے
origin_domainstringصرف ویب/ٹیسٹ کے لیے — وہ صفحہ origin جس نے وِجٹ کو ہوسٹ کیا تھا (مائیک سیشنز کے لیے خالی)
start_time, end_timetimestampISO 8601 UTC
duration_secondsinteger | nullآغاز/اختتام سے اخذ کردہ
statusstringcompleted یا failed
end_reasonstringنیچے دی گئی جدول دیکھیں
answered_bystring | nullصرف آؤٹ باؤنڈ فون کالز کے لیے (ورنہ موجود نہیں): کس نے جواب دیا، human، voicemail، screener (کال اسکریننگ اسسٹنٹ)، ivr (فون مینو) یا unknown۔ جب کسی نے جواب نہ دیا ہو تو null، اور ان آؤٹ باؤنڈ کالز کے لیے migration.call.complete ایونٹس میں ہمیشہ null جنہیں اس پلیٹ فارم نے سنبھالا ہو جس سے آپ منتقل ہو رہے ہیں۔ کال آبجیکٹ جیسی ہی قدریں
product, voicestringکال کے وقت نافذ ایجنٹ کنفیگ
variablesobjectکال شروع ہونے پر محفوظ کیے گئے ان پٹ variables
unresolved_variablesarrayوہ variable نام جن کا حوالہ کال کنفیگ میں دیا گیا ہو لیکن کال شروع ہونے پر فراہم نہ کیے گئے ہوں
transfer_numberstring | nullکال منتقل ہونے پر سیٹ ہوتا ہے
scheduled_send_idstringصرف شیڈول شدہ بھیجنے کے ذریعے کی گئی کال پر: اس بھیجنے کی id۔ ہر دوسری کال پر موجود نہیں
recording_urlstring | nullمیعاد ختم ہونے والا دستخط شدہ URL؛ فوراً ڈاؤن لوڈ کریں۔ جب ریکارڈنگ آرٹیفیکٹ دستیاب نہ ہو تو null
recording_stopped_attimestamp | nullجب کال ختم ہونے سے پہلے ریکارڈنگ روک دی گئی ہو؛ اس لمحے کے بعد کی کوئی چیز ریکارڈنگ میں شامل نہیں ہوتی۔ جب ریکارڈنگ کال کے اختتام تک جاری رہی ہو یا کال ریکارڈ نہ کی گئی ہو تو null
recording_stopped_reasonstring | nullریکارڈنگ جلد کیوں رکی۔ warm_transfer: وارم ٹرانسفر کے منزل کو کال کرنے سے فوراً پہلے یہ رک جاتی ہے، اور ٹرانسفر ناکام ہونے اور کالر کے ایجنٹ کے پاس واپس آنے پر بھی بند رہتی ہے۔ دیگر قدروں کو معلوماتی سمجھیں؛ مزید قدریں شامل کی جا سکتی ہیں۔ جب recording_stopped_at null ہو تو null
billable_minutesnumberبل کیے گئے منٹ، قریب ترین چوتھائی منٹ تک گول کیے گئے (15 سیکنڈ کے اضافے، کم از کم 0.25)۔ براہِ راست voicemail جانے والی کالز بھی یہاں اپنے اصل میٹر شدہ منٹ رپورٹ کرتی ہیں، مگر چارج پلان ریٹ پر ایک منٹ تک محدود ہوتا ہے۔
billing_total_centsinteger | nullامریکی ڈالر سینٹس۔ جب billing_pending true ہو تو null
billing_pendingbooleanصرف ایسی میٹر شدہ کال پر true کے طور پر موجود ہوتا ہے جس کا چارج ابھی طے نہیں ہوا: میٹر شدہ کال کا چارج اس کے ختم ہونے کے چند منٹ بعد، استعمال موصول ہونے پر، لگتا ہے، اس لیے یہاں billable_minutes اور billing_total_cents null ہوتے ہیں اور چارج call.billed میں آتا ہے۔ ہر دوسری کال پر موجود نہیں
transcriptsarrayہر ٹرن کے transcript اندراجات؛ transcript دستیاب نہ ہونے پر خالی ہو سکتے ہیں
summarystring | 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_dataobject | nullstatus، 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_tracearrayصرف ان کالز پر جن کے ایجنٹ کے پاس steps یا handoffs ہوں۔ وہ ترتیب جس میں کال ان سے گزری: ہر اندراج میں t_ms (کال شروع ہونے کے بعد ملی سیکنڈز)، agent (ایجنٹ کی کلید، a کے بعد اس کی ID)، step (step ID، یا steps کے بغیر ایجنٹ کو handoff ہونے پر null) اور via (start، model، condition، on_enter یا handoff) شامل ہوتے ہیں۔ صرف IDs اور اوقات رکھتا ہے، اس لیے ریکارڈنگ بند ہونے پر بھی محفوظ رہتا ہے
collected_valuesobjectصرف ان کالز پر جن کے ایجنٹ کے پاس steps یا handoffs ہوں۔ وہ قدریں جو ایجنٹ نے اپنے steps میں جمع کیں، collect فیلڈ نام کے لحاظ سے کلید بند، نیز ہر step کے on_enter_tool نتیجے کے لیے <tool>_result۔ جب کال کا مواد برقرار نہ رکھا جائے (ریکارڈنگ بند ہو) تو شامل نہیں ہوتا

اختتام کی وجوہات

قدرمعنی
user_hangupدوسری طرف کے فریق نے پہلے کال ختم کی
ai_hangupAI نے جان بوجھ کر کال ختم کی
ai_transferAI نے کال منتقل کی؛ transfer_number سیٹ ہے
ai_warm_transferAI نے وارم (نگرانی کے ساتھ) منتقلی مکمل کی
returned_to_platformAI نے کال آپ کے کانٹیکٹ سینٹر کو واپس کی: اس نے کال ختم کی، اور اگر واپسی اندراج کے ہیڈرز موجود تھے تو وہ 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"] }
    }
  }
]
فیلڈقسمتفصیل
rolestringuser، model، tool، یا system
content_typestringگفتگو کے لیے text/plain؛ ٹول کالز، ٹول نتائج، اور سسٹم واقعات کے لیے application/json
contentstring | objectگفتگو کا متن، یا اوپر دکھایا گیا اسٹرکچرڈ آبجیکٹ۔ ٹول کالز: {"tool_call": name, "arguments": {…}}۔ ٹول نتائج: {"tool_name": name, "response": {…}}
start_ms, end_msintegerکال کے آغاز سے آفسیٹس، ms۔ آڈیو ٹائمنگ معلوم ہونے پر موجود ہوتے ہیں
ttfa_msintegerناپے جانے پر model باری کے لیے پہلے آڈیو تک کا وقت
audio_url, audio_urlsstring / 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} جواب دے سکتا ہے کہ ہینڈ آف ہدف تیار نہیں ہے۔ کوئی بھی دوسرا جواب (یا لیگیسی ویب ہک کا نہ ہونا) ٹرانسفر کو جاری رہنے دیتا ہے۔ اس مقصد کے لیے اینڈ پوائنٹ ڈیلیوریز سے کبھی مشورہ نہیں لیا جاتا۔

مثال ہینڈلر

Python (FastAPI)
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}
Node.js (Express)
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 });
  },
);

عام استعمال کے معاملات

CRM انضمام

ہر کال کی ٹرانسکرپٹ اور ریکارڈنگ URL کو اپنے کسٹمر ریکارڈز کے ساتھ محفوظ کریں۔

تجزیات

موضوعاتی ماڈلنگ، CSAT سگنل اخذ کرنے، یا ٹرانسفر کی شرح کی نگرانی کے لیے ٹرانسکرپٹس کو پائپ لائن میں اسٹریم کریں۔

معیار کا جائزہ

انسانی جائزے کے لیے کالز کو QA ٹول میں کھولیں، یا انہیں اپنے تشخیصی ماڈل کے ذریعے چلائیں۔

اطلاعات

ٹرانسفر یا ناکامی پر انسانی ٹیم کے رکن کو متحرک کریں۔


متعلقہ