--- title: "كتالوج الأحداث" description: "جميع أنواع أحداث خطافات الويب التي يصدرها ThunderPhone." --- يحتوي كل جسم لخطاف ويب على حقل `type` تكون قيمته أحد أنواع الأحداث في هذه الصفحة. عند الاشتراك في [نقطة نهاية](/ar/webhooks/endpoints)، يجب أن تحتوي مصفوفة `events` على أنواع الأحداث التي تريدها (أو أن تكون فارغة للاشتراك في كل شيء — باستثناء أحداث كل دور [`telephony.turn`](#telephony-turn) / [`web.turn`](#web-turn)، التي لا تُسلَّم إلا إلى نقاط النهاية التي تسميها صراحةً). يحمل هذان الأسلوبان للتسليم هذه الأحداث: * عمليات تسليم **نقطة النهاية** هي دائمًا إشعارات **غير حاجبة** مع [إعادات المحاولة](/ar/webhooks/overview): استجب بأي رمز 2xx؛ ويحتوي الغلاف على `event_id` لإزالة التكرار بناءً عليه. * تعمل التبادلات **الحاجبة** فقط على [خطاف الويب القديم أحادي الرابط](/ar/webhooks/overview): طلب إعداد [`telephony.incoming` / `web.incoming`](/ar/webhooks/call-incoming) (الأرقام في وضع خطاف الويب: 13 ثانية، بما في ذلك إعادة محاولة واحدة؛ مفاتيح الأداة في وضع خطاف الويب: 10 ثوانٍ) و[إرسال الأدوات](/ar/tools/overview) في وضع خطاف الويب. يشكّل ردك المكالمة المباشرة. تُظهر حمولات الأمثلة أدناه غلاف نقطة النهاية بترتيبه عند الإرسال (المفاتيح مرتبة أبجديًا: `data` و`event_id` و`type`)؛ وتحمل عمليات التسليم القديمة بيانات `data` نفسها من دون `event_id`. ## أحداث المكالمات ### `telephony.incoming` يُرسل عند وصول مكالمة واردة إلى أحد [أرقام هاتفك](/api-reference/phone-numbers). عمليات التسليم إلى نقاط النهاية هي إشعارات إرسال دون انتظار تُرسل لكل مكالمة واردة، سواء كان الرقم مُعدًّا لوكيل أو مُعدًّا لخطاف ويب. وتتلقى الأرقام التي لا يُعيَّن لها وكيل أيضًا طلب الإعداد **الحاجب** على خطاف الويب القديم — راجع [`telephony.incoming` / `web.incoming`](/ar/webhooks/call-incoming) للاطلاع على مخطط الطلب / الاستجابة الكامل. ```json { "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }, "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11", "type": "telephony.incoming" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | ### `telephony.complete` يُرسل عند انتهاء مكالمة هاتفية واردة أو صادرة. غير حاجب. يتضمن النص المفرغ، ورابط التسجيل عند توفره، وملخص الفوترة. راجع [`telephony.complete` / `web.complete`](/ar/webhooks/call-complete) للاطلاع على مخطط الحمولة. | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | ### `telephony.tool` يُرسل بعد أن تستدعي مكالمة هاتفية [أداة دالة](/ar/tools/overview). وهو إشعار تدقيق غير حاجب — تكون الأداة قد نُفذت بالفعل عند تسليم هذا الحدث؛ ويشمل أدوات الدوال الخاصة بك وأداة `send_sms` المضمنة (وليس الأدوات المضمنة الأخرى، أو أدوات قاعدة المعرفة، أو اتصالات التطبيقات، أو أدوات MCP). بالنسبة إلى `send_sms`، يكون كل من `arguments.to` و`arguments.body` بالقيمة `[REDACTED]`. كما يحجب النص المفرغ للإكمال هذه القيم؛ استرجع المحتوى والمستلم من مورد SMS على مستوى المؤسسة باستخدام `message_id` في الاستجابة. ```json { "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": , "response": }` عند النجاح، أو `{"status": , "error": ""}` عند الفشل. | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | ### `telephony.turn` يُرسل أثناء كون المكالمة الهاتفية **قيد التقدم**، مرة واحدة لكل دور يتضمن كلامًا عند حدوثه — إكمالات الوكيل المنطوقة وأدوار المتصل المنسوخة نصيًا. يتيح لك متابعة المحادثة المباشرة عبر خطافات ويب عادية بدلًا من الاستعلام المتكرر عن [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript). غير حاجب. **يلزم اشتراك صريح.** بخلاف كل أنواع الأحداث الأخرى، لا تُسلَّم أحداث الدور مطلقًا عبر مصفوفة `events` فارغة (الاشتراك في الكل). لا تتلقاها نقطة النهاية إلا عندما تتضمن قائمة `events` الخاصة بها `telephony.turn` / `web.turn` صراحةً. ```json { "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" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `position` | integer | فهرس الدور في سجل المكالمة — معرّف ثابت للترتيب | | `role` | string | `assistant` (كلام الوكيل) أو `user` (كلام المتصل) | | `text` | string | نص الدور المفرغ كما هو معروف وقت الإرسال | | `entry_type` | string | نوع إدخال السجل الأساسي: `completion` (الوكيل)، أو `user_turn` / `span` (المتصل) | | `start_ms`, `end_ms` | integer | إزاحات الصوت بالمللي ثانية منذ بدء المكالمة؛ تكون موجودة فقط عندما يكون توقيت التشغيل معروفًا بالفعل وقت الإرسال | يكون التسليم مرة واحدة على الأقل وقد تصل الأدوار **بترتيب غير صحيح**: أزل التكرار استنادًا إلى `event_id` الخاص بالغلاف ورتّب حسب `position`. قد يستمر تحسين النصوص المفرغة للمتصل بعد الإرسال؛ ويُعد النص المفرغ لـ [`telephony.complete`](/ar/webhooks/call-complete) بعد المكالمة المرجع المعتمد. لا تُرسل إلا الأدوار المنطوقة — ولا تظهر استدعاءات الأدوات، أو الهمسات، أو الإدخالات الداخلية الأخرى في هذا التدفق مطلقًا. ### `web.incoming` المكافئ في قناة الويب لـ `telephony.incoming`، ويُرسل عند بدء جلسة [أداة ويب](/ar/widget/overview) أو مكالمة اختبار ميكروفون من أداة الإنشاء. عمليات التسليم إلى نقاط النهاية هي إرسال دون انتظار لكل جلسة ويب. تتلقى المفاتيح القابلة للنشر في `mode="webhook"` أيضًا طلب الإعداد **الحاجب** على خطاف الويب القديم — ويكون لطلب الحجب هذا بنية مختلفة (`origin_domain`، `publishable_key_prefix`؛ دون أرقام هاتفية). راجع [`telephony.incoming` / `web.incoming`](/ar/webhooks/call-incoming). ```json { "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` فارغين. | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | ### `web.complete` المكافئ في قناة الويب لـ `telephony.complete`، ويغطي مكالمات أداة الويب (`direction: "web"`) ومكالمات اختبار ميكروفون أداة الإنشاء (`direction: "test"`). غير حاجب. له بنية الحمولة نفسها التي لدى [`telephony.complete`](/ar/webhooks/call-complete)، بالإضافة إلى `origin_domain`، مع ضبط `from_number` على `"web"`. | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | على خطاف الويب القديم ذي عنوان URL الواحد، تُبلّغ مكالمات اختبار ميكروفون أداة الإنشاء تاريخيًا بصفتها `telephony.complete` — ولا تستخدم هناك نوع `web.complete` إلا المكالمات ذات `direction: "web"`. يعيّن نظام نقاط النهاية كلاً من مكالمات الويب والاختبار إلى `web.*`. قد تتضمن الحمولات التاريخية قيم `direction` القديمة `widget` أو `mic`. ### `web.tool` المكافئ في قناة الويب لـ `telephony.tool`. تحمل `data` القيمة `origin_domain` بدلًا من `from_number` / `to_number`. | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | ### `web.turn` المكافئ في قناة الويب لـ [`telephony.turn`](#telephony-turn)، ويغطي مكالمات أداة الويب ومكالمات اختبار ميكروفون أداة الإنشاء. له بنية الحمولة نفسها، مع `origin_domain` بدلًا من `from_number` / `to_number`. وكما في `telephony.turn`، يتطلب **اشتراكًا صريحًا** — ولا يُسلَّم مطلقًا عبر مصفوفة `events` فارغة. | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | ### `call.transfer_completed` يُرسل مرة واحدة لكل مكالمة متضمناً النتيجة النهائية لـ [تحويل المكالمة](/ar/guides/call-transfers): تحويل بارد، أو الجسر البشري الذي يتركه التحويل الدافئ بعد مغادرة الوكيل. لا يحظر التنفيذ، ويُسلَّم إلى نقاط النهاية فقط (وليس إلى خطاف الويب القديم ذي الرابط الواحد). يصل بعد `telephony.complete` للمكالمة: عند استلام الناقل للمكالمة أو فشل التحويل، أو، عندما يقوم ThunderPhone بربط المكالمة، عند انتهاء الجسر. ```json { "data": { "agent_id": 12, "agent_name": "Front desk", "bridge_kind": "cold_fallback", "bridge_seconds": 255, "bridge_total_cents": 5, "call_id": 987654321, "destination": "+15555550102", "sip_status": 403, "transfer_outcome": "bridged" }, "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f", "type": "call.transfer_completed" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `call_id` | عدد صحيح | المكالمة التي تم تحويلها | | `agent_id` | عدد صحيح \| فارغ | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | سلسلة نصية \| فارغ | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `transfer_outcome` | سلسلة نصية | `refer_accepted`: استلم الناقل المكالمة. `bridged`: أبقى ThunderPhone المتصل والوجهة متصلين بنفسه، إما لأن الناقل رفض تحويلاً بارداً أو لأن وكيل التحويل الدافئ غادر. `bridge_unanswered`: رفض الناقل تحويلاً بارداً ولم تجب الوجهة على مكالمة ThunderPhone الخاصة. `failed`: لم يكتمل التحويل وانتهت المكالمة | | `destination` | سلسلة نصية \| فارغ | الرقم الذي حُوِّلت المكالمة إليه | | `sip_status` | عدد صحيح \| فارغ | حالة SIP لدى الناقل عند رفضه للتحويل البارد: `403` (مثلاً، قناة Twilio من دون تحويل مكالمات)، أو `405` أو `501`. تكون `null` عندما لا يرفضه الناقل | | `bridge_kind` | سلسلة نصية \| فارغ | لـ `bridged` فقط: `cold_fallback` (تحويل بارد مرفوض وصله ThunderPhone) أو `warm` (الشخصان في تحويل دافئ بعد مغادرة الوكيل) | | `bridge_seconds` | عدد صحيح \| فارغ | لـ `bridged` فقط: مدة الجسر التي فوّتَرها ThunderPhone، بالثواني | | `bridge_total_cents` | عدد صحيح \| فارغ | لـ `bridged` فقط: تكلفة الجسر بسنتات الدولار الأمريكي بعد أي رصيد مجاني للمكالمات، وتُفوَّتر منفصلة عن `billing_total_cents` الخاص بالمكالمة | تتوفر القيم نفسها في [كائن المكالمة](/api-reference/calls#call-object) بأسماء `transfer_outcome` و`transfer_destination` و`transfer_sip_status` و`transfer_bridge_kind` و`transfer_bridge_seconds` و `transfer_bridge_total_cents`. تكون قيمة `event_id` نفسها في كل تسليم للمكالمة، لذا لا ينتج عن التقرير المتكرر حدث ثانٍ. --- ## أحداث الرسائل النصية القصيرة تصف أحداث الرسائل النصية القصيرة الرسائل المُرسلة عبر حساب Twilio أو Telnyx المتصل بالمؤسسة. يُحذف نص الرسالة وتُحجب قيمة `to`. استرجع الرسالة على نطاق المؤسسة من [`GET /v1/sms/{message_id}`](/api-reference/sms#retrieve-a-message) عند الحاجة إلى محتواها أو مستلمها. ### `sms.sent` يُرسل عند قبول شركة الاتصالات لدى العميل طلب إرسال رسالة نصية قصيرة صادرة. لا يُعد هذا إيصال تسليم إلى جهاز المستلم. ```json { "data": { "accepted_at": "2026-09-19T15:42:10.113Z", "agent_id": 12, "call_id": 987654321, "created_at": "2026-09-19T15:42:09.901Z", "direction": "outbound", "error_code": null, "error_message": null, "from_number": "+15551234567", "id": "313a3117-827b-46e9-a01a-ac1493838724", "provider": "twilio", "provider_id": "SM0123456789abcdef0123456789abcdef", "segment_count": 1, "source": "agent_tool", "status": "accepted", "to": "[REDACTED]" }, "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37", "type": "sms.sent" } ``` ### `sms.failed` يُرسل بعد رفض دائم من شركة الاتصالات، أو بعد استنفاد محاولات إعادة الإرسال المؤقتة، أو عندما تكون النتيجة غير معروفة بشكل نهائي. `error_code` هو رمز ثابت من ThunderPhone، ويحدد `error_message` الإجراء المطلوب من العميل عند توفره. تعني `status: "unknown"` أن شركة الاتصالات قد تكون قبلت الرسالة النصية القصيرة؛ طابقها في سجل شركة الاتصالات لأن ThunderPhone لن يعيد إرسالها تلقائيًا. ### `sms.received` محجوز لدعم الرسائل النصية القصيرة الواردة. لا تُصدر أي أحداث `sms.received` في الإصدار الحالي. سيُطرح إعداد webhook الوارد لشركة الاتصالات والتحقق من التوقيع بشكل منفصل. --- ## الأحداث الصوتية إنشاء الصوت المخصص عملية غير متزامنة. تتيح لك هذه الأحداث غير الحاجبة الاستجابة لنتيجة نهائية بدلًا من الاستعلام المتكرر عن [نقطة نهاية تفاصيل النسخة المستنسخة](/api-reference/custom-voices#list-and-retrieve-clones). لا تُسلَّم `voice.ready` و`voice.failed` إلا إلى نقطة نهاية على مستوى المؤسسة بأكملها مع `events: []`. لا يمكن اختيارهما كمرشحات أحداث صريحة. ### `voice.ready` يُرسل عند انتهاء معالجة صوت مخصص وإتاحة تعيينه إلى وكيل. ```json { "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` يُرسل عند وصول معالجة الصوت المخصص إلى فشل دائم. ```json { "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` | سلسلة نصية | المعرّف العام للصوت المخصص | | `voice.name` | سلسلة نصية | قيمة صوت الوكيل بالصيغة `custom:` | | `voice.display_name` | سلسلة نصية | اسم الصوت الظاهر للمؤسسة | | `voice.language` | سلسلة نصية | رمز اللغة الوحيدة للنسخة المستنسخة | | `voice.gender` | سلسلة نصية | `male` أو `female` أو سلسلة نصية فارغة | | `voice.status` | سلسلة نصية | `ready` لـ `voice.ready`؛ و`failed` لـ `voice.failed` | | `voice.failure_reason` | سلسلة نصية | فارغ عند النجاح؛ تفاصيل فشل المعالجة عند الفشل | | `voice.created_at`, `voice.updated_at` | طابع زمني | طوابع زمنية وفق ISO 8601 | | `reason` | سلسلة نصية | تفاصيل الفشل؛ موجود فقط في `voice.failed` | --- ## أحداث الجودة ### `call.graded` يُرسل كلما اكتمل [تشغيل تقييم بالذكاء الاصطناعي](/api-reference/calls#ai-call-grading) لمكالمة. غير حاجب. ```json { "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…" }, "report": null }, "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "type": "call.graded" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | عدد صحيح \| فارغ | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | نص \| فارغ | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `grade.id` | عدد صحيح | معرّف التقييم | | `grade.score` | عدد صحيح \| فارغ | 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` | طابع زمني | | | `report` | كائن \| فارغ | [تقرير المكالمة](/api-reference/calls#call-report) الموجّه للعميل: تسمية النتيجة، علامة الحاجة إلى الانتباه وسببها، المتصل، ملخص من سطر واحد، وتجربة المتصل. في تقييم استدلالي مبكر، تكون قيمته `null` أو تقرير `pending` تكون حقوله عناصر نائبة؛ ويحمل حدث التقييم الكامل التقرير المكتمل | يمكن تقييم المكالمة أكثر من مرة — غالبًا ما يتبع التقييم الاستدلالي السريع تقييم كامل من النموذج عند توفر التسجيل، كما يمكن إجراء إعادة تقييم يدوية. ترسل كل عملية تشغيل مكتملة حدث `call.graded` خاصًا بها؛ تعامل مع أحدث `graded_at` بوصفه المرجع المعتمد. ### `call.data_extracted` يُرسل كلما اكتمل استخراج البيانات المنظمة بنجاح، بما في ذلك إعادة محاولة متأخرة بعد `telephony.complete` / `web.complete` أو إعادة تشغيل يدوية عبر [`POST /v1/calls/{call_id}/extract`](/api-reference/calls#run-data-extraction). غير حاجب. في وضع الاستخراج الحاجب، لا ينتظر حدث الاكتمال عادةً أكثر من ميزانية الاستخراج البالغة 75 ثانية. إذا فُقدت عملية عامل الاستخراج، فإن تصريف الإنهاء في بيئة الإنتاج، الذي يعمل كل خمس دقائق، يطلق حدث اكتمال تجاوز فيه `blocking_deadline_at` موعده قبل بدء محاولة استخراج أخرى. ويُرسل النجاح اللاحق بشكل منفصل عبر هذا الحدث. القيم المستخرجة هي تفسير النموذج للمحادثة. تتضمن كل قيمة غير فارغة الاقتباس ودور المتحدث وفهرس الدور الذي استندت إليه، بالإضافة إلى علامة تحقق على مستوى التشغيل. تحقق من النتيجة قبل اتخاذ قرارات تتعلق بالمال أو الهوية أو الوصول. ```json { "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": "", "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23." }, "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef", "type": "call.data_extracted" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `summary` | string \| null | [ملخص المكالمة](/ar/webhooks/call-complete) المكتمل عندما يكون لدى الوكيل خيار **إنشاء ملخص للمكالمة** مفعّلًا، لذلك يرسل حدث الاستخراج المتأخر أيضًا ملخصًا لم يصل ضمن نافذة الاكتمال؛ وإلا تكون القيمة `null`. لا ترسل الوكلاء الذين لديهم ملخص دون حقول استخراج هذا الحدث مطلقًا: اقرأ الملخص المتأخر من `GET /v1/calls/{call_id}` | | `extracted_data.status` | string | دائمًا `completed` لهذا الحدث | | `extracted_data.fields` | object | القيم مفهرسة بمفاتيح حقول الاستخراج المهيأة؛ القيم غير المتاحة هي `null` | | `extracted_data.evidence` | object | الأدلة مفهرسة بحقل الاستخراج. تحتوي القيمة غير الفارغة على الاقتباس الدقيق المتحقق منه بنيويًا، بحد أقصى 1,000 حرف، و`speaker_role`، إما `caller` أو `agent`، و`turn_index`؛ تُرفض الاقتباسات الأطول التي يعيدها النموذج بدلًا من اقتطاعها، وتكون الأدلة `null` كلما كان حقلها `null` | | `extracted_data.verification` | string | تكون `verified` فقط عندما تعيد مرحلة الأدلة المستقلة حكمًا صالحًا واحدًا بالضبط لكل حقل مرشح. تعني `unavailable` أن المرحلة فشلت أو انتهت مهلتها أو لم تتوفر لها ميزانية كافية أو أعادت مخرجات مشوهة أو جزئية. تحافظ المرحلة غير المتاحة بالكامل على القيم المؤسسة بنيويًا لمراجعة العميل. بالنسبة إلى المخرجات الجزئية، تُطبق الأحكام الصالحة ويُعيّن كل مرشح لا يملك حكمًا صالحًا واحدًا بالضبط إلى قيمة فارغة | | `extracted_data.field_reasons` | object | أسباب مفهرسة بالحقول التي عُيّنت إلى قيمة فارغة بواسطة التأسيس البنيوي أو المدقق المستقل | | `extracted_data.schema_version` | string | تجزئة مخطط الحقول الدقيق المستخدم لهذا الاستخراج | | `extracted_at` | timestamp | وقت الاكتمال بتنسيق ISO 8601 | | `model` | string | النموذج المستخدم للاستخراج | ### `campaign.completed` يُرسل مرة واحدة عندما تنتقل حملة من `running` إلى `completed`، سواء انتهى جدولها أو وصلت جميع جهات الاتصال إلى حالات نهائية. لا تؤدي محاولات إعادة التشغيل إلى إرسال حدث آخر. يُسلَّم حدث دورة الحياة هذا على مستوى المؤسسة فقط إلى نقاط النهاية ذات نطاق المؤسسة، وليس إلى نقاط النهاية ذات نطاق الوكيل. غير حاجب. ```json { "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` يُرسل عند إنشاء [تقرير مشكلة](/api-reference/issue-reports) — إما يقدمه مستخدم من لوحة التحكم (`source: "user"`) أو يُنشأ تلقائيًا عبر تقييم المكالمة (`source: "system"`). غير حاجب. ```json { "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" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `issue_report.severity` | string | `critical` أو `warning` أو `info` | | `issue_report.status` | string | `open` أو `resolved` | | `issue_report.source` | string | `user`، قُدّم من لوحة التحكم، أو `system`، أُنشئ بواسطة التقييم | تؤدي إعادة تقييم مكالمة إلى إعادة بناء تقارير المشكلات التي أنشأها النظام، مما يعيد إرسال `issue.reported` للتقارير المعاد إنشاؤها. أزل التكرار بناءً على `call_id` + `title` إذا كنت تريد إشعارًا واحدًا فقط لكل مشكلة أساسية. ### `issue.escalated` يُرسل عند إرسال نمط مشكلة إلى ThunderPhone لمراجعة الموظفين: بعد **الإبلاغ إلى ThunderPhone**، أو عندما يتعذر على إصلاح المشكلة بالذكاء الاصطناعي تأكيد إصلاح من جانب العميل ويوجّه المشكلة تلقائيًا. لا تتلقى هذا الحدث إلا نقاط النهاية على مستوى المؤسسة. ```json { "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" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `automatic` | boolean | `true` للتصعيد التلقائي؛ و`false` للتصعيد اليدوي | | `cluster_id` | UUID | نمط المشكلة المُصعّد | | `escalation_id` | UUID | سجل التصعيد | | `status` | string | `open` عند إرسال الحدث | هذا إشعار وليس حزمة أدلة. استخدم `cluster_id` لربطه بنمط المشكلة. راجع [الإبلاغ إلى ThunderPhone](/ar/guides/issues). --- ## أحداث المكالمات التجريبية ### `test-call.completed` يُرسل عند وصول [تشغيل مكالمة تجريبية](/api-reference/test-calls#test-call-run-object) إلى حالة نهائية — `completed` أو `failed`، بما في ذلك عمليات التشغيل التي فشلت عند البدء ولم تُنتج مكالمة مطلقًا. غير حاجب. مفيد لربط عمليات تشغيل CI الدفعية بأنظمة الدردشة/الإشعارات لديك. ```json { "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" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `agent_id` | integer \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `agent_name` | string \| null | الوكيل الذي عالج المكالمة، عند تعيين وكيل | | `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` يُرسل عندما تتجاوز [قاعدة تنبيه](/ar/guides/alerts) حدّها مع تفعيل قناة **التسليم إلى خطافات الويب للمطورين**. غير حاجب. تُفعَّل القاعدة مرة واحدة ثم تلتزم بفترة التهدئة الخاصة بها، لذا ينتج عن التجاوز المستمر حدث واحد لكل نافذة تهدئة. ```json { "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, string | القاعدة التي تم تفعيلها | | `metric` | string | `success_rate` أو `failure_rate` أو `avg_score` أو `call_volume` أو `suite_regression` | | `comparator` | string | `lt` أو `lte` أو `gt` أو `gte` | | `metric_value` | number | قيمة المقياس ضمن النافذة عند تفعيل القاعدة | | `threshold` | number | الحد المُعدّ | | `window_hours` | integer | نافذة التقييم السابقة | | `fired_at` | timestamp | | راجع [دليل التنبيهات](/ar/guides/alerts) لإنشاء القواعد والمقاييس وفترات التهدئة وقنوات البريد الإلكتروني / Slack. --- ## أحداث الترحيل ### `migration.call.complete` يُرسل عند انتهاء مكالمة أُجريت عبر [`POST /v1/migrations/{id}/calls`](/api-reference/migration-calls)، بغض النظر عن المنصة التي أجرتها. غير حاجب. يصل خلال مدة تصل إلى نحو 5 دقائق بعد انتهاء المكالمة. يحتوي `data` على كل حقل من [`telephony.complete`](/ar/webhooks/call-complete) بالإضافة إلى كتلة `migration`. ترسل المكالمة التي يجريها ThunderPhone أيضًا `telephony.complete` كالمعتاد، باستخدام `call_id` نفسه. تُرسل مكالمة على المنصة الأخرى لم تنتهِ بعد ساعتين، أو اكتمل ترحيلها أو فقدت مفتاحها أولًا، مع `status: "unknown"` ودون نص مفرغ. ```json { "data": { "agent_id": 42, "agent_name": "Front desk", "billable_minutes": null, "billing_total_cents": null, "call_id": null, "direction": "outbound", "duration_seconds": 94, "end_reason": "user_hangup", "end_time": "2026-10-06T17:01:34+00:00", "extracted_data": null, "from_number": "+15551234567", "migration": { "arm": "vendor", "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30", "metadata": { "lead_id": "8812" }, "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34", "vendor": "retell", "vendor_call_id": "call_6a1f0e", "vendor_cost_usd": "0.1240" }, "product": "", "recording_mode": "vendor", "recording_url": "https://…", "start_time": "2026-10-06T17:00:00+00:00", "status": "completed", "summary": "The callee booked a table for two on Thursday.", "thunderphone_retained_call_content": true, "to_number": "+14155552671", "transcripts": [ { "content": "Hi Ada, this is Rosa's calling about your booking.", "role": "agent" }, { "content": "Yes, Thursday works.", "role": "user" } ], "transfer_number": null, "unresolved_variables": [], "variables": { "first_name": "Ada" }, "voice": "" }, "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a", "type": "migration.call.complete" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `migration.id` | UUID | الترحيل | | `migration.routing_id` | UUID | المكالمة المُوجَّهة، كما أُعيدت عند إجرائها | | `migration.arm` | string | `ours` (أجراها ThunderPhone) أو `vendor` (أجرتها المنصة الأخرى) | | `migration.vendor` | string | `retell` أو `vapi` أو `elevenlabs` أو `bland` | | `migration.vendor_call_id` | string \| null | معرّف المكالمة في المنصة الأخرى؛ `null` لـ `ours` | | `migration.metadata` | object | بيانات `metadata` التي أرسلتها عند إجراء المكالمة | | `migration.vendor_cost_usd` | string \| null | التكلفة التي أبلغت بها المنصة الأخرى للمكالمة، عند توفرها | | `call_id` | integer \| null | معرّف مكالمة ThunderPhone؛ `null` لـ `vendor` | | `status` | string | بالنسبة إلى `vendor`: `completed` عندما يتحدث المتصل به، و`failed` عندما لا يتحدث، و`unknown` كما ورد أعلاه. بالنسبة إلى `ours`: كما في `telephony.complete` | بالنسبة إلى مكالمة `vendor`، لا تتوفر لدى ThunderPhone بيانات فوترة أو استخراج: تكون `billable_minutes` و`billing_total_cents` و`extracted_data` بقيمة `null`، ويكون `product` و`voice` فارغين، ويكون `recording_mode` هو `vendor`، ويكون `recording_url` رابط المنصة الأخرى عند تقديمها رابطًا. ### `migration.rollback` يُرسل عندما يعيد التحويل التدريجي لعملية ترحيل كل مكالمة تلقائيًا إلى المنصة الأخرى: فشلت 3 مكالمات في الاتصال بـ ThunderPhone خلال 15 دقيقة، أو انتهت مكالمتان مُرسلتان إلى ThunderPhone قبل أن يجيب الوكيل، أو انخفض معدل نتائج المهام لدى ThunderPhone عن معدل المنصة الأخرى بأكثر من الفجوة المُعَدّة. غير حاجب، ويُرسل مرة واحدة لكل تراجع. بعده، تصبح حصة ThunderPhone 0% وتُعلّق عملية الترحيل إلى أن يستأنفها شخص ما من علامة تبويب الترحيل الخاصة بالوكيل. لا تحتوي الحمولة على أرقام هواتف أو نصوص مفرغة أو معرّفات مكالمات. ```json { "data": { "agent_id": 42, "agent_name": "Front desk", "dropped": 0, "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30", "ours": { "graded": 20, "success_rate": 0.8 }, "ours_failed": 3, "ours_percent": 0, "previous_percent": 25, "reason": "ours_failed_burst", "rolled_back_at": "2026-10-10T12:05:00+00:00", "step": 1, "theirs": { "graded": 20, "success_rate": 0.8 }, "vendor": "retell" }, "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e", "type": "migration.rollback" } ``` | الحقل | النوع | الوصف | |-------|------|-------------| | `migration_id` | UUID | عملية الترحيل | | `vendor` | string | `retell` أو `vapi` أو `elevenlabs` أو `bland` | | `reason` | string | `ours_failed_burst` ‏(3 اتصالات فاشلة خلال 15 دقيقة)، أو `dropped_calls` ‏(انتهت مكالمتان قبل أن يجيب الوكيل، خلال 30 دقيقة)، أو `rate_gap` ‏(فجوة في معدل نتائج المهام عبر ما لا يقل عن `rollback_min_calls` مكالمة مُقيَّمة لكل جانب) | | `previous_percent` | integer | حصة ThunderPhone من المكالمات قبل التراجع | | `ours_percent` | integer | دائمًا `0` | | `step` | integer \| null | خطوة الجدول التي كانت عليها العملية (تبدأ من 0) | | `ours` / `theirs` | object \| null | المكالمات المُقيَّمة في الخطوة الحالية ومعدل نجاحها؛ قد تمثل `theirs` آخر 30 يومًا عندما تحتوي الخطوة على عدد قليل جدًا من المكالمات. تكون `null` عند عدم وجود أي منها | | `ours_failed` | integer | الاتصالات الفاشلة المُحتسبة خلال آخر 15 دقيقة | | `dropped` | integer | المكالمات المُحتسبة على أنها منقطعة خلال آخر 30 دقيقة | | `rolled_back_at` | timestamp | | --- ## ذو صلة حمولة المكالمة الواردة الحاجبة التي يجب أن تستجيب لها. النص المفرغ للمكالمة ومقاييسها بعد انتهائها. اشترك بعنوان URL في مجموعة فرعية من هذه الأحداث. كيفية إنشاء أحداث `telephony.tool` / `web.tool`.