بدلالات الاستبدال والصيغ

بدلالات الاستبدال هي متغيرات بصيغة {{...}} تُدرَج في نصوص الرسائل وحقول الإجراءات وقوالب الأزرار عند تشغيل التفاعل. تبقى بدلالات الاستبدال غير المعروفة كما هي. إلى جانب المتغيرات توجد صيغ للحسابات. يُساعد زر «بدلالات الاستبدال» في محرر الرسالة على إدراج المتغير.

بيانات المُرسِل

  • {{first_name}} و{{last_name}} — الاسم الأول والأخير.
  • {{username}} — @username المستخدم.
  • {{user_id}} — معرّف Telegram الرقمي.

بيانات الحدث والمحادثة

  • {{text}} (أو {{received_message}}) — نص الرسالة الواردة.
  • {{message_id}} (أو {{received_message_id}}) — معرّف الرسالة الواردة.
  • {{chat_id}} و{{chat_title}} (أو {{chat_name}}) — المحادثة التي وقع فيها الحدث.
  • {{topic_id}} و{{topic_url}} — الموضوع (للمنتديات).

التاريخ والوقت

  • {{date}} — التاريخ (YYYY-MM-DD)، {{time}} — الوقت (HH:MM)، {{datetime}} — التاريخ والوقت.
  • التنسيق: {{date:DD.MM.YYYY HH:mm}} — الرموز YYYY وYY وMM وDD وHH وmm وss.

معاملات المستخدم

  • {{param.key}} (أو {{params.key}} أو {{recipient.key}}) — قيمة معامل المشترك. تُملأ المعاملات بإجراءات «تعديل المعاملات» و«حفظ الرسالة» والردود في الحوار.

سياق التنفيذ (ctx)

  • {{ctx.key}} (أو {{context.key}}) — القيم المؤقتة للتشغيل الحالي: بيانات webhook الواردة، ونتائج الإجراءات (طلب ويب، استعلام مصدر، ذكاء اصطناعي)، والبيانات المستعادة من الزر (Carry)، وعناصر الحلقة.
  • في حلقة قائمة يكون العنصر متاحاً باسمه المستعار، مثل {{item.name}}.

الصيغ

يحسب التركيب {{= expression}} القيمة مباشرةً في النص. المحرك ذاته يعمل في إجراء «الحساب» وفي شروط جدول القرارات. في التعبيرات يمكن الإشارة إلى المعاملات وقيم ctx بالاسم، واستخدام الحساب والمقارنة والمنطق وعشرات الدوال ذات الأسماء المستعارة بالروسية (مثل ROUND وIF وCONCAT وغيرها).

مثال: {{= ROUND(param.total * 0.9) }} — خصم 10% من المبلغ في المعامل.

البنية الكاملة وقائمة الدوال — في قسم الصيغ.

HTML في بدلالات الاستبدال

تُرسَل الرسائل بتنسيق HTML. لكي لا تُفسد القيمة المُدرَجة تخطيط الرسالة (مثلاً عندما يحتوي اسم المستخدم على <)، تُعالَج القيم المُدرَجة بشكل افتراضي عبر escaping: تتحول رموز HTML إلى نص آمن. أما الوسوم التي تكتبها مباشرةً في نص التفاعل (<b> و<a> …) فتبقى دون تغيير.

إذا كانت القيمة نفسها تحتوي على تنسيق جاهز (مثلاً إعلان محفوظ في معامل يحوي <b>...</b>) وأردت إدراجها كما هي، ضع البادئة & قبل بدلالة الاستبدال:

  • {{& key}} — إدراج خام لبدلالات الاستبدال {{...}}.
  • {&user:key} و{&recipient:key} و{&global:key} — إدراج خام لبدلالات استبدال namespace.

تُعطّل البادئة & المعالجة (escaping) لهذه البدلالة فقط — وأنت تتحمل مسؤولية الثقة بمصدر القيمة. أما الرموز التي يتحكم بها المشترك ({{first_name}} …) فالأفضل تركها معالَجة.

عند استيراد البوتات من منشئات أخرى، تُنقَل بدلالات استبدال namespace {user:…}/{recipient:…}/{global:…} تلقائياً إلى الصيغة الخام {&…} — فهي تحمل عادةً قيماً بتنسيق جاهز، تماماً كما كانت تعمل في المنشئ الأصلي.

ملاحظة حول التنسيق

تعمل بدلالات الاستبدال {{...}} في النصوص والتعليقات وأجسام الطلبات وقوالب الأزرار. أعطِ أسماء المعاملات ومفاتيح ctx أسماء قصيرة بالأحرف اللاتينية (email وtotal وorder_id) — يسهّل ذلك إدراجها.

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