جایگزینی‌ها و فرمول‌ها

جایگزینی‌ها متغیرهایی به شکل {{...}} هستند که هنگام فعال شدن واکنش، در متون پیام‌ها، فیلدهای اقدامات و قالب‌های دکمه‌ها جایگزین می‌شوند. جایگزینی‌های ناشناخته همانطور که هستند باقی می‌مانند. علاوه بر متغیرها، فرمول‌ها برای محاسبات وجود دارند. دکمه «جایگزینی‌ها» در ویرایشگر پیام کمک به درج متغیر می‌کند.

داده‌های فرستنده

  • {{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.کلید}} (همچنین {{params.کلید}} یا {{recipient.کلید}}) — مقدار پارامتر مشترک. پارامترها با اقدامات «تغییر پارامترها»، «ذخیره پیام» و پاسخ‌های مکالمه پر می‌شوند.

زمینه اجرا (ctx)

  • {{ctx.کلید}} (همچنین {{context.کلید}}) — مقادیر موقت اجرای فعلی: داده‌های webhook ورودی، نتایج اقدامات (درخواست وب، درخواست به منبع، هوش مصنوعی)، داده‌های بازیابی‌شده دکمه (Carry)، عناصر حلقه.
  • در حلقه روی فهرست عنصر با نام مستعار خود در دسترس است، مثلاً {{item.name}}.

فرمول‌ها

ساختار {{= عبارت}} عبارت را مستقیماً در متن محاسبه می‌کند. همان موتور در اقدام «محاسبه» و در شرط‌های جدول تصمیم کار می‌کند. در عبارات می‌توان به پارامترها و مقادیر ctx با نام ارجاع داد، از حساب، مقایسه‌ها، منطق و ده‌ها تابع مانند ROUND، IF، CONCAT و غیره استفاده کرد.

مثال: {{= ROUND(param.total * 0.9) }} — تخفیف ۱۰٪ از مبلغ پارامتر.

نحو کامل و فهرست توابع — در بخش فرمول‌ها.

HTML در جایگزینی‌ها

پیام‌ها با نشانه‌گذاری HTML ارسال می‌شوند. برای اینکه مقدار جایگزین‌شده چیدمان را خراب نکند (مثلاً وقتی نام کاربر شامل < است)، مقادیر جایگزین‌شده به‌طور پیش‌فرض escape می‌شوند: نویسه‌های HTML به متن امن تبدیل می‌شوند. تگ‌هایی که مستقیماً در متن واکنش می‌نویسید (<b>، <a>، …) دست‌نخورده باقی می‌مانند.

اگر خود مقدار شامل نشانه‌گذاری آماده باشد (مثلاً اعلانی که در یک پارامتر با <b>...</b> ذخیره شده) و بخواهید آن را همان‌طور که هست درج کنید، پیشوند & را پیش از جایگزینی قرار دهید:

  • {{& key}} — درج خام برای جایگزینی‌های {{...}}.
  • {&user:key}، {&recipient:key}، {&global:key} — درج خام برای جایگزینی‌های namespace.

پیشوند & فقط برای همان جایگزینی مشخص، escape را غیرفعال می‌کند — شما مسئولیت اعتماد به منبع مقدار را می‌پذیرید. بهتر است توکن‌هایی که مشترک کنترل می‌کند ({{first_name}}، …) escape‌شده باقی بمانند.

هنگام وارد کردن بات‌ها از سازنده‌های دیگر، جایگزینی‌های namespace یعنی {user:…}/{recipient:…}/{global:…} به‌طور خودکار به شکل خام {&…} منتقل می‌شوند — آن‌ها معمولاً مقادیری با نشانه‌گذاری آماده دارند، همان‌طور که در سازنده اصلی کار می‌کرد.

نکته مهم درباره فرمت

جایگزینی‌های {{...}} در متون، زیرنویس‌ها، بدنه درخواست‌ها و قالب‌های دکمه‌ها کار می‌کنند. به پارامترها و کلیدهای ctx نام‌های کوتاه و لاتین بدهید (email، total، order_id) — درج آن‌ها راحت‌تر است.

مرحله بعد