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

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

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

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

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

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

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

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

`web.tool`

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

أحداث الصوت

إنشاء الصوت المخصص غير متزامن. تتيح لك هذه الأحداث غير الحاجبة التفاعل مع نتيجة نهائية بدلاً من الاستعلام المتكرر عن نقطة نهاية تفاصيل الاستنساخ.

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

الحقل	النوع	الوصف
`voice.id`	string	المعرّف العام للصوت المخصص
`voice.name`	string	قيمة صوت الوكيل بالصيغة `custom:<public_id>`
`voice.display_name`	string	اسم الصوت الظاهر للمؤسسة
`voice.language`	string	رمز اللغة الوحيدة للاستنساخ
`voice.gender`	string	`male` أو `female` أو سلسلة فارغة
`voice.status`	string	`ready` لـ `voice.ready`؛ و`failed` لـ `voice.failed`
`voice.failure_reason`	string	فارغ عند النجاح؛ تفاصيل فشل المعالجة عند الفشل
`voice.created_at`, `voice.updated_at`	timestamp	طوابع زمنية بتنسيق ISO 8601
`reason`	string	تفاصيل الفشل؛ موجودة فقط في `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"
}

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

يمكن تقييم مكالمة أكثر من مرة — غالبًا ما يتبع التقييم الاستدلالي السريع تقييمٌ بالنموذج الكامل بمجرد توفر التسجيل، كما يمكن إجراء إعادة تقييم يدوية. تُرسل كل عملية تشغيل مكتملة حدث 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`	سلسلة نصية	`critical` أو `warning` أو `info`
`issue_report.status`	سلسلة نصية	`open` أو `resolved`
`issue_report.source`	سلسلة نصية	`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`	سلسلة نصية	`agent` أو `phone_number`
`test_call_run.target_id`	عدد صحيح	معرّف الوكيل أو معرّف رقم الهاتف الذي استهدفته عملية التشغيل، بما يتوافق مع `target_type`
`test_call_run.status`	سلسلة نصية	`completed` أو `failed`
`test_call_run.call_id`	عدد صحيح \| null	تكون `null` عندما تفشل عملية التشغيل قبل إجراء مكالمة
`test_call_run.error_message`	سلسلة نصية	فارغ عند النجاح

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

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

أحداث الصوت

`voice.ready`

`voice.failed`

أحداث الجودة

`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

​أحداث الصوت

​voice.ready

​voice.failed

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

​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`

أحداث الصوت

`voice.ready`

`voice.failed`

أحداث الجودة

`call.graded`

`issue.reported`

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

`test-call.completed`

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

`alert.triggered`

ذو صلة