ইভেন্ট ক্যাটালগ

ThunderPhone যে সব webhook ইভেন্ট টাইপ পাঠায়।

প্রতিটি webhook বডিতে একটি type ফিল্ড থাকে, যার মান এই পৃষ্ঠার ইভেন্ট টাইপগুলোর একটি। আপনি যখন কোনো endpoint-এ সাবস্ক্রাইব করেন, তখন events অ্যারেতে অবশ্যই আপনার চাওয়া ইভেন্ট টাইপগুলো থাকতে হবে (অথবা সবকিছুতে সাবস্ক্রাইব করতে এটি খালি রাখতে পারেন — তবে প্রতি-টার্ন ইভেন্ট telephony.turn / web.turn ব্যতিক্রম; এগুলো কেবল সেই endpoint-এ পাঠানো হয় যেগুলোতে এগুলোর নাম স্পষ্টভাবে উল্লেখ করা থাকে)।

এই ইভেন্টগুলো দুটি ডেলিভারি পদ্ধতিতে পাঠানো হয়:

• Endpoint ডেলিভারি সবসময় non-blocking নোটিফিকেশন এবং এতে retry থাকে: যেকোনো 2xx দিয়ে উত্তর দিন; envelope-এ dedup করার জন্য একটি event_id থাকে।
• Blocking এক্সচেঞ্জ কেবল legacy single-URL webhook-এ চলে: telephony.incoming / web.incoming কনফিগারেশন রিকোয়েস্ট (webhook-mode নম্বর ও widget key, 10 s timeout) এবং webhook-mode tool dispatch। আপনার উত্তর লাইভ কলকে রূপ দেয়।

নিচের উদাহরণ payload-গুলো wire order-এ endpoint envelope দেখায় (কীগুলো বর্ণানুক্রমে সাজানো: data, event_id, type); legacy ডেলিভারিগুলো event_id ছাড়া একই data বহন করে।

কল ইভেন্ট#

telephony.incoming#

আপনার কোনো একটি ফোন নম্বরে ইনবাউন্ড কল পৌঁছালে পাঠানো হয়। এন্ডপয়েন্ট ডেলিভারিগুলো প্রতিটি ইনবাউন্ড কলের জন্য পাঠানো ফায়ার-অ্যান্ড-ফরগেট বিজ্ঞপ্তি, নম্বরটি এজেন্ট-কনফিগার করা বা webhook-কনফিগার করা যাই হোক না কেন। কোনো এজেন্ট বরাদ্দ না থাকা নম্বরগুলো লেগ্যাসি webhook-এ অতিরিক্তভাবে ব্লকিং কনফিগারেশন রিকোয়েস্ট পায় — সম্পূর্ণ রিকোয়েস্ট / রেসপন্স স্কিমার জন্য দেখুন telephony.incoming / web.incoming।

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

telephony.complete#

ইনবাউন্ড বা আউটবাউন্ড টেলিফোনি কল শেষ হলে পাঠানো হয়। নন-ব্লকিং। ট্রান্সক্রিপ্ট, উপলভ্য থাকলে রেকর্ডিং URL এবং বিলিং সারাংশ অন্তর্ভুক্ত করে। পেলোড স্কিমার জন্য দেখুন telephony.complete / web.complete।

telephony.tool#

কোনো টেলিফোনি কল একটি ফাংশন টুল আহ্বান করার পরে পাঠানো হয়। নন-ব্লকিং অডিট বিজ্ঞপ্তি — এই ইভেন্ট ডেলিভারির সময় টুলটি ইতিমধ্যে কার্যকর হয়েছে; এটি আপনার নিজস্ব ফাংশন টুলগুলোকে অন্তর্ভুক্ত করে (বিল্ট-ইন, নলেজ-বেস, অ্যাপ-কানেকশন বা MCP টুল নয়)।

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response হলো কার্যকর হওয়া ফলাফল: সফল হলে {"status": <http status>, "response": <your endpoint's JSON>}, অথবা ব্যর্থ হলে {"status": <status>, "error": "<message>"}।

telephony.turn#

টেলিফোনি কল চলমান থাকাকালে, প্রতিটি কথন-সমৃদ্ধ টার্ন ঘটার সঙ্গে সঙ্গে একবার পাঠানো হয় — এজেন্টের বলা completion এবং কলারের ট্রান্সক্রাইব করা টার্ন। পোলিংয়ের পরিবর্তে সাধারণ webhook-এর মাধ্যমে লাইভ কথোপকথন অনুসরণ করতে দেয় GET /v1/calls/{call_id}/transcript। নন-ব্লকিং।

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

web.incoming#

telephony.incoming-এর ওয়েব-চ্যানেল সমতুল্য, কোনো ওয়েব উইজেট সেশন বা বিল্ডার মাইক টেস্ট কল শুরু হলে পাঠানো হয়। এন্ডপয়েন্ট ডেলিভারিগুলো প্রতিটি ওয়েব সেশনের জন্য ফায়ার-অ্যান্ড-ফরগেট। mode="webhook"-এ থাকা পাবলিশেবল কী-গুলো লেগ্যাসি webhook-এ অতিরিক্তভাবে ব্লকিং কনফিগারেশন রিকোয়েস্ট পায় — সেই ব্লকিং রিকোয়েস্টের গঠন ভিন্ন (origin_domain, publishable_key_prefix; কোনো ফোন নম্বর নেই)। দেখুন telephony.incoming / web.incoming।

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number সবসময় আক্ষরিক "web"। webhook-মোড উইজেট সেশনের জন্য to_number খালি থাকে (কনফিগারেশনের পরে সেশনের এজেন্ট নম্বর বরাদ্দ করা হয়); বিল্ডার মাইক টেস্ট কলের জন্য origin_domain এবং publishable_key_prefix খালি থাকে।

web.complete#

telephony.complete-এর ওয়েব-চ্যানেল সমতুল্য, যা ওয়েব উইজেট কল (direction: "web") এবং বিল্ডার মাইক টেস্ট কল (direction: "test") অন্তর্ভুক্ত করে। নন-ব্লকিং। from_number-কে "web" সেট করে, origin_domain-সহ telephony.complete-এর মতো একই পেলোড গঠন।

web.tool#

telephony.tool-এর ওয়েব-চ্যানেল সমতুল্য। data-তে from_number / to_number-এর পরিবর্তে origin_domain থাকে।

web.turn#

telephony.turn-এর ওয়েব-চ্যানেল সমতুল্য, যা ওয়েব উইজেট কল এবং বিল্ডার মাইক টেস্ট কল অন্তর্ভুক্ত করে। from_number / to_number-এর পরিবর্তে origin_domain-সহ একই পেলোড গঠন। telephony.turn-এর মতো, এটির জন্য স্পষ্ট সাবস্ক্রিপশন প্রয়োজন — খালি events অ্যারের মাধ্যমে এটি কখনও ডেলিভার করা হয় না।

ভয়েস ইভেন্ট#

কাস্টম ভয়েস তৈরি অ্যাসিঙ্ক্রোনাস। এই নন-ব্লকিং ইভেন্টগুলো আপনাকে পোলিং করার পরিবর্তে একটি চূড়ান্ত ফলাফলে প্রতিক্রিয়া জানাতে দেয় ক্লোন বিস্তারিত এন্ডপয়েন্ট।

voice.ready এবং voice.failed শুধুমাত্র events: [] সহ একটি সংস্থা-ব্যাপী এন্ডপয়েন্টে পাঠানো হয়। এগুলোকে স্পষ্ট ইভেন্ট ফিল্টার হিসেবে নির্বাচন করা যায় না।

voice.ready#

একটি কাস্টম ভয়েসের প্রসেসিং শেষ হলে এবং সেটি একটি এজেন্টে বরাদ্দ করা গেলে পাঠানো হয়।

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

voice.failed#

কাস্টম ভয়েস প্রসেসিং স্থায়ী ব্যর্থতায় পৌঁছালে পাঠানো হয়।

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

গুণমান ইভেন্ট#

call.graded#

কোনো কলের জন্য AI গ্রেডিং রান সম্পন্ন হলে পাঠানো হয়। ব্লকিং নয়।

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

telephony.complete / web.complete-এর পরে দেরিতে পুনঃচেষ্টা অথবা POST /v1/calls/{call_id}/extract-এর মাধ্যমে ম্যানুয়াল পুনরায় চালানোসহ, স্ট্রাকচার্ড ডেটা এক্সট্র্যাকশন সফলভাবে সম্পন্ন হলে পাঠানো হয়। ব্লকিং নয়।

ব্লকিং এক্সট্র্যাকশন মোডে, সম্পন্ন হওয়ার ইভেন্ট সাধারণত 75-সেকেন্ডের এক্সট্র্যাকশন বাজেটের বেশি অপেক্ষা করে না। এক্সট্র্যাকশন ওয়ার্কার প্রক্রিয়া হারিয়ে গেলে, প্রোডাকশন ফাইনালাইজেশন ড্রেন (প্রতি পাঁচ মিনিটে) আরেকটি এক্সট্র্যাকশন প্রচেষ্টা শুরু করার আগে যার blocking_deadline_at পেরিয়ে গেছে এমন সম্পন্ন হওয়ার ইভেন্ট প্রকাশ করে। পরবর্তী সফলতা এই ইভেন্ট হিসেবে আলাদাভাবে পাঠানো হয়।

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "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..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "gemini-2.5-flash"
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

কোনো ক্যাম্পেইন running থেকে completed-এ গেলে একবার পাঠানো হয়, সেটির সময়সূচি শেষ হোক বা সব পরিচিতি চূড়ান্ত অবস্থায় পৌঁছাক। রানার পুনঃচেষ্টা আরেকটি ইভেন্ট পাঠায় না। এই সংস্থা-স্তরের লাইফসাইকেল ইভেন্ট শুধু সংস্থা-স্কোপড এন্ডপয়েন্টে পাঠানো হয়, এজেন্ট-স্কোপড এন্ডপয়েন্টে নয়। ব্লকিং নয়।

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

চারটি ফলাফল গণনা আলাদা এবং যোগ করলে contacts_total হয়: completed-এ সফল পরিচিতি থাকে; no_answer-এ এমন চূড়ান্ত ব্যর্থ/শেষ হয়ে যাওয়া পরিচিতি থাকে যাদের শেষ ফলাফল ছিল কোনো উত্তর নেই; failed-এ অন্য সব চূড়ান্ত ব্যর্থ/শেষ হয়ে যাওয়া পরিচিতি থাকে; এবং remaining-এ মুলতুবি, নির্ধারিত অথবা বর্তমানে কল করা হচ্ছে এমন পরিচিতি থাকে। পুনঃচেষ্টার অপেক্ষায় থাকা পরিচিতি remaining, এমনকি তার সাম্প্রতিকতম প্রচেষ্টায় কোনো উত্তর না এলেও। একবারের সম্পন্ন স্ন্যাপশটের আগে চলমান কলগুলো সমন্বয় করা হয়। started_at হলো কনফিগার করা ক্যাম্পেইন শুরু হওয়ার সময়, অথবা কোনো শুরু নির্ধারিত না থাকলে ক্যাম্পেইন তৈরির সময়।

issue.reported#

একটি সমস্যা প্রতিবেদন তৈরি হলে পাঠানো হয় — হয় ড্যাশবোর্ড থেকে ব্যবহারকারী দাখিল করেন (source: "user"), অথবা কল গ্রেডিং স্বয়ংক্রিয়ভাবে তৈরি করে (source: "system")। ব্লকিং নয়।

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

issue.escalated#

কর্মীদের পর্যালোচনার জন্য কোনো সমস্যার প্যাটার্ন ThunderPhone-এ পাঠানো হলে পাঠানো হয়: ThunderPhone-এ রিপোর্ট করুন-এর পরে, অথবা AI দিয়ে সমাধান করুন গ্রাহক-পক্ষের সমাধান নিশ্চিত করতে না পারলে এবং সমস্যাটি স্বয়ংক্রিয়ভাবে রুট করলে। শুধু সংস্থা-ব্যাপী এন্ডপয়েন্ট এই ইভেন্ট পায়।

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}

এটি একটি বিজ্ঞপ্তি, প্রমাণের বান্ডল নয়। সমস্যার প্যাটার্নের সঙ্গে সম্পর্কিত করতে cluster_id ব্যবহার করুন। ThunderPhone-এ রিপোর্ট করুন দেখুন।

টেস্ট কল ইভেন্ট#

test-call.completed#

একটি টেস্ট কল রান চূড়ান্ত স্ট্যাটাসে পৌঁছালে পাঠানো হয় — completed বা failed, এতে সেই রানও অন্তর্ভুক্ত যা শুরুতেই ব্যর্থ হয়েছে এবং কখনও কল তৈরি করেনি। ব্লক করে না। আপনার চ্যাট/বিজ্ঞপ্তি সিস্টেমের সঙ্গে ব্যাচ CI রান সংযুক্ত করার জন্য উপযোগী।

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

সতর্কতা ইভেন্ট#

alert.triggered#

ডেভেলপার ওয়েবহুকে পাঠান চ্যানেল সক্রিয় থাকা কোনো সতর্কতা নিয়ম তার থ্রেশহোল্ড অতিক্রম করলে পাঠানো হয়। ব্লক করে না। একটি নিয়ম একবার ট্রিগার হওয়ার পর তার কুলডাউন মেনে চলে, তাই অব্যাহত লঙ্ঘনে প্রতি কুলডাউন উইন্ডোতে একটি ইভেন্ট তৈরি হয়।

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

নিয়ম, মেট্রিক, কুলডাউন এবং ইমেল / Slack চ্যানেল তৈরি করতে সতর্কতা নির্দেশিকা দেখুন।

সম্পর্কিত#