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

عقدة telegram

عقدة telegram توفر تكاملًا مع واجهة برمجة تطبيقات Telegram Bot. من خلالها يمكن للتدفق إرسال رسائل إلى الدردشات والقنوات، وعرض الأزرار المدمجة، ومعالجة ضغطات الأزرار، وعرض إشعارات منبثقة للمستخدم.

إعدادات عقدة telegram​

نافذة "Node Information" لعقدة telegram مع الحقول "bot_token" و"chat_id" و"tg_text" و"parse_mode" و"reply_markup" وزر "Submit"

في العناوين أدناه — تسميات الحقول في نموذج العقدة، وفي الأقواس — المفاتيح التي يتم حفظ القيم تحتها في مخطط JSON.

1. رمز البوت (botToken)​

رمز البوت الخاص بك في Telegram، الذي تم الحصول عليه من @BotFather.

يدعم Mustache — يمكن تخزين الرمز في متغير التدفق (flow) واستبداله عبر {{المتغير}}.

مثال:

{{flow.telegramToken}}

2. معرف الدردشة (chatId)​

معرف الدردشة أو القناة التي سيتم إرسال الرسالة إليها.

يدعم Mustache. إذا تركت الحقل فارغًا، يتم أخذ القيمة تلقائيًا من msg.payload.message.chat.id — وهذا مفيد عند الرد على رسالة واردة من المستخدم.

مثال:

{{payload.message.chat.id}}

3. نص الرسالة (text)​

نص الرسالة المرسلة.

يدعم Mustache — يمكن إدراج البيانات ديناميكيًا من msg.

مثال:

تم تأكيد طلبك رقم {{payload.orderId}} بنجاح!

4. تنسيق النص (parseMode)​

وضع تنسيق نص الرسالة. الخيارات المتاحة:

  • none (افتراضي) — بدون تنسيق، يتم إرسال النص كما هو.
  • Markdown — Markdown الأساسي من Telegram (v1).
  • MarkdownV2 — نسخة موسعة من Markdown تدعم العناصر مثل السبويلر.
  • HTML — تنسيق HTML (<b>, <i>, <code>, <a> وغيرها).

5. الأزرار (replyMarkup)​

مُنشئ الأزرار المدمجة تحت الرسالة. يتم تنظيم الأزرار في صفوف (Row 1, Row 2, …): يحتوي كل صف على زر واحد أو أكثر. يتم إضافة الزر إلى الصف عبر زر + Button، وصف جديد عبر زر + Row.

لكل زر يتم تحديد:

  • النص — تسمية الزر التي يراها المستخدم.
  • callback_data — القيمة التي ستصل إلى الويب هوك في حقل msg.payload.callback_query.data عند الضغط على الزر. يمكن من خلال هذه القيمة تحديد أي زر تم الضغط عليه، وتوجيه التدفق إلى الفرع المناسب عبر عقدة Switch.

مثال على الهيكل:

Row 1: [تأكيد | callback_data: confirm]  [إلغاء | callback_data: cancel]
Row 2: [المزيد  | callback_data: details]

6. معرف استعلام الاسترجاع (callbackQueryId)​

معرف استعلام الاسترجاع — مطلوب للرد على ضغط الزر المدمج.

يدعم Mustache. إذا تركت الحقل فارغًا، يتم أخذ القيمة تلقائيًا من msg.payload.callback_query.id.

مثال:

{{payload.callback_query.id}}

7. عرض كتنبيه (showAlert)​

مربع اختيار، افتراضيًا مغلق. يحدد نوع الإشعار عند الرد على ضغط الزر:

  • مغلق — يتم عرض نافذة منبثقة قصيرة (تختفي تلقائيًا).
  • مفتوح — يتم عرض نافذة نموذجية مع إشعار يجب على المستخدم إغلاقها يدويًا.

8. نص الإشعار (notificationText)​

نص الإشعار الذي سيظهر عند الرد على ضغط الزر المدمج.

يظهر الحقل في النموذج فقط عندما يكون عرض كتنبيه مفعلًا.
يدعم Mustache.

مثال:

تم قبول اختيارك: {{payload.callback_query.data}}

أمثلة على الاستخدام​

مثال 1: إرسال رسالة حول طلب جديد​

التدفق:

[events: order_created] ---> [telegram]

إعدادات العقدة:

  • رمز البوت: {{flow.telegramToken}}
  • معرف الدردشة: {{flow.adminChatId}}
  • نص الرسالة: طلب جديد رقم {{payload.order.id}} من {{payload.order.userName}}. المبلغ: {{payload.order.totalPrice}} روبل.
  • تنسيق النص: none

النتيجة:
عند إنشاء طلب جديد، سيرسل البوت إشعارًا إلى دردشة المشرف.

مثال 2: رسالة مع أزرار التأكيد​

إعدادات العقدة:

  • معرف الدردشة: {{payload.message.chat.id}}
  • نص الرسالة: هل تريد تأكيد الطلب؟
  • الأزرار: 
    Row 1: [نعم، تأكيد | confirm]  [إلغاء | cancel]

النتيجة:
سيتلقى المستخدم رسالة تحتوي على زرين. الضغط على الزر سيرسل callback_data إلى الويب هوك، حيث يمكن معالجته عبر عقدة Switch.

مثال 3: الرد على ضغط الزر مع إشعار​

التدفق:

[http in] ---> [switch: callback_data == "confirm"] ---> [telegram: الرد مع إشعار]

إعدادات العقدة:

  • معرف استعلام الاسترجاع: (اتركه فارغًا — يتم أخذه من msg.payload.callback_query.id)
  • عرض كتنبيه: مفعل
  • نص الإشعار: تم تأكيد الطلب!

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