Open in
كتالوج الأحداث
جميع أنواع أحداث خطافات الويب التي يصدرها ThunderPhone.
يحتوي كل جسم لخطاف ويب على حقل type تكون قيمته أحد أنواع
الأحداث في هذه الصفحة. عند الاشتراك في
نقطة نهاية، يجب أن تحتوي مصفوفة events على
أنواع الأحداث التي تريدها (أو أن تكون فارغة للاشتراك في كل شيء —
باستثناء أحداث كل دور telephony.turn /
web.turn، التي لا تُسلَّم إلا إلى نقاط النهاية التي
تسميها صراحةً).
يحمل هذان الأسلوبان للتسليم هذه الأحداث:
- عمليات تسليم نقطة النهاية هي دائمًا إشعارات غير حاجبة مع إعادات المحاولة: استجب بأي رمز 2xx؛ ويحتوي الغلاف على
event_idلإزالة التكرار بناءً عليه. - تعمل التبادلات الحاجبة فقط على
خطاف الويب القديم أحادي الرابط: طلب إعداد
telephony.incoming/web.incoming(الأرقام في وضع خطاف الويب: 13 ثانية، بما في ذلك إعادة محاولة واحدة؛ مفاتيح الأداة في وضع خطاف الويب: 10 ثوانٍ) وإرسال الأدوات في وضع خطاف الويب. يشكّل ردك المكالمة المباشرة.
تُظهر حمولات الأمثلة أدناه غلاف نقطة النهاية بترتيبه عند الإرسال
(المفاتيح مرتبة أبجديًا: 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"
}| الحقل | النوع | الوصف |
|---|---|---|
agent_id | integer | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
agent_name | string | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
telephony.complete
يُرسل عند انتهاء مكالمة هاتفية واردة أو صادرة. غير حاجب.
يتضمن النص المفرغ، ورابط التسجيل عند توفره، وملخص الفوترة. راجع
telephony.complete / web.complete للاطلاع على
مخطط الحمولة.
| الحقل | النوع | الوصف |
|---|---|---|
agent_id | integer | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
agent_name | string | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
telephony.tool
يُرسل بعد أن تستدعي مكالمة هاتفية
أداة دالة. وهو إشعار تدقيق غير حاجب —
تكون الأداة قد نُفذت بالفعل عند تسليم هذا الحدث؛ ويشمل
أدوات الدوال الخاصة بك وأداة send_sms المضمنة (وليس الأدوات المضمنة الأخرى،
أو أدوات قاعدة المعرفة، أو اتصالات التطبيقات، أو أدوات MCP). بالنسبة إلى send_sms،
يكون كل من arguments.to وarguments.body بالقيمة [REDACTED]. كما
يحجب النص المفرغ للإكمال هذه القيم؛ استرجع المحتوى والمستلم من
مورد SMS على مستوى المؤسسة باستخدام message_id في الاستجابة.
{
"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>"} عند الفشل.
| الحقل | النوع | الوصف |
|---|---|---|
agent_id | integer | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
agent_name | string | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
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"
}| الحقل | النوع | الوصف |
|---|---|---|
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 | إزاحات الصوت بالمللي ثانية منذ بدء المكالمة؛ تكون موجودة فقط عندما يكون توقيت التشغيل معروفًا بالفعل وقت الإرسال |
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 فارغين.
| الحقل | النوع | الوصف |
|---|---|---|
agent_id | integer | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
agent_name | string | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
web.complete
المكافئ في قناة الويب لـ telephony.complete، ويغطي مكالمات
أداة الويب (direction: "web") ومكالمات اختبار ميكروفون أداة الإنشاء
(direction: "test"). غير حاجب. له بنية الحمولة نفسها التي لدى
telephony.complete، بالإضافة إلى origin_domain،
مع ضبط from_number على "web".
| الحقل | النوع | الوصف |
|---|---|---|
agent_id | integer | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
agent_name | string | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
web.tool
المكافئ في قناة الويب لـ telephony.tool. تحمل data
القيمة origin_domain بدلًا من from_number / to_number.
| الحقل | النوع | الوصف |
|---|---|---|
agent_id | integer | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
agent_name | string | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
web.turn
المكافئ في قناة الويب لـ telephony.turn،
ويغطي مكالمات أداة الويب ومكالمات اختبار ميكروفون أداة الإنشاء. له بنية الحمولة
نفسها، مع origin_domain بدلًا من from_number / to_number.
وكما في telephony.turn، يتطلب اشتراكًا صريحًا — ولا
يُسلَّم مطلقًا عبر مصفوفة events فارغة.
| الحقل | النوع | الوصف |
|---|---|---|
agent_id | integer | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
agent_name | string | null | الوكيل الذي عالج المكالمة، عند تعيين وكيل |
call.transfer_completed
يُرسل مرة واحدة لكل مكالمة متضمناً النتيجة النهائية لـ
تحويل المكالمة: تحويل بارد، أو الجسر البشري
الذي يتركه التحويل الدافئ بعد مغادرة الوكيل.
لا يحظر التنفيذ، ويُسلَّم إلى نقاط النهاية فقط (وليس إلى
خطاف الويب القديم ذي الرابط الواحد). يصل بعد telephony.complete
للمكالمة: عند استلام الناقل للمكالمة أو فشل التحويل، أو، عندما
يقوم ThunderPhone بربط المكالمة، عند انتهاء الجسر.
{
"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 الخاص بالمكالمة |
تتوفر القيم نفسها في كائن المكالمة
بأسماء 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} عند الحاجة إلى
محتواها أو مستلمها.
sms.sent
يُرسل عند قبول شركة الاتصالات لدى العميل طلب إرسال رسالة نصية قصيرة صادرة. لا يُعد هذا إيصال تسليم إلى جهاز المستلم.
{
"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 الوارد لشركة الاتصالات والتحقق من التوقيع
بشكل منفصل.
الأحداث الصوتية
إنشاء الصوت المخصص عملية غير متزامنة. تتيح لك هذه الأحداث غير الحاجبة الاستجابة لنتيجة نهائية بدلًا من الاستعلام المتكرر عن نقطة نهاية تفاصيل النسخة المستنسخة.
لا تُسلَّم 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"
}| الحقل | النوع | الوصف |
|---|---|---|
voice.id | سلسلة نصية | المعرّف العام للصوت المخصص |
voice.name | سلسلة نصية | قيمة صوت الوكيل بالصيغة custom:<public_id> |
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
يُرسل كلما اكتمل تشغيل تقييم بالذكاء الاصطناعي لمكالمة. غير حاجب.
{
"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 | كائن | فارغ | تقرير المكالمة الموجّه للعميل: تسمية النتيجة، علامة الحاجة إلى الانتباه وسببها، المتصل، ملخص من سطر واحد، وتجربة المتصل. في تقييم استدلالي مبكر، تكون قيمته null أو تقرير pending تكون حقوله عناصر نائبة؛ ويحمل حدث التقييم الكامل التقرير المكتمل |
call.data_extracted
يُرسل كلما اكتمل استخراج البيانات المنظمة بنجاح، بما في ذلك إعادة محاولة
متأخرة بعد telephony.complete / web.complete أو إعادة تشغيل يدوية عبر
POST /v1/calls/{call_id}/extract.
غير حاجب.
في وضع الاستخراج الحاجب، لا ينتظر حدث الاكتمال عادةً أكثر من ميزانية الاستخراج
البالغة 75 ثانية. إذا فُقدت عملية عامل الاستخراج، فإن تصريف الإنهاء في بيئة
الإنتاج، الذي يعمل كل خمس دقائق، يطلق حدث اكتمال تجاوز فيه
blocking_deadline_at موعده قبل بدء محاولة استخراج أخرى. ويُرسل النجاح
اللاحق بشكل منفصل عبر هذا الحدث.
{
"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": "<model id>",
"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 | ملخص المكالمة المكتمل عندما يكون لدى الوكيل خيار إنشاء ملخص للمكالمة مفعّلًا، لذلك يرسل حدث الاستخراج المتأخر أيضًا ملخصًا لم يصل ضمن نافذة الاكتمال؛ وإلا تكون القيمة 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، سواء انتهى
جدولها أو وصلت جميع جهات الاتصال إلى حالات نهائية. لا تؤدي محاولات إعادة
التشغيل إلى إرسال حدث آخر. يُسلَّم حدث دورة الحياة هذا على مستوى المؤسسة فقط
إلى نقاط النهاية ذات نطاق المؤسسة، وليس إلى نقاط النهاية ذات نطاق الوكيل.
غير حاجب.
{
"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"
}| الحقل | النوع | الوصف |
|---|---|---|
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.escalated
يُرسل عند إرسال نمط مشكلة إلى ThunderPhone لمراجعة الموظفين: بعد الإبلاغ إلى ThunderPhone، أو عندما يتعذر على إصلاح المشكلة بالذكاء الاصطناعي تأكيد إصلاح من جانب العميل ويوجّه المشكلة تلقائيًا. لا تتلقى هذا الحدث إلا نقاط النهاية على مستوى المؤسسة.
{
"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.
أحداث المكالمات التجريبية
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"
}| الحقل | النوع | الوصف |
|---|---|---|
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
يُرسل عندما تتجاوز قاعدة تنبيه حدّها مع تفعيل قناة التسليم إلى خطافات الويب للمطورين. غير حاجب. تُفعَّل القاعدة مرة واحدة ثم تلتزم بفترة التهدئة الخاصة بها، لذا ينتج عن التجاوز المستمر حدث واحد لكل نافذة تهدئة.
{
"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 |
راجع دليل التنبيهات لإنشاء القواعد والمقاييس وفترات التهدئة وقنوات البريد الإلكتروني / Slack.
أحداث الترحيل
migration.call.complete
يُرسل عند انتهاء مكالمة أُجريت عبر
POST /v1/migrations/{id}/calls،
بغض النظر عن المنصة التي أجرتها. غير حاجب. يصل خلال مدة تصل إلى نحو 5 دقائق
بعد انتهاء المكالمة. يحتوي data على كل حقل من
telephony.complete بالإضافة إلى كتلة migration.
ترسل المكالمة التي يجريها ThunderPhone أيضًا telephony.complete كالمعتاد،
باستخدام call_id نفسه. تُرسل مكالمة على المنصة الأخرى لم تنتهِ بعد ساعتين،
أو اكتمل ترحيلها أو فقدت مفتاحها أولًا، مع
status: "unknown" ودون نص مفرغ.
{
"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% وتُعلّق عملية الترحيل إلى أن يستأنفها شخص ما من علامة تبويب الترحيل الخاصة بالوكيل. لا تحتوي الحمولة على أرقام هواتف أو نصوص مفرغة أو معرّفات مكالمات.
{
"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 |