ويب هوك Deskgram 2: إعداد الأحداث والتسليم

نظرة عامة على وحدة الويب هوك

ترسل الويب هوك أحداث Deskgram إلى عنوان تختاره: نظام CRM أو خدمة أتمتة أو تطبيقك الخاص. هذه إشعارات صادرة من Deskgram، ولا تضبط webhook في Telegram Bot API ولا تنشئ قناة أوامر واردة إلى البرنامج.

تمت المراجعة مقابل الشفرة في 24 أكتوبر 2026.

قبل البداية: يجب أن يكون Deskgram قيد التشغيل، وأن يمكن الوصول إلى النظام المستقبل من حاسوب البرنامج. يستخدم الإرسال POST مع JSON. لا تُستعاد عمليات التسليم المقطوعة تلقائيًا بعد إعادة تشغيل البرنامج.

الإعداد من الواجهة لا يتطلب البرمجة. لمطوري النظام المستقبل ومستخدمي HTTP المحلي، يتوفر مرجع API.

إعداد سريع

1. احصل على عنوان webhook الوارد من النظام المستقبل، وجهّز السر أو رمز الوصول إذا لزم.
2. في Deskgram، افتح الإعدادات ← التكاملات.
3. اختر جديد، وأدخل الاسم وWebhook URL.
4. في الإجراءات المراد إرسالها، حدد الأحداث.
5. في من أي وحدات، أبقِ جميع الوحدات أو اختر المطلوب.
6. في محتوى الطلب، اختر التنسيق. يمكن البدء بـ JSON القياسي لـ Deskgram إذا كان المستقبل يقبله.
7. أدخل السر والترويسات الإضافية عند الحاجة.
8. راجع تفعيل الويب هوك بعد الحفظ، ثم اضغط إنشاء.
9. اضغط اختبار، وافتح السجل وتفاصيل التسليم.
10. نفذ إجراءً فعليًا قصيرًا يطابق أحد الأحداث، وتحقق من النتيجة عند المستقبل.

الاختبار يستخدم الإعدادات المحفوظة. بعد تغيير URL أو السر أو الأحداث أو الحقول، احفظ أولًا ثم اختبر. يمكنك إنشاء عدة نقاط استقبال بعناوين واشتراكات وتنسيقات مختلفة.

ربط CRM

أدخل عنوان webhook الوارد في CRM، لا عنوان الصفحة الرئيسية أو لوحة الحساب. مثال وهمي لقناة متوافقة مع Deskgram:

https://crm.example.com/api/v1/channel-webhooks/deskgram/123

النطاق ورقم القناة للتوضيح فقط؛ استخدم العنوان الذي يوفره CRM لديك.

يتعرف Deskgram على المسارات /channel-webhooks/deskgram/{id} ويظهر حقل سر CRM. يُرسل السر في ترويسة x-secret. يوفر CRM العنوان والسر بصورة منفصلة؛ لا يمكن استخراج السر من URL وحده.

لأنظمة CRM الأخرى، راجع JSON والمصادقة المطلوبة. عميل CRM محتمل ليس محولًا عامًا لكل الأنظمة؛ يجب أن تطابق أسماء الحقول عقد النظام المستقبل.

في n8n أو Make أو Zapier أو API خاصة، انسخ عنوان خطوة الاستقبال واضبط حقولها المطلوبة. يجب أن يكون مسار العمل الوارد مفعّلًا ومتاحًا.

اختيار الأحداث

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

انتهاء المهمة لا يثبت نجاح كل إجراءاتها؛ العدادات والأخطاء تعتمد على الوحدة. تخطي مستلم أو فشل التعرف عليه لا يؤدي دائمًا إلى message.failed، ولا يوجد حاليًا حدث منفصل للتخطي.

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

زر نتائج المهام يحدد الأحداث النهائية الثلاثة، وكل المتاح يحدد الستة، ومسح يزيل الاختيار. بعد المسح حدد المطلوب قبل الحفظ.

مرشح الوحدات

يحدد المرشح المهام التي يمكن أخذ الأحداث منها. كل الوحدات لا يقيد المصدر، واختيار وحدات يحصره في المحدد.

مثلًا task.completed مع spampm يعني انتهاء مهمة رسائل خاصة، بينما message.sent مع spampm يعني رسالة منفردة من تلك المهمة.

اختيار وحدة لا يضيف لها أنواع أحداث جديدة. أحداث الرسائل والردود الحية مرتبطة حاليًا بـ spam_pm؛ اختيار وحدة أخرى لا يفعّل هذه الإمكانية تلقائيًا.

اختيار بيانات الطلب

المحتوى الفعلي يعتمد على الحدث وقائمة الحقول المحفوظة. قارن المعاينة مع البيانات المرسلة في تفاصيل تسليم حقيقي.

حقول خاصة

في كل صف، أدخل اسم الحقل الذي يتوقعه المستقبل، واختر مصدر Deskgram، ثم فعّل مفتاح الحقل.

مثال افتراضي:

قد ينتج حدث رسالة البيانات التالية:

{  "contact": {    "telegram_id": "123456789",    "username": "example_client"  },  "comment": "مرحبًا!"}

النقطة في اسم الهدف تنشئ كائنًا متداخلًا. عند غياب قيمة المصدر يُحذف الحقل. قد يغيب الهاتف؛ الويب هوك لا يكشف رقمًا مخفيًا.

حذف أو تعطيل كل الحقول يرسل {}، ولا يستبدلها بالحدث الكامل. المعاينة مثال وليست بيانات مستقبل حقيقي؛ قد يحتوي الطلب الفعلي حقولًا أقل.

منشئ الحقول يختار البيانات ويعيد تسميتها، ولا ينفذ JavaScript أو حسابات أو استعلامات CRM أو سلسلة طلبات HTTP.

إعدادات إضافية

مثال:

{  "Authorization": "Bearer YOUR_RECEIVER_TOKEN"}

YOURRECEIVERTOKEN يرمز إلى رمز النظام المستقبل، لا إلى مفتاح ترخيص Deskgram.

عند تعديل إعداد محفوظ من الواجهة، ترك حقل السر فارغًا يحفظ السر السابق. لا يُعرض محتواه مجددًا. تختلف قواعد المسح الصريح في REST API كما يوضح المرجع.

عند ضبط السر، تُضاف x-secret وX-Deskgram-Webhook-Secret وX-Deskgram-Signature. التوقيع يسمح بالتحقق من الجسم، لكن السر نفسه يُرسل أيضًا في ترويسات. استخدم HTTPS ولا تنشر قيمها في السجلات. مثال التحقق في مرجع API.

اختبار الاتصال

يرسل اختبار الحدث webhook.test حتى إلى نقطة معطلة. يفحص اتصال HTTP ومعالجة طلب الاختبار، ولا يبدأ مهمة Telegram.

لا يحتوي الاختبار على task أو lead أو account أو message. يُطبق mapping الحالي؛ الاقتصار على مصادر lead قد ينتج كائنًا فارغًا. يجب أن يدعم المستقبل الاختبارات صراحةً. الرفض لغياب العميل المحتمل قد يكون تحققًا تجاريًا؛ اقرأ الحالة ومحتوى الاستجابة.

النجاح فقط HTTP 200–299. الرمز 302 ليس نجاحًا؛ لا تُتبع التحويلات. ضع عنوان الاستقبال النهائي.

HTTP 200 يدل على القبول بطبقة HTTP، ولا يثبت إنشاء عميل محتمل أو رسالة. افحص استجابة CRM والسجل الفعلي فيه.

السجل وإعادة المحاولة

يعرض السجل أحدث عمليات التسليم. اختر المستقبل والحالة ثم حدّث القائمة.

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

المحاولات التلقائية

حتى ثلاث محاولات لكل تسليم، بفاصل يقارب ثانيتين ثم أربع ثوانٍ قبل الثانية والثالثة، دون احتساب انتظار الشبكة. تُعاد أيضًا استجابات 4xx و5xx.

تحافظ كلها على X-Deskgram-Delivery-Id نفسه. ينبغي أن يزيل المستقبل التكرار ضمن نطاق المرسل حتى لا يعيد إجراءً نُفذ بالفعل.

إعادة يدوية

1. افتح تسليمًا فاشلًا.
2. صحح URL أو السر أو الحقول عند الحاجة.
3. احفظ الإعدادات.
4. ارجع للسجل واضغط إعادة محاولة التسليم.
5. افحص السجل الجديد والنتيجة الخارجية.

تتوفر فقط للحالة error. تنشئ تسليمًا جديدًا بمعرّف جديد وتترك الأصل.

تستخدم السجلات الجديدة الحدث الأصلي وmapping الحالي. القديمة التي لا تملك الأصل تعيد JSON المحفوظ دون تحويل ثانٍ. يُستخدم URL والسر والترويسات الحالية في الحالتين.

إذا عالج المستقبل الطلب وضاعت الاستجابة، قد تكرر المحاولة الإجراء. لأن المحاولة اليدوية تغير المعرّف، يحتاج CRM إلى إزالة تكرار على مستوى العمل أيضًا.

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

سيناريوهات عملية

إرسال الرسائل إلى CRM

اختر spampm والأحداث message.sent وmessage.failed وlead.replyreceived. لقناة متوافقة استخدم JSON القياسي وسر القناة. أرسل لحساب اختبار تملكه، ثم رد وافحص عمليتي التسليم والسجلين. هذا يختبر الأحداث الحقيقية منفصلة عن فحص الاتصال.

أتمتة بعد انتهاء مهمة

اختر task.completed والوحدة المطلوبة، مع JSON القياسي أو النتيجة المختصرة. أضف task.failed وtask.cancelled إذا كان المسار يعالج الفشل والتوقف أيضًا.

تطبيقك الخاص

اضبط العنوان والحقول والسر. استقبل POST JSON، تحقق من التوقيع، احفظ أو ضع في طابور موثوق، ثم أعد 2xx. نفذ الأعمال الطويلة لاحقًا. راجع عقد HTTP وHMAC.

معالجة المشكلات

الإدارة بواسطة وكيل ذكاء اصطناعي

تحتاج أدوات MCP إلى إذن في الإعدادات ← MCP. الفروق:

• الإنشاء افتراضيًا dry-run، والنقطة الجديدة معطلة.
• HTTPS عام فقط، دون localhost أو LAN أو HTTP.
• فعل حقيقي مناسب للإنشاء أو التعديل أو التفعيل أو الاختبار أو الإعادة يحفظ قواعد الشبكة المحمية للإرسال اللاحق.
• تعديل الواجهة أو إيقاف MCP لا يزيل القواعد.
• القراءة لا تكشف السر المحفوظ أو قيم headers أو الأجسام الكاملة.

للقراءة وdry-run والتعطيل والحذف قواعد منفصلة، ولا تُدخل هذه العمليات وحدها نقطة قديمة في السياسة الجديدة. راجع MCP.

القيود

• هي إشعارات صادرة، وليست تنفيذًا عن بعد لأي إجراء أو قناة أوامر CRM دائمة.
• السجل ليس طابورًا تلقائيًا مقاومًا لإعادة التشغيل؛ الإرسال الذي قُطع بالإغلاق لا يُستأنف تلقائيًا.
• POST JSON فقط، دون GET أو multipart أو نص حر للجسم.
• لا يوجد ضمان لتسليم مرة واحدة أو ترتيب أحداث مختلفة.
• النتائج تختلف بحسب الوحدة، وقد تغيب بعض الحقول.
• قد تُرسل جهات اتصال ونصوص ومعاملات مهام ونتائج إلى الخارج؛ اختر المستقبل والحقول على هذا الأساس.

المتابعة

تنزيل Deskgram 2

الخطوة التالية

• كل الأدلة