ایونٹس کیٹلاگ

وہ تمام ویب ہک ایونٹ اقسام جو ThunderPhone جاری کرتا ہے۔

ہر webhook باڈی میں ایک type فیلڈ ہوتی ہے جس کی قدر اس صفحے پر موجود ایونٹ اقسام میں سے ایک ہوتی ہے۔ جب آپ کسی endpoint کو سبسکرائب کرتے ہیں، تو events ارے میں وہ ایونٹ اقسام شامل ہونی چاہییں جو آپ چاہتے ہیں (یا ہر چیز کو سبسکرائب کرنے کے لیے اسے خالی رکھیں — سوائے فی ٹرن ایونٹس telephony.turn / web.turn کے، جو صرف ان endpoints کو بھیجے جاتے ہیں جن میں ان کے نام واضح طور پر درج ہوں)۔

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

• Endpoint ترسیلات ہمیشہ دوبارہ کوششوں کے ساتھ غیر مسدود اطلاعات ہوتی ہیں: کسی بھی 2xx کے ساتھ جواب دیں؛ لفافے میں ڈی ڈپلی کیشن کے لیے event_id شامل ہوتا ہے۔
• مسدود تبادلے صرف legacy single-URL webhook پر ہوتے ہیں: telephony.incoming / web.incoming کنفیگریشن درخواست (webhook-mode نمبرز اور widget keys، 10 s ٹائم آؤٹ) اور webhook-mode tool dispatch۔ آپ کا جواب جاری کال کی ساخت متعین کرتا ہے۔

نیچے دی گئی مثال payloads endpoint لفافے کو اس کے wire ترتیب میں دکھاتی ہیں (کیز حروفِ تہجی کے مطابق ترتیب دی گئی ہیں: 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#

ٹیلی فونی کال کے جاری ہونے کے دوران، ہر گفتاری ٹرن کے وقوع پذیر ہوتے ہی ایک بار بھیجا جاتا ہے — ایجنٹ کے بولے گئے جوابات اور کالر کے ٹرانسکرائب شدہ ٹرنز۔ یہ آپ کو GET /v1/calls/{call_id}/transcript کو پول کرنے کے بجائے سادہ webhooks کے ذریعے براہ راست گفتگو کی پیروی کرنے دیتا ہے۔ غیر مسدود۔

{
  "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") کا احاطہ کرتا ہے۔ غیر مسدود۔ پے لوڈ کی ساخت telephony.complete جیسی ہی ہے، جس میں origin_domain اضافی ہوتا ہے، اور from_number کو "web" پر سیٹ کیا جاتا ہے۔

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

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 چینلز بنانے کے لیے الرٹس گائیڈ دیکھیں۔

متعلقہ#