ThunderPhone v3 এখন লাইভ।নিজেই ব্যবহার শুরু করুন, 2¢/মিনিট থেকে।ঘোষণাটি পড়ুন

Webhooks

telephony.complete / web.complete

ট্রান্সক্রিপ্ট, রেকর্ডিং URL এবং মেট্রিক্সসহ কল শেষ হলে নন-ব্লকিং webhook পাঠানো হয়।

প্রতিটি কল শেষ হওয়ার পরে একটি completion ইভেন্ট ফায়ার হয় — ইনবাউন্ড টেলিফোনি, আউটবাউন্ড টেলিফোনি, ওয়েব কল বা টেস্ট কল (builder mic সেশন)। এটি ব্লকিং নয়: যেকোনো 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। ঐতিহাসিক payload-এ পুরোনো mic বা widget মান থাকতে পারে
from_number, to_numberstringE.164। ওয়েব কল এবং টেস্ট কলের জন্য from_number-এর আক্ষরিক মান "web"
origin_domainstringশুধু ওয়েব/টেস্ট — যে পৃষ্ঠার origin-এ widget হোস্ট করা ছিল (mic সেশনের জন্য খালি)
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কলের সময় কার্যকর এজেন্ট config
variablesobjectকল শুরু হওয়ার সময় snapshot নেওয়া ইনপুট ভেরিয়েবল
unresolved_variablesarrayকল config-এ উল্লেখিত কিন্তু কল শুরুর সময় সরবরাহ না করা ভেরিয়েবলের নাম
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 | nullUSD সেন্ট। 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-এ লেখা; তা না থাকলে প্রতিষ্ঠানের সারসংক্ষেপের ভাষায়; সেটিও না থাকলে কলের ভাষায়: কলটি অন্যভাবে নির্ধারণ না করলে এজেন্টের প্রাথমিক ভাষা) যখন এজেন্ট বিল্ডারের সংগ্রহের জন্য ডেটা-র অধীনে এজেন্টের কলের সারসংক্ষেপ তৈরি করুন চালু থাকে (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_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শুধু সেই কলগুলোর জন্য যাদের এজেন্টের ধাপ বা handoff আছে। কলটি যেসব ক্রমে সেগুলোর মধ্য দিয়ে গেছে: প্রতিটি এন্ট্রিতে t_ms (কল শুরুর পর থেকে মিলিসেকেন্ড), agent (এজেন্টের key, a এবং তার ID), step (ধাপের ID, অথবা ধাপবিহীন এজেন্টে handoff হলে null) এবং via (start, model, condition, on_enter অথবা handoff) থাকে। শুধু ID ও সময় ধারণ করে, তাই রেকর্ডিং বন্ধ থাকলেও এটি রাখা হয়
collected_valuesobjectশুধু সেই কলগুলোর জন্য যাদের এজেন্টের ধাপ বা handoff আছে। collect ক্ষেত্রের নাম অনুসারে key করা, এজেন্ট তার ধাপগুলোতে সংগ্রহ করা মান এবং প্রতিটি ধাপের 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প্রতি-টার্নে রেকর্ড করা হলে টার্নের অডিওর জন্য মেয়াদোত্তীর্ণ সাইন করা 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 না থাকলে) ট্রান্সফারকে এগোতে দেয়। এন্ডপয়েন্ট ডেলিভারি এ ক্ষেত্রে কখনো পরামর্শ করা হয় না।

উদাহরণ হ্যান্ডলার

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 টুলে খুলুন, অথবা আপনার নিজস্ব মূল্যায়ন মডেলের মাধ্যমে চালান।

বিজ্ঞপ্তি

ট্রান্সফার / ব্যর্থতার ক্ষেত্রে একজন মানব সহকর্মীকে ট্রিগার করুন।


সম্পর্কিত