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

يحتوي كل جسم webhook على حقل type تكون قيمته أحد أنواع الأحداث الموجودة في هذه الصفحة. عند الاشتراك في نقطة نهاية، يجب أن تحتوي مصفوفة events على أنواع الأحداث التي تريدها (أو تكون فارغة للاشتراك في كل شيء). ينقل هذين الأسلوبين من التسليم هذه الأحداث:

تسليمات نقاط النهاية هي دائمًا إشعارات غير حاجبة تتضمن إعادات المحاولة: استجب بأي رمز 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>"} عند الفشل.

`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".

في خطاف الويب القديم ذي عنوان URL الواحد، كانت مكالمات اختبار ميكروفون أداة الإنشاء تُبلّغ تاريخيًا على أنها telephony.complete — وحدها المكالمات ذات direction: "web" تستخدم نوع web.complete هناك. يعيّن نظام نقاط النهاية كلًا من مكالمات الويب والاختبار إلى web.*. قد تحتوي الحمولات التاريخية على قيم direction القديمة widget أو mic.

`web.tool`

المكافئ في قناة الويب لـ telephony.tool. تحمل data origin_domain بدلًا من from_number / to_number.

أحداث الجودة

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

الحقل	النوع	الوصف
`grade.id`	integer	معرّف التقييم
`grade.score`	integer \| null	من 0 إلى 100
`grade.call_outcome`	string	`success` أو `failure` أو `unknown` أو `no_conversation`
`grade.summary`	string	ملخص من فقرة واحدة
`grade.detected_issues`	array	سلاسل المشكلات التي عثر عليها المُقيِّم
`grade.status`	string	دائمًا `completed` — لا تصدر إلا عمليات التشغيل المكتملة
`grade.grader_model`	string	المُقيِّم الذي أنتج النتيجة (مثل `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

يمكن تقييم المكالمة أكثر من مرة — غالبًا ما يتبع التقييم الاستدلالي السريع تقييمٌ كامل بالنموذج بمجرد توفر التسجيل، كما يمكن إعادة التقييم يدويًا. تصدر كل عملية تشغيل مكتملة حدث call.graded خاصًا بها؛ تعامل مع أحدث graded_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_report.severity`	string	`critical` أو `warning` أو `info`
`issue_report.status`	string	`open` أو `resolved`
`issue_report.source`	string	`user` (مقدَّم من لوحة التحكم) أو `system` (أُنشئ بواسطة التقييم)

تؤدي إعادة تقييم مكالمة إلى إعادة إنشاء تقارير المشكلات التي أنشأها النظام، مما يعيد إصدار issue.reported للتقارير المُعاد إنشاؤها. أزل التكرار بناءً على call_id + title إذا كنت تريد إشعارًا واحدًا فقط لكل مشكلة أساسية.

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

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

الحقل	النوع	الوصف
`test_call_run.target_type`	string	`agent` أو `phone_number`
`test_call_run.target_id`	integer	معرّف الوكيل أو معرّف رقم الهاتف الذي استهدفه التشغيل، بما يتوافق مع `target_type`
`test_call_run.status`	string	`completed` أو `failed`
`test_call_run.call_id`	integer \| null	`null` عندما يفشل التشغيل قبل إجراء مكالمة
`test_call_run.error_message`	string	فارغ عند النجاح

أحداث التنبيه

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

الحقل	النوع	الوصف
`event_id` (في `data`)	UUID	معرّف إطلاق التنبيه — وهو مختلف عن `event_id` الخاص بتسليم الغلاف
`rule_id`, `rule_name`	UUID، سلسلة نصية	القاعدة التي تم تفعيلها
`metric`	سلسلة نصية	`success_rate` أو `failure_rate` أو `avg_score` أو `call_volume` أو `suite_regression`
`comparator`	سلسلة نصية	`lt` أو `lte` أو `gt` أو `gte`
`metric_value`	رقم	قيمة المقياس ضمن النافذة عند تفعيل القاعدة
`threshold`	رقم	الحدّ الذي تم تكوينه
`window_hours`	عدد صحيح	نافذة التقييم السابقة
`fired_at`	طابع زمني

راجع دليل التنبيهات لإنشاء القواعد والمقاييس وفترات التهدئة وقنوات البريد الإلكتروني / Slack.

ذو صلة

telephony.incoming / web.incoming

حمولة المكالمة الواردة الحاجبة التي يجب الاستجابة لها.

telephony.complete / web.complete

النص المفرغ والمقاييس بعد المكالمة.

نقاط نهاية خطافات الويب

اشترك بعنوان URL في مجموعة فرعية من هذه الأحداث.

أدوات الدوال

كيفية إنشاء أحداث telephony.tool / web.tool.

Webhooks

Function Tools

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

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

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

أحداث الجودة

`call.graded`

`issue.reported`

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

`test-call.completed`

أحداث التنبيه

`alert.triggered`

ذو صلة

telephony.incoming / web.incoming

telephony.complete / web.complete

نقاط نهاية خطافات الويب

أدوات الدوال

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

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​أحداث الجودة

​call.graded

​issue.reported

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

​test-call.completed

​أحداث التنبيه

​alert.triggered

​ذو صلة

telephony.incoming / web.incoming

telephony.complete / web.complete

نقاط نهاية خطافات الويب

أدوات الدوال

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

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

أحداث الجودة

`call.graded`

`issue.reported`

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

`test-call.completed`

أحداث التنبيه

`alert.triggered`

ذو صلة