Skip to main content
عندما تصل مكالمة هاتفية واردة إلى رقم من دون وكيل مُعيَّن، أو تبدأ جلسة أداة ويب على مفتاح قابل للنشر في mode="webhook"، يرسل ThunderPhone طلب telephony.incoming / web.incoming حاجبًا إلى عنوان URL القديم لخطاف الويب وينتظر ما يصل إلى 10 ثوانٍ للحصول على استجابة إعداد. استخدم هذا التبادل لاختيار موجّه وصوت وأدوات ديناميكيًا لكل مكالمة — راجع دليل إعداد المكالمات الديناميكي للاطلاع على النمط الكامل.
تتلقى نقاط نهاية خطاف الويب المشتركة أيضًا telephony.incoming / web.incoming — لكل مكالمة واردة وجلسة ويب، سواء كانت مُعدَّة لوكيل أم لا — لكن عمليات التسليم هذه إشعارات تُرسل دون انتظار مع event_id، وليست حاجبة مطلقًا. يحمل خطاف الويب القديم ذو عنوان URL الواحد فقط تبادل الإعداد الوارد في هذه الصفحة. توجد أشكال إشعارات نقاط النهاية في كتالوج الأحداث.
لا يحتوي التبادل الحاجب على بديل احتياطي: إذا أعاد معالجك حالة ليست 2xx، أو انتهت مهلته، أو أعاد إعدادًا يفشل التحقق منه، تُرفض المكالمة (لا تتصل المكالمة الهاتفية؛ ويفشل طلب جلسة الأداة بالرمز 502/422). استجب بسرعة — يسمع المتصل نغمة الرنين أثناء اتخاذك للقرار.

حمولة الطلب

للمكالمات الهاتفية (telephony.incoming):
بالنسبة إلى جلسات أداة الويب (web.incoming)، يحدّد data صفحة التضمين بدلًا من أرقام الهاتف:
ترسل الأدوات في وضع خطاف الويب هذا الطلب إلى webhook_url الخاص بالمفتاح القابل للنشر عند تعيينه، مع الرجوع إلى عنوان URL لخطاف الويب على مستوى المؤسسة. وفي كلتا الحالتين، يُوقَّع باستخدام secret لخطاف ويب المؤسسة.

مخطط الاستجابة

أعِد كائن JSON يصف إعدادات الوكيل لهذه المكالمة. prompt وvoice مطلوبان؛ وكل شيء آخر اختياري.
المفاتيح غير المعروفة من المستوى الأعلى يتم تجاهلها بصمت — اسم حقل به خطأ إملائي لا يرفض الإعداد، لكنه لا يُطبّق. لا يُقبل ترتيب التحدث وmax_hold_seconds هنا؛ إذ يمكن إعدادهما على الوكيل نفسه فقط.
لأن prompt وvoice مطلوبان، فإن إرجاع {} أو أي استجابة تفشل التحقق يرفض المكالمة باستخدام 422 — لا توجد آلية بديلة لوكيل ثابت في هذا المسار (إذ لا يكون لرقم أو مفتاح في وضع webhook وكيل معيّن).

حد حجم الاستجابة

تقتصر استجابات الإعداد على 5 MiB. إذا أعاد المعالج استجابة أكبر، بما في ذلك بحالة 2xx، يُبلغ ThunderPhone أن الاستجابة تجاوزت الحد ويرفض المكالمة أو جلسة الأداة. اجعل الاستجابة مقتصرة على الحقول اللازمة لإعداد المكالمة؛ واستضف البيانات الكبيرة خلف أدوات الدوال أو خدمة أخرى بدلاً من تضمينها في الإعداد.

معالج نموذجي


الاستجابة باستخدام أدوات الدوال

أرفق أدوات حتى يتمكن الذكاء الاصطناعي من استدعاء واجهات برمجة التطبيقات الخاصة بك أثناء المحادثة:
تُوقَّع طلبات نقطة نهاية الأداة باستخدام سر خطاف الويب نفسه للمؤسسة الذي وقّع هذا التبادل. راجع أدوات الدوال للاطلاع على البنية الدقيقة وتنسيق الطلب الموقّع.

مرجع سريع لمستويات المنتج


ذو صلة

telephony.complete / web.complete

حدث انتهاء المكالمة غير الحاجب.

أدوات الدوال

مخطط JSON الكامل لـ tools[] وعقد نقطة النهاية الموقّع.

نقاط نهاية Webhook

اشترك بعدة عناوين URL في telephony.incoming / web.incoming.

إعداد المكالمات الديناميكي

أنماط للموجّهات والأدوات واختبارات A/B لكل متصل.