ThunderPhone 2.0 متاح الآن.خدمة ذاتية، ابتداءً من 2 سنت/دقيقة.اقرأ الإعلان

Webhooks

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

جميع أنواع أحداث خطافات الويب التي يصدرها 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_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل

telephony.complete

يُرسل عند انتهاء مكالمة هاتفية واردة أو صادرة. غير حاجب. يتضمن النص المفرغ، ورابط التسجيل عند توفره، وملخص الفوترة. راجع telephony.complete / web.complete للاطلاع على مخطط الحمولة.

الحقلالنوعالوصف
agent_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | 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_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | 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_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
positionintegerفهرس الدور في سجل المكالمة — معرّف ثابت للترتيب
rolestringassistant (كلام الوكيل) أو user (كلام المتصل)
textstringنص الدور المفرغ كما هو معروف وقت الإرسال
entry_typestringنوع إدخال السجل الأساسي: completion (الوكيل)، أو user_turn / span (المتصل)
start_ms, end_msintegerإزاحات الصوت بالمللي ثانية منذ بدء المكالمة؛ تكون موجودة فقط عندما يكون توقيت التشغيل معروفًا بالفعل وقت الإرسال

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_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل

web.complete

المكافئ في قناة الويب لـ telephony.complete، ويغطي مكالمات أداة الويب (direction: "web") ومكالمات اختبار ميكروفون أداة الإنشاء (direction: "test"). غير حاجب. له بنية الحمولة نفسها التي لدى telephony.complete، بالإضافة إلى origin_domain، مع ضبط from_number على "web".

الحقلالنوعالوصف
agent_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل

web.tool

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

الحقلالنوعالوصف
agent_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل

web.turn

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

الحقلالنوعالوصف
agent_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | 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_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
summarystring | nullملخص المكالمة المكتمل عندما يكون لدى الوكيل خيار إنشاء ملخص للمكالمة مفعّلًا، لذلك يرسل حدث الاستخراج المتأخر أيضًا ملخصًا لم يصل ضمن نافذة الاكتمال؛ وإلا تكون القيمة null. لا ترسل الوكلاء الذين لديهم ملخص دون حقول استخراج هذا الحدث مطلقًا: اقرأ الملخص المتأخر من GET /v1/calls/{call_id}
extracted_data.statusstringدائمًا completed لهذا الحدث
extracted_data.fieldsobjectالقيم مفهرسة بمفاتيح حقول الاستخراج المهيأة؛ القيم غير المتاحة هي null
extracted_data.evidenceobjectالأدلة مفهرسة بحقل الاستخراج. تحتوي القيمة غير الفارغة على الاقتباس الدقيق المتحقق منه بنيويًا، بحد أقصى 1,000 حرف، وspeaker_role، إما caller أو agent، وturn_index؛ تُرفض الاقتباسات الأطول التي يعيدها النموذج بدلًا من اقتطاعها، وتكون الأدلة null كلما كان حقلها null
extracted_data.verificationstringتكون verified فقط عندما تعيد مرحلة الأدلة المستقلة حكمًا صالحًا واحدًا بالضبط لكل حقل مرشح. تعني unavailable أن المرحلة فشلت أو انتهت مهلتها أو لم تتوفر لها ميزانية كافية أو أعادت مخرجات مشوهة أو جزئية. تحافظ المرحلة غير المتاحة بالكامل على القيم المؤسسة بنيويًا لمراجعة العميل. بالنسبة إلى المخرجات الجزئية، تُطبق الأحكام الصالحة ويُعيّن كل مرشح لا يملك حكمًا صالحًا واحدًا بالضبط إلى قيمة فارغة
extracted_data.field_reasonsobjectأسباب مفهرسة بالحقول التي عُيّنت إلى قيمة فارغة بواسطة التأسيس البنيوي أو المدقق المستقل
extracted_data.schema_versionstringتجزئة مخطط الحقول الدقيق المستخدم لهذا الاستخراج
extracted_attimestampوقت الاكتمال بتنسيق ISO 8601
modelstringالنموذج المستخدم للاستخراج

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_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
issue_report.severitystringcritical أو warning أو info
issue_report.statusstringopen أو resolved
issue_report.sourcestringuser، قُدّم من لوحة التحكم، أو 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"
}
الحقلالنوعالوصف
automaticbooleantrue للتصعيد التلقائي؛ وfalse للتصعيد اليدوي
cluster_idUUIDنمط المشكلة المُصعّد
escalation_idUUIDسجل التصعيد
statusstringopen عند إرسال الحدث

هذا إشعار وليس حزمة أدلة. استخدم 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_idinteger | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
agent_namestring | nullالوكيل الذي عالج المكالمة، عند تعيين وكيل
test_call_run.target_typestringagent أو phone_number
test_call_run.target_idintegerمعرّف الوكيل أو معرّف رقم الهاتف الذي استهدفه التشغيل، بما يتطابق مع target_type
test_call_run.statusstringcompleted أو failed
test_call_run.call_idinteger | nullnull عندما يفشل التشغيل قبل إجراء مكالمة
test_call_run.error_messagestringفارغ عند النجاح

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

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_nameUUID, stringالقاعدة التي تم تفعيلها
metricstringsuccess_rate أو failure_rate أو avg_score أو call_volume أو suite_regression
comparatorstringlt أو lte أو gt أو gte
metric_valuenumberقيمة المقياس ضمن النافذة عند تفعيل القاعدة
thresholdnumberالحد المُعدّ
window_hoursintegerنافذة التقييم السابقة
fired_attimestamp

راجع دليل التنبيهات لإنشاء القواعد والمقاييس وفترات التهدئة وقنوات البريد الإلكتروني / 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.idUUIDالترحيل
migration.routing_idUUIDالمكالمة المُوجَّهة، كما أُعيدت عند إجرائها
migration.armstringours (أجراها ThunderPhone) أو vendor (أجرتها المنصة الأخرى)
migration.vendorstringretell أو vapi أو elevenlabs أو bland
migration.vendor_call_idstring | nullمعرّف المكالمة في المنصة الأخرى؛ null لـ ours
migration.metadataobjectبيانات metadata التي أرسلتها عند إجراء المكالمة
migration.vendor_cost_usdstring | nullالتكلفة التي أبلغت بها المنصة الأخرى للمكالمة، عند توفرها
call_idinteger | nullمعرّف مكالمة ThunderPhone؛ null لـ vendor
statusstringبالنسبة إلى 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_idUUIDعملية الترحيل
vendorstringretell أو vapi أو elevenlabs أو bland
reasonstringours_failed_burst ‏(3 اتصالات فاشلة خلال 15 دقيقة)، أو dropped_calls ‏(انتهت مكالمتان قبل أن يجيب الوكيل، خلال 30 دقيقة)، أو rate_gap ‏(فجوة في معدل نتائج المهام عبر ما لا يقل عن rollback_min_calls مكالمة مُقيَّمة لكل جانب)
previous_percentintegerحصة ThunderPhone من المكالمات قبل التراجع
ours_percentintegerدائمًا 0
stepinteger | nullخطوة الجدول التي كانت عليها العملية (تبدأ من 0)
ours / theirsobject | nullالمكالمات المُقيَّمة في الخطوة الحالية ومعدل نجاحها؛ قد تمثل theirs آخر 30 يومًا عندما تحتوي الخطوة على عدد قليل جدًا من المكالمات. تكون null عند عدم وجود أي منها
ours_failedintegerالاتصالات الفاشلة المُحتسبة خلال آخر 15 دقيقة
droppedintegerالمكالمات المُحتسبة على أنها منقطعة خلال آخر 30 دقيقة
rolled_back_attimestamp

ذو صلة