POST إلى خادمك عند حدوث أمور
أثناء مكالمة — بدء مكالمة واردة أو انتهاء مكالمة أو اكتمال
تشغيل تقييم أو إطلاق تنبيه، وغير ذلك. هناك نموذجا تسليم:
نقاط نهاية الويب هوك (موصى بها)
عناوين URL متعددة، وأسرار لكل نقطة نهاية، وفلاتر أحداث لكل نقطة نهاية،
وإعادات محاولة تلقائية.
أدرها عبر
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.ويب هوك قديم بعنوان URL واحد
عنوان URL واحد لكل مؤسسة. يحمل أحداث دورة حياة المكالمة، بما في ذلك
عمليات تبادل الإعدادات الحاجبة. يُدار عبر
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) أيضًا إلى
الويب هوك القديم ذي عنوان URL الواحد — إذا كان لديك عنوان URL قديم ونقطة
نهاية مطابقة، فستتلقى الحدث عبر كلا المسارين. يوجد السلوك الحاجب
(تبادل إعدادات telephony.incoming / web.incoming
وتوجيه الأدوات
في وضع الويب هوك) حصريًا في المسار القديم؛ وكل تسليم إلى نقطة نهاية هو
إشعار يُرسل دون انتظار.
تنسيق الحمولة
تكون عمليات التسليم إلى نقاط النهاية كائن JSON يحتوي علىdata وevent_id و
type:
event_id فريدًا لكل حدث يتم إصداره. ويكون متطابقًا عبر إعادات المحاولة
وكذلك عبر كل نقطة نهاية تتلقى الحدث — أزل التكرار باستخدامه.
يرسل الويب هوك القديم ذي عنوان URL الواحد type وdata نفسيهما ولكن
من دون event_id:
التحقق من التوقيع
يحمل كل طلب توقيع HMAC-SHA256 محسوبًا على نص الطلب الخام في ترويسةX-ThunderPhone-Signature. مفتاح التوقيع هو secret الخاص بنقطة النهاية (أو secret الخاص بخطاف الويب على مستوى مؤسستك لعمليات التسليم القديمة).
الخطوات
- اقرأ نص الطلب الخام قبل أي تحليل.
- احسب
hmac_sha256(secret, body).hexdigest(). - قارنه بزمن ثابت مع ترويسة
X-ThunderPhone-Signature.
دلالات التسليم
تنطبق هذه الدلالات على عمليات تسليم نقطة النهاية. أما خطاف الويب القديم ذو عنوان URL الواحد فهو محاولة متزامنة واحدة دون إعادة محاولات.إعادة المحاولات
إعادة المحاولات
تتم محاولة كل حدث مرة واحدة فورًا. تُقرّ أي استجابة
2xx
بالتسليم. عند أي نتيجة أخرى (غير 2xx،
أو خطأ في الاتصال، أو انتهاء المهلة)، نعيد المحاولة بعد 1 دقيقة، و5 دقائق، و30 دقيقة، وساعتين، و6 ساعات،
و12 ساعة، و24 ساعة من المحاولة الأولى — أي 8 محاولات خلال
24 ساعة. إذا فشلت كل محاولة، يتوقف التسليم وتُعلَّم نقطة النهاية بالحالة
status="failing" في
نقاط نهاية خطاف الويب. أعد 2xx بمجرد
قبول الحمولة بشكل دائم؛ ونفّذ المعالجة بصورة غير متزامنة.الترتيب
الترتيب
ترتيب التسليم هو بأفضل جهد ممكن. عمليًا، نسلّم الأحداث بالترتيب الذي
تُصدَر به، لكن إعادة المحاولات قد تعيد ترتيبها عند الفشل.
أزل التكرار دائمًا وطابق البيانات باستخدام
call_id / معرّف الكائن.التكرارات
التكرارات
التسليم هو مرة واحدة على الأقل: قد تؤدي إعادة المحاولة بعد استجابة لم
نتلقَّها إلى تكرار حدث. تحمل كل إعادة محاولة المعرّف نفسه
event_id، لذا خزّن المعرّفات التي تمت معالجتها وتجاوز التكرارات. يكون event_id
مشتركًا أيضًا بين نقاط النهاية — فنقطتا النهاية المشتركتان في
الحدث نفسه تتلقيان event_id نفسه.انتهاء المهلات
انتهاء المهلات
تبلغ مهلة عمليات تسليم نقطة النهاية 30 ثانية لكل محاولة. في
المسار القديم، تنتهي مهلة الطلبات الحاجبة التي تتحكم في سلوك المكالمات المباشرة — أي
تبادل إعدادات
telephony.incoming / web.incoming —
بعد 10 ثوانٍ، لكن الاستجابة البطيئة تؤخر الرد على المكالمة، لذا احرص على
الرد خلال بضع ثوانٍ. يتيح إرسال الأدوات في وضع خطاف الويب 20 ثانية.عناوين IP المصدر
عناوين IP المصدر
تنشأ خطافات الويب الصادرة من نطاق عناوين IP السحابية الخاص بـ ThunderPhone.
إذا كان جدار الحماية لديك يتطلب قائمة سماح، فتواصل مع الدعم وسنشارك
النطاقات الحالية.
الاختيار بين خطافات الويب القديمة والقائمة على نقاط النهاية
يجب أن تستهلك عمليات التكامل الجديدة الأحداث عبر خطافات الويب القائمة على
نقاط النهاية. احتفظ بعنوان URL قديم (أو أضف واحدًا) فقط إذا كنت تضبط المكالمات
ديناميكيًا عند وقت الرد أو تستخدم إرسال الأدوات في وضع خطاف الويب — إذ إن
عمليات تبادل الطلبات/الاستجابات هذه تعمل فقط عبر المسار القديم.
ذو صلة
كتالوج الأحداث
جميع أنواع الأحداث وحمولاتها.
نقاط نهاية خطاف الويب
أدر نقاط نهاية متعددة وعوامل تصفية الأحداث والأسرار.
telephony.incoming / web.incoming
الطلب الحاجب الذي يجب أن يجيب عنه خادمك لإعداد المكالمات.
telephony.complete / web.complete
حمولة ما بعد المكالمة تتضمن النص المفرغ والتسجيل والمقاييس.