hotline.tg

وحدة Webhooks

تلقي الأحداث من الحوارات Hotline في شكل POST-الطلبات بالصيغة JSON إلى نص خارجي لمزيد من المعالجة.

في بوت التثبيت @hotlinetg_bot عبر معلمة الاتصال @WEBHOOKS@ يمكنك تعيين عنوان واحد أو أكثر لمعالجة البريد الصادر POST-طلبات من الخارج Hotline حول الأحداث في الحوارات.

ملاحظة: تحتوي هذه الصفحة على أجزاء مع ترجمة آلية. إذا وجدت صعوبة في فهم هذه المعلومات، فحاول تغيير اللغة إلى الإنجليزية أو الروسية واستخدم نظام ترجمة موقع الويب الموثوق به لديك.

الطلبات الصادرة من الجانب Hotline إلى العناوين المحددة مع أنواع الأحداث المحددة تحتوي على جميع المعلومات الأساسية حول الموضوع و/أو المستخدم المقابل للمعالجة اللاحقة، بالإضافة إلى الحقل api_key الاتصال المُناسب للتحقق من المُرسِل. إذا لزم الأمر، يُمكنك تكوين عملية تحقق إضافية من المُرسِل من جانبك باستخدام عنوان IP الخاص بخادم الوكيل الخاص بنا.

مثال JSON لتكوين المعلمة @WEBHOOKS@:

{
  "https://someapiserver.com/webhooks/test-hook1": [
    "dialog_created",
    "dialog_reopened",
    "dialog_closed",
    "message_received",
    "message_sent",
    "message_intercepted"
  ],
  "https://someapiserver.com/webhooks/test-hook2": [
    "/mark", "/info",
    "/invoice", "/client"
  ]
}

يمكنك تلقي نوعين من الطلبات من الخط الساخن:

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

الأوامر المخصصة - تقارير عن استخدام الأوامر المحددة من قبل المشغلين والتي تبدأ بالرمز / (شرطة مائلة). يمكن مراقبتها كأوامر نظام قياسية (على سبيل المثال /mark أو /close)، بالإضافة إلى أي أوامر مخصصة، على سبيل المثال /invoice (إنشاء فاتورة) /client (الحصول على معلومات عن العميل من خلال user_id в Telegramيمكن لأحداث النوع الثاني إرجاع استجابة، تُعرض في الموضوع مع مربع الحوار المقابل. تُسهّل هذه الأحداث تنفيذ أوامر مخصصة تُوسّع وظائف الخط الساخن بشكل كبير أو تُسرّع عمل المُشغّل.

تتوفر خطافات الويب فقط لمستخدمي النظام المدفوعين.

لشراء اشتراك مدفوع أو توصيل نسخة تجريبية لعدة أيام لاختبار الوظيفة، يرجى الاتصال @hotlinetg_support

النوع الأول: أحداث النظام

تُعرَّف أحداث النظام من مجموعة قيم ثابتة. تُرسَل أحداث النظام دون إرجاع أي نتائج إلى موضوع الحوار المُقابل.

الأنواع التالية من الأحداث متاحة حاليًا: تم إنشاء الحوار, تم إعادة فتح الحوار, تم إغلاق الحوار, message_تلقى, message_مرسل, message_تم اعتراضه.

أمثلة على استخدام أحداث النظام في الحوارات:

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

مثال على طلب صادر لإعادة فتح الحوار:

{
    "event_type": "dialog_reopened",
    "timestamp": "2025-10-09 00:24:55",
    "instance_id": "13209946874612345",
    "data": {
        "chat_id": -1002146012345,
        "thread_id": 5602541568,
        "topic_id": 5343,
        "topic_link": "https://t.me/c/2146012345/5343",
        "user_id": 5339212345,
        "frontend_chat_id": 5339212345,
        "frontend_topic_id": null,
        "frontend_topic_link": null,
        "frontend_user_id": 6406751371,
        "chat_type": "private",
        "title": "Some User Name",
        "department": "default"
    },
    "api_key": "pQTngMZLh0NmAh"
}

مثال على طلب صادر لرسالة مرسلة:

{
    "event_type": "message_sent",
    "timestamp": "2025-10-09 00:21:57",
    "instance_id": "132099468746812345",
    "data": {
        "backend_chat_id": -1002146012345,
        "backend_thread_id": 5602541568,
        "backend_message_id": 6171918336,
        "sender_user_id": 5339212345,
        "frontend_user_id": 640675123,
        "frontend_message_id": 3260022784,
        "text": "test message",
        "content_type": "messageText",
        "department": "default",
        "backend_reply_message_id": 0
    },
    "api_key": "pQTngMZLh0NmAh"
}

النوع 2: الأوامر المخصصة

أي أمر يبدأ بالرمز / يمكن تحديد (الشرطة المائلة) كقيمة لتلقي الأحداث المتعلقة بها والمعلومات حول الحوار المقابل.

يمكنك تحديد أوامر النظام القياسية الموجودة (/info, /mark, /close إلخ)، بالإضافة إلى النصوص المخصصة، لمنطق الإجراءات التي سيكون البرنامج النصي الخاص بك مسؤولاً عنها، وإذا لزم الأمر، قم بإرجاع النتيجة إلى الموضوع في النموذج JSON أو رسالة نصية (يُسمح بالترميز في التنسيق) Markdown v2).

أمثلة على استخدام خطافات الويب مع الأوامر المخصصة:

تمديد الأمر القياسي /info معلومات إضافية عن المستخدم
تسجيل التغييرات في حالات الحوار بواسطة المشغلين عبر أمر /mark
تسجيل أحداث طلبات الإغلاق بواسطة الأمر /close
إضافة الأوامر الخاصة بك، على سبيل المثال /invoice, /client أو أي شيء آخر يتطلب معلومات حول الموضوع الذي تجري فيه المحادثة وبيانات المستخدم أو الدردشة.

مثال على طلب استدعاء أمر /mark deal مشغل الصفقة:

{
    "event_type": "/mark",
    "timestamp": "2025-10-08 20:41:20",
    "instance_id": "132099468746812345",
    "data": {
        "command_data": "deal",
        "chat_id": -1002146012345,
        "topic_id": 5,
        "topic_link": "https://t.me/c/2146012345/5",
        "message_id": 5850,
        "reply_message_id": null,
        "sender_user_id": 123456,
        "user_id": 7890123,
        "frontend_chat_id": 7890123,
        "frontend_thread_id": null
    },
    "api_key": "pQTngMZLh0NmAh"
}

لعرض نتيجة أمر في موضوع ما، يجب أن تكون استجابة الخادم لديك إما في نص عادي أو في النموذج JSON، والتي تحتوي على عقدة باسم message أو error (سيتم تجاهل العقد الأخرى).

مثال على استجابة ناجحة من الخادم الخاص بك بالتنسيق JSON مع رسالة ستظهر في الموضوع مع الحوار:

{
    "message": "Deal created: http://internal.domain.com/crm/deals/76238",
    "status": "ok"
}

مثال على استجابة الخادم الخاص بك مع نص الخطأ بالتنسيق JSON، والتي سيتم عرضها في الموضوع بالحوار:

{
    "error": "User 12345678 not found in our database"
}

للاستفسارات حول خطافات الويب، أو لتفعيل اشتراك مدفوع أو تجريبي، يرجى الاتصال بالدعم. @hotlinetg_support.