Skip to main content
يرسل ThunderPhone طلبات HTTP 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:
عند الإرسال، تُسلسَل كل حمولة بشكل معياري — تكون المفاتيح مرتبة أبجديًا، ومن دون مسافات بيضاء، وبترميز UTF-8. أمثلة التنسيق الجميلة في هذه الوثائق مخصصة لسهولة القراءة فقط. راجع كتالوج الأحداث للاطلاع على القائمة الكاملة لأنواع الأحداث وحقول الحمولة.

التحقق من التوقيع

يحمل كل طلب توقيع HMAC-SHA256 محسوبًا على نص الطلب الخام في ترويسة X-ThunderPhone-Signature. مفتاح التوقيع هو secret الخاص بنقطة النهاية (أو secret الخاص بخطاف الويب على مستوى مؤسستك لعمليات التسليم القديمة).

الخطوات

  1. اقرأ نص الطلب الخام قبل أي تحليل.
  2. احسب hmac_sha256(secret, body).hexdigest().
  3. قارنه بزمن ثابت مع ترويسة X-ThunderPhone-Signature.
نوقّع البايتات التي نرسلها كما هي تمامًا، وهذه البايتات هي تسلسل JSON القياسي (مفاتيح مرتبة وفواصل مضغوطة). لذلك ينجح التحقق دائمًا باستخدام النص الخام — وإذا كان إطار العمل لديك يزوّدك بـ JSON محلل فقط، فإن إعادة تسلسله بمفاتيح مرتبة وفواصل مضغوطة تنتج بايتات مطابقة. تُغطّى كلتا الطريقتين في دليل التحقق.

دلالات التسليم

تنطبق هذه الدلالات على عمليات تسليم نقطة النهاية. أما خطاف الويب القديم ذو عنوان 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 السحابية الخاص بـ ThunderPhone. إذا كان جدار الحماية لديك يتطلب قائمة سماح، فتواصل مع الدعم وسنشارك النطاقات الحالية.

الاختيار بين خطافات الويب القديمة والقائمة على نقاط النهاية

يجب أن تستهلك عمليات التكامل الجديدة الأحداث عبر خطافات الويب القائمة على نقاط النهاية. احتفظ بعنوان URL قديم (أو أضف واحدًا) فقط إذا كنت تضبط المكالمات ديناميكيًا عند وقت الرد أو تستخدم إرسال الأدوات في وضع خطاف الويب — إذ إن عمليات تبادل الطلبات/الاستجابات هذه تعمل فقط عبر المسار القديم.

ذو صلة

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

جميع أنواع الأحداث وحمولاتها.

نقاط نهاية خطاف الويب

أدر نقاط نهاية متعددة وعوامل تصفية الأحداث والأسرار.

telephony.incoming / web.incoming

الطلب الحاجب الذي يجب أن يجيب عنه خادمك لإعداد المكالمات.

telephony.complete / web.complete

حمولة ما بعد المكالمة تتضمن النص المفرغ والتسجيل والمقاييس.