Webhooks

كتالوج الأحداث

جميع أنواع أحداث خطاف الويب التي يصدرها ThunderPhone.

يحتوي كل نص طلب webhook على حقل type تكون قيمته أحد أنواع الأحداث الموجودة في هذه الصفحة. عند اشتراكك في نقطة نهاية، يجب أن تحتوي مصفوفة events على أنواع الأحداث التي تريدها (أو أن تكون فارغة للاشتراك في جميع الأحداث — باستثناء أحداث كل دور telephony.turn / web.turn، التي تُسلَّم فقط إلى نقاط النهاية التي تسميها صراحةً).

تتولى نمطان من التسليم نقل هذه الأحداث:

• تكون عمليات التسليم إلى نقاط النهاية دائمًا إشعارات غير معيقة مع إعادات المحاولة: استجب بأي رمز 2xx؛ ويحتوي الغلاف على event_id لإزالة التكرار بناءً عليه.
• تعمل عمليات التبادل المعيقة فقط على webhook القديم ذي عنوان URL الواحد: طلب إعداد telephony.incoming / web.incoming (أرقام وضع webhook ومفاتيح الودجة، مهلة قدرها 10 ثوانٍ) وإرسال الأدوات في وضع webhook. يشكّل ردك المكالمة المباشرة.

توضح حمولات الأمثلة أدناه غلاف نقطة النهاية بترتيبه على الشبكة (المفاتيح مرتبة أبجديًا: data وevent_id وtype)؛ وتحمل عمليات التسليم القديمة data نفسه من دون event_id.

أحداث المكالمات#

telephony.incoming#

يُرسل عند وصول مكالمة واردة إلى أحد أرقام هاتفك. تُعد عمليات التسليم إلى نقطة النهاية إشعارات إرسال دون انتظار تُرسل لكل مكالمة واردة، سواء كان الرقم مُعدًا لوكيل أو مُعدًا لخطاف ويب. تتلقى الأرقام التي ليس لها وكيل مُعيّن أيضًا طلب الإعداد الحاجب على خطاف الويب القديم — راجع 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#

يُرسل عند انتهاء مكالمة هاتفية واردة أو صادرة. غير حاجب. يتضمن النص المفرغ ورابط التسجيل عند توفره وملخص الفوترة. راجع 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. غير حاجب.

{
  "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" أيضًا طلب الإعداد الحاجب على خطاف الويب القديم — ولهذا الطلب الحاجب بنية مختلفة (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". بالنسبة إلى جلسات الأداة المصغّرة في وضع خطاف الويب، يكون 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 origin_domain بدلًا من from_number / to_number.

web.turn#

المكافئ في قناة الويب لـ telephony.turn، ويشمل مكالمات أداة الويب المصغّرة ومكالمات اختبار الميكروفون في أداة الإنشاء. له بنية الحمولة نفسها، مع origin_domain بدلًا من from_number / to_number. وكما في telephony.turn، يتطلب اشتراكًا صريحًا — ولا يُسلَّم مطلقًا عبر مصفوفة 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#

يُرسل عند اكتمال تشغيل تقييم بالذكاء الاصطناعي لمكالمة. غير حاجب.

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

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

أحداث اختبار المكالمات#

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.

ذو صلة#