إنتقل إلى المحتوى الرئيسي

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

ما هو​

يتضمن إعداد التكاملات في BotBat ثلاثة أنشطة عملية: إنشاء مفاتيح API للوصول البرمجي إلى REST API، وتهيئة خطافات الويب الصادرة لدفع إشعارات الأحداث إلى الأنظمة الخارجية، وإعداد خطافات الويب الواردة التي تتيح للأنظمة الخارجية تشغيل سير عمل BotBat. توفر هذه الصفحة تعليمات تفصيلية خطوة بخطوة لكل نشاط.

تقوم مفاتيح API بمصادقة تطبيقاتك المخصصة والسكربتات والخدمات الخلفية عند استدعاء REST API الخاص بـ BotBat. كل مفتاح هو رمز Bearer طويل الأمد تضمّنه في ترويسة Authorization لكل طلب HTTP. يمكنك إنشاء مفاتيح متعددة بأسماء وصفية وتتبع استخدامها وإلغائها بشكل فردي عندما لا تعود مطلوبة.

تتيح خطافات الويب البنية المبنية على الأحداث. ترسل خطافات الويب الصادرة طلب HTTP POST إلى نقطة النهاية الخاصة بك كلما وقع حدث محدد في BotBat (مثل تسليم رسالة أو اكتمال حملة). تعمل خطافات الويب الواردة بالعكس: يرسل نظامك الخارجي طلب POST إلى عنوان URL يولده BotBat، مما يشغل سير عمل داخل المنصة. معاً، تتيح لك هذه الآليات بناء تكاملات في الوقت الفعلي ومترابطة بشكل فضفاض دون الحاجة إلى الاستقصاء.

متى تستخدم​

بناء تكامل مخصص. عندما يحتاج فريقك الهندسي لإرسال رسائل أو إدارة جهات الاتصال أو تشغيل سير العمل من تطبيقك الخاص، ابدأ بإنشاء مفتاح API. يفتح المفتاح الوصول الكامل إلى REST API الخاص بـ BotBat، والذي يغطي نقاط نهاية المراسلة وجهات الاتصال والحملات وسير العمل والتحليلات.

الاتصال بنظام إشعارات. قم بإعداد خطافات الويب الصادرة لدفع أحداث BotBat إلى Slack أو PagerDuty أو مستودع بيانات أو أي نظام يقبل استدعاءات HTTP. على سبيل المثال، قد ترسل خطاف ويب إلى منصة التحليلات الخاصة بك في كل مرة تنتهي فيها حملة، أو تنبه قائد الدعم الخاص بك في Slack كلما كانت محادثة في الانتظار لأكثر من 10 دقائق.

استقبال البيانات من أدوات خارجية. قم بتهيئة خطافات الويب الواردة بحيث يمكن لأنظمة خارجية مثل Shopify أو Stripe أو نظام CRM الداخلي الخاص بك إرسال بيانات إلى BotBat وتشغيل سير عمل آلي. يمكن لمنصة تجارة إلكترونية إخطار BotBat بطلب جديد، مما يشغل بعد ذلك رسالة تأكيد عبر WhatsApp للعميل.

تدوير بيانات الاعتماد للامتثال الأمني. تتطلب أفضل الممارسات الأمنية تدوير المفاتيح بشكل دوري. تدعم واجهة إدارة مفاتيح API التدوير بدون توقف: أنشئ مفتاحاً جديداً، وحدّث تطبيقك، وتحقق من أنه يعمل، ثم ألغِ المفتاح القديم.

مفاتيح API​

إنشاء وإدارة مفاتيح API​

  1. الانتقال إلى مفاتيح API. اذهب إلى التكاملات في الشريط الجانبي وانقر على علامة تبويب "مفاتيح API". تعرض القائمة جميع المفاتيح الموجودة بأسمائها وتواريخ إنشائها والطوابع الزمنية لآخر استخدام.
API Keys tab showing keys with names, creation dates, and last-used timestamps
  1. إنشاء مفتاح API جديد. انقر على "إنشاء مفتاح API". أدخل اسماً وصفياً يحدد التكامل أو البيئة (على سبيل المثال، "تكامل CRM - الإنتاج" أو "مفتاح اختبار المرحلة"). اختيارياً حدد تاريخ انتهاء الصلاحية. انقر "إنشاء".
Create API Key dialog showing name field, expiration options, and the generated key value

  1. انسخ المفتاح فوراً. يتم عرض قيمة مفتاح API الكاملة مرة واحدة فقط، عند الإنشاء. انقر زر النسخ وخزّن المفتاح في مكان آمن مثل مدير أسرار أو خزنة كلمات مرور أو متغير بيئة. لا يمكنك عرض المفتاح الكامل مرة أخرى بعد إغلاق هذا الحوار.

  2. استخدام المفتاح في طلبات API. ضمّن المفتاح في ترويسة Authorization لكل طلب HTTP إلى REST API الخاص بـ BotBat:

    Authorization: Bearer YOUR_API_KEY

    تقبل جميع نقاط نهاية REST API القياسية طريقة المصادقة هذه. ارجع إلى وثائق BotBat API للحصول على القائمة الكاملة لنقاط النهاية المتاحة.

  3. مراقبة استخدام المفتاح. تعرض قائمة مفاتيح API الطابع الزمني لآخر استخدام لكل مفتاح. المفاتيح التي لم تُستخدم لفترة طويلة قد تكون غير مستخدمة ويجب النظر في إلغائها. يصف الجدول أدناه كل عمود في قائمة مفاتيح API.

العمودالوصف
الاسمالتسمية الوصفية التي عيّنتها عند إنشاء المفتاح
تاريخ الإنشاءتاريخ ووقت توليد المفتاح
آخر استخدامأحدث طابع زمني تم فيه استخدام المفتاح في طلب API
تاريخ الانتهاءتاريخ انتهاء الصلاحية، إن تم تحديده؛ فارغ إذا لم يكن للمفتاح تاريخ انتهاء
الإجراءاتقائمة بخيارات نسخ بادئة المفتاح أو التدوير أو الإلغاء

  1. تدوير المفتاح. للتدوير بدون توقف، أنشئ مفتاحاً جديداً أولاً، وحدّث تطبيقك لاستخدام المفتاح الجديد، وتحقق من نجاح استدعاءات API مع المفتاح الجديد، ثم ألغِ المفتاح القديم. لا تلغِ المفتاح القديم أبداً قبل التأكد من عمل المفتاح الجديد.

  2. إلغاء المفتاح. انقر على قائمة النقاط الثلاث على أي مفتاح API واختر "إلغاء". يؤدي هذا إلى إبطال المفتاح فوراً. ستتلقى أي طلبات لاحقة تستخدم المفتاح الملغى استجابة 401 Unauthorized. لا يمكن التراجع عن الإلغاء.

خطافات الويب الصادرة​

إضافة وتهيئة نقاط نهاية خطافات الويب​

  1. الانتقال إلى خطافات الويب. اذهب إلى التكاملات في الشريط الجانبي وانقر على علامة تبويب "خطافات الويب". تعرض اللوحة جميع خطافات الويب المهيأة مع مؤشرات الحالة وعناوين URL لنقاط النهاية وعدد الأحداث المشترك فيها.

  2. إضافة نقطة نهاية خطاف ويب. انقر "إضافة خطاف ويب" واملأ الحقول التالية:

الحقلمطلوبالوصف
عنوان URL لنقطة النهايةنعمعنوان HTTPS URL الذي يرسل إليه BotBat حمولات الأحداث. يتم رفض عناوين HTTP URL.
الوصفلاملاحظة مختصرة تشرح الغرض من خطاف الويب هذا (مثل "خط تحليل البيانات")
سر التوقيعلاسر مشترك يُستخدم لتوليد توقيع HMAC للتحقق من الحمولة
Add Webhook form showing endpoint URL, description, signing secret, and event checkboxes
  1. اختيار الأحداث للاشتراك. اختر أي أحداث BotBat يجب أن تشغل تسليم حمولة إلى نقطة النهاية هذه. اشترك فقط في الأحداث التي تعالجها نقطة النهاية الخاصة بك فعلياً؛ الاشتراك في كل شيء يولد حركة بيانات غير ضرورية.
Event selection panel showing available events grouped by category

يسرد الجدول التالي أحداث خطافات الويب الأكثر استخداماً.

الحدثشرط التشغيل
message.receivedوصول رسالة جديدة من جهة اتصال على أي قناة
message.deliveredتأكيد تسليم رسالة أرسلها BotBat من قبل مزود القناة
message.readتعليم الرسالة كمقروءة من قبل المستلم (القنوات التي تدعم إيصالات القراءة)
conversation.createdبدء محادثة جديدة من قبل جهة اتصال أو النظام
conversation.closedتعليم محادثة كمغلقة من قبل وكيل أو أتمتة
contact.createdإضافة سجل جهة اتصال جديد إلى BotBat
contact.updatedتعديل سمة واحدة أو أكثر على جهة اتصال موجودة
campaign.completedإنهاء حملة إرسال جميع الرسائل المجدولة

  1. الحفظ والتفعيل. انقر "حفظ". يصبح خطاف الويب نشطاً فوراً ويبدأ في استقبال الحمولات للأحداث المختارة.

  2. اختبار التسليم. انقر "إرسال اختبار" لإرسال حمولة عينة إلى نقطة النهاية الخاصة بك. يعرض BotBat رمز استجابة HTTP وجسم الاستجابة الذي أعادته نقطة النهاية الخاصة بك. استجابة 200 OK تؤكد أن نقطة النهاية قابلة للوصول وتعالج البيانات بشكل صحيح.

Test result showing the sent payload, response code, and response body
  1. عرض سجلات التسليم. انقر على خطاف ويب لفتح سجل التسليم الخاص به. يعرض كل إدخال نوع الحدث والطابع الزمني ورمز استجابة HTTP ووقت الاستجابة بالمللي ثانية وحمولة الطلب الكاملة. استخدم مرشح الحالة (نجاح، فشل) لعزل المشكلات بسرعة.
Log entries showing timestamps, event types, response codes, and status
  1. فهم إعادة المحاولات ومعالجة الفشل. يعيد BotBat محاولة عمليات تسليم خطافات الويب الفاشلة (أي استجابة غير 2xx) حتى 5 مرات باستخدام التراجع الأسي. فترات إعادة المحاولة تقريباً هي 10 ثوانٍ و30 ثانية ودقيقتان و10 دقائق و30 دقيقة. إذا فشلت جميع المحاولات، يتم تسجيل الحدث على أنه فشل نهائي ولا يتم إجراء محاولات أخرى.

خطافات الويب الواردة (مشغلات سير العمل)​

تتيح خطافات الويب الواردة للأنظمة الخارجية تشغيل سير عمل BotBat عن طريق إرسال طلب HTTP POST إلى عنوان URL فريد.

  1. إنشاء سير عمل بمشغل خطاف ويب. في صفحة سير العمل، أنشئ سير عمل جديداً واختر "خطاف ويب" كنوع المشغل. يقوم BotBat تلقائياً بتوليد عنوان URL فريد لخطاف الويب لسير العمل هذا.
Workflow editor showing webhook trigger node with the generated URL

  1. نسخ عنوان URL المولّد. انقر زر النسخ بجوار العنوان. هذه هي نقطة النهاية التي سيستدعيها نظامك الخارجي.

  2. تهيئة نظامك الخارجي. الصق العنوان في إعدادات خطاف الويب أو الإشعارات لنظامك الخارجي (على سبيل المثال، خطافات ويب طلبات Shopify أو أحداث دفع Stripe أو تطبيق مخصص). عندما يرسل النظام الخارجي طلب POST إلى هذا العنوان مع جسم JSON، يتم تشغيل سير العمل.

  3. تعيين البيانات الواردة. في تهيئة مشغل سير العمل، حدد هيكل حمولة JSON المتوقعة. يتيح لك هذا الإشارة إلى حقول فردية من البيانات الواردة كمتغيرات عبر خطوات سير العمل. على سبيل المثال، إذا كانت الحمولة تحتوي على {"orderId": "12345", "customerEmail": "user@example.com"}، يمكنك استخدام {{trigger.orderId}} و{{trigger.customerEmail}} في إجراءات سير العمل اللاحقة.

الأخطاء الشائعة​

عدم نسخ مفتاح API عند الإنشاء. يتم عرض قيمة المفتاح الكاملة مرة واحدة فقط. إذا أغلقت الحوار دون نسخه، يجب عليك إنشاء مفتاح جديد. لا توجد آلية استرداد للمفاتيح المفقودة.

استخدام HTTP بدلاً من HTTPS لنقاط نهاية خطافات الويب. يتطلب BotBat بروتوكول HTTPS لجميع نقاط نهاية خطافات الويب. يضمن هذا تشفير حمولات الأحداث أثناء النقل. يتم رفض عناوين HTTP URL عند التهيئة.

الاشتراك في أحداث كثيرة جداً. اشتراك خطاف ويب في كل نوع حدث متاح يولد حركة بيانات كبيرة، خاصة إذا كان حسابك يعالج أحجام رسائل عالية. اشترك فقط في الأحداث التي تحتاجها نقطة النهاية الخاصة بك فعلياً، واستخدم الترشيح من جانب الخادم إذا كنت تحتاج لمعالجة مجموعة فرعية من فئة حدث واسعة.

عدم التحقق من توقيعات خطافات الويب. إذا قمت بتعيين سر توقيع لكن لم تنفذ التحقق من HMAC على نقطة النهاية الخاصة بك، فلا يمكنك التأكد من أن الحمولات الواردة تنشأ فعلاً من BotBat. يمكن لمهاجم يكتشف عنوان URL لنقطة النهاية الخاصة بك إرسال حمولات مزيفة. تحقق دائماً من ترويسة X-BotBat-Signature باستخدام سر التوقيع الخاص بك.

جدار الحماية يحظر عنوان IP الصادر لـ BotBat. إذا كانت نقطة نهاية خطاف الويب الخاصة بك خلف جدار حماية مؤسسي أو مجموعة أمان سحابية، يجب عليك إضافة عناوين IP الصادرة لـ BotBat إلى القائمة البيضاء. تواصل مع دعم BotBat للحصول على نطاقات IP الحالية وقم بتحديث قواعد جدار الحماية وفقاً لذلك.

تلميح

عند بناء تكامل مخصص، ابدأ بإنشاء مفتاح API بتاريخ انتهاء قصير (على سبيل المثال، 7 أيام) للتطوير والاختبار. بمجرد أن يكون التكامل مستقراً ويجتاز ضمان الجودة، أنشئ مفتاح إنتاج طويل الأمد وألغِ مفتاح التطوير.

  • قائمة مفاتيح API
  • إنشاء مفتاح API
  • إضافة Webhook
  • الاشتراك في الأحداث
  • سجل التسليم
  • Webhook الوارد