telephony.complete / web.complete

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

ایونٹ دونوں راستوں پر پہنچایا جاتا ہے:

• Webhook endpoints کو telephony.complete (فون کالز) یا web.complete (ویب کالز اور بلڈر مائیک ٹیسٹ کالز) موصول ہوتا ہے، جس میں ذیل میں دستاویزی مستحکم payload، ہر ڈیلیوری کے لیے ایک event_id، 30 سیکنڈ کا ٹائم آؤٹ، اور 24 گھنٹے تک دوبارہ کوششیں شامل ہیں۔
• پرانے سنگل-URL webhook کو قدرے مختلف payload کے ساتھ ایک ہم وقت کوشش موصول ہوتی ہے (10 سیکنڈ کا ٹائم آؤٹ، کوئی دوبارہ کوشش نہیں) — دیکھیں پرانے payload کے فرق۔

درخواست payload (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",
    "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,
    "voice": "john"
  },
  "event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "type": "telephony.complete"
}

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

ٹرانسکرپٹ فارمیٹ

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"] }
    }
  }
]

مکمل اسٹرکچرڈ ٹرن ہسٹری کے لیے (جس میں مداخلت کے مارکرز، ack-prompts، اور خام پوزیشنز شامل ہیں)، GET /v1/calls/{call_id}/history استعمال کریں۔

پرانے payload کے فرق

پرانا سنگل-URL webhook envelope {"type": "telephony.complete" | "web.complete", "data": {…}} ہے، جس میں کوئی event_id نہیں ہوتا، اور اس کا data endpoint payload سے مختلف ہے:

• ٹرن array، transcripts کے بجائے history کے تحت ہوتا ہے (اوپر والا ہی ٹرن schema)۔
• فیلڈ سیٹ خام end-of-call رپورٹ ہے اور اس میں اوپر دی گئی جدول سے اضافی اندرونی فیلڈز شامل ہو سکتے ہیں — نامعلوم فیلڈز کو معلوماتی سمجھیں۔
• ویب کالز (direction: "web") میں from_number / to_number شامل نہیں ہوتے اور origin_domain شامل کیا جاتا ہے۔
• Builder مائیک ٹیسٹ کالز پرانے path میں telephony.complete کے طور پر رپورٹ ہوتی ہیں (endpoint سسٹم انہیں web.complete سے میپ کرتا ہے)۔
• ٹرانسفر کوآرڈینیشن: جب کال ٹرانسفر میں ختم ہوتی ہے، تو پرانے webhook کو synchronously کال کیا جاتا ہے اور ہینڈ آف ہدف کے تیار نہ ہونے کا اشارہ دینے کے لیے یہ {"transfer_ready": false} واپس کر سکتا ہے۔ کوئی بھی دوسرا جواب (یا پرانا webhook نہ ہونا) ٹرانسفر کو جاری رہنے دیتا ہے۔ اس مقصد کے لیے endpoint deliveries سے کبھی مشورہ نہیں کیا جاتا۔

ہینڈلر کی مثال

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 });
  },
);

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

متعلقہ