الرسائل والأزرار

يُجمّع إجراء «إرسال رسالة» ردّ البوت من بلوكات ويضيف إليه أزراراً مضمّنة وقائمة رئيسية وخطوات حوار. هذا أغنى إجراء في المحرر — ومنه تُوصَّل بدلالات الاستبدال والمعاملات المرفقة بالأزرار.

بلوكات الرسالة

الرسالة هي سلسلة من البلوكات (زر إضافة بلوك):

  • نص — نص منسّق (حتى 4096 حرفاً) مع بدلالات استبدال وأزرار.
  • صورة — صورة مع تعليق.
  • ملف — مستند مع تعليق.
  • تأخير — وقفة بالثواني قبل البلوك التالي.
  • ذكاء اصطناعي — رد يُولّده النموذج وفق موجّه (prompt).
  • تفاعل — استدعاء تفاعل آخر (مع انتظار معالجته أو بدونه).

يمكن سحب البلوكات وإعادة ترتيبها. وضع العرض — «بالترتيب» أو «عشوائياً» (للردود المتنوعة). يمكن إبقاء القائمة الرئيسية كما هي أو تعيين قائمة جديدة أو إخفاؤها.

خيارات البلوك

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

الأزرار المضمّنة

تُضبط الأزرار في البلوك (نص الزر + النوع):

  • نص (callback) — زر تعالج البوت نقره.
  • رابط — يفتح URL.
  • تطبيق ويب — يفتح Telegram Mini App. انظر Mini App.
  • استدعاء تفاعل — يُشغّل تفاعلاً آخر عند النقر.
  • استقبال دفع وإشعار — مصنّفان كـ«قريباً».

نمط الزر — عادي أو أزرق (Primary) أو أخضر (Success) أو أحمر (Danger). علم «للاستخدام مرة واحدة» يُعطّل الزر بعد النقر.

السلوك عند النقر

للأزرار من نوع callback، يمكن ضبط ما يحدث عند النقر: استبدال نص الزر، استبدال الرسالة (بنص أو بمحتوى تفاعل مرتبط)، حذف الرسالة، تخطي answerCallbackQuery. يمكن للنقر أيضاً تعيين تسميات وضبط معاملات.

معاملات الزر (Carry)

يُرفق بلوك «Carry — لقطة بيانات في لحظة النقر» بالزر مجموعة قيم مسجّلة في لحظة الإرسال. عند النقر تنتقل هذه القيم إلى السياق — وهكذا يحمل كل زر معاملاته الخاصة (per-invocation) حتى لو كانت الأزرار متعددة. يُحدَّد عمر الـpayload بالثواني. هذا هو أساس سيناريوهات «اختر منتجاً → أتمّ طلبه تحديداً».

الأزرار الديناميكية

يُحوّل بلوك «أزرار ديناميكية من قائمة» مصفوفة من ctx إلى أزرار — زر لكل عنصر. يمكن ضبط: مفتاح القائمة في ctx، اسم مستعار للعنصر، عدد الأزرار في الصف، قالب الزر (يدعم {{alias.field}}). يمكن بذلك بناء كتالوجات وقوائم سجلات وقوائم من بيانات المجموعة. التفاصيل — الأزرار الديناميكية والمعاملات.

الرد المتوقع (خطوات الحوار)

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

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

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

التحقق من النص

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

حفظ الرد

يمكن حفظ رد المستخدم في معامل — فيصبح متاحاً في بدلالات الاستبدال كـ{{param.key}} وفي الشروط. وهكذا تُبني خطوات الحوار ملفاً مصغّراً للعميل.

الأخطاء والتذكير والمهلة

  • رسالة عند خطأ في التحقق — ما يُعرض عند فشل الرد في التحقق.
  • تذكير — ما يُرسل إذا صمت المستخدم.
  • إلغاء الانتظار عند انتهاء المهلة — المدة قبل التوقف عن الانتظار؛ عند انتهاء المهلة يمكن تشغيل تفاعل (مثل إنهاء الاستطلاع بلطف). يظهر هذا التفاعل في الصلات كـ«مهلة الانتظار»، فيما يظهر التفاعل مع الرد ذاته كـ«الرد المتوقع».

بدلالات الاستبدال

يُدرج زر «بدلالات الاستبدال» متغيرات: بيانات المُرسل ({{first_name}} و{{username}} و{{user_id}}), والحدث ({{text}} و{{chat_id}} و{{datetime}}) والمعاملات ({{param.key}}). القائمة الكاملة والصيغ — بدلالات الاستبدال والصيغ.

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