پیام‌ها و دکمه‌ها

اقدام «ارسال پیام» پاسخ بات را از بلوک‌ها می‌سازد و آن را با دکمه‌های inline، منوی اصلی و مراحل مکالمه تکمیل می‌کند. این غنی‌ترین اقدام سازنده است — اینجا جایگزینی‌ها و پارامترهای ارجاعی دکمه‌ها نیز اتصال می‌یابند.

بلوک‌های پیام

پیام یک دنباله از بلوک‌ها است (دکمه افزودن بلوک):

  • متن — متن فرمت‌شده (تا ۴۰۹۶ کاراکتر) با جایگزینی‌ها و دکمه‌ها.
  • عکس — تصویر با زیرنویس.
  • فایل — سند با زیرنویس.
  • تأخیر — مکث به ثانیه قبل از بلوک بعدی.
  • هوش مصنوعی — پاسخ تولیدشده توسط مدل بر اساس پرامپت.
  • واکنش — فراخوانی واکنش دیگر (به اختیار با انتظار برای پردازش آن).

بلوک‌ها قابل کشیدن و رها کردن هستند. حالت نمایش بلوک‌ها — «به ترتیب» یا «تصادفی» (برای پاسخ‌های متنوع). منوی اصلی بات می‌تواند بدون تغییر باقی بماند، تنظیم شود یا پنهان شود.

گزینه‌های بلوک

بلوک‌های متنی و رسانه‌ای پرچم دارند: پین‌کردن، بی‌صدا، محافظت از فوروارد، اسپویلر، بدون پیش‌نمایش لینک‌ها، حذف خودکار پس از N ثانیه.

دکمه‌های Inline

دکمه‌ها در بلوک تنظیم می‌شوند (متن دکمه + نوع):

  • متن (callback) — دکمه با پردازش ضربه در سمت بات.
  • لینک — URL را باز می‌کند.
  • وب‌اپلیکیشن — Telegram Mini App را باز می‌کند. ببینید Mini App.
  • فراخوانی واکنش — ضربه، واکنش دیگری را اجرا می‌کند.
  • دریافت پرداخت و اعلان — به عنوان «به زودی» علامت‌گذاری شده‌اند.

استایل دکمه — معمولی، آبی (Primary)، سبز (Success) یا قرمز (Danger). پرچم «یک‌بار مصرف» دکمه را پس از ضربه غیرفعال می‌کند.

رفتار هنگام ضربه

برای دکمه‌های callback تنظیم می‌شود که هنگام ضربه چه اتفاقی بیفتد: جایگزینی متن دکمه، جایگزینی پیام (با متن یا محتوای واکنش متصل)، حذف پیام، رد کردن answerCallbackQuery. ضربه همچنین می‌تواند برچسب‌ها بگذارد و پارامترها تنظیم کند.

پارامترها در دکمه (Carry)

بلوک «Carry — عکس‌فوری داده‌ها در هنگام ضربه دکمه» مجموعه‌ای از مقادیر ثابت‌شده در لحظه ارسال را به دکمه ضمیمه می‌کند. هنگام ضربه، این مقادیر وارد زمینه می‌شوند — بنابراین هر دکمه پارامترهای خود را دارد (per-invocation)، حتی اگر دکمه‌های زیادی وجود داشته باشد. مدت زمان payload به ثانیه تنظیم می‌شود. این پایه سناریوهای «کالا را انتخاب کن → همان را سفارش بده» است.

دکمه‌های پویا

بلوک «دکمه‌های پویا از فهرست» آرایه‌ای از ctx را به دکمه‌ها تبدیل می‌کند — یک دکمه برای هر عنصر. تنظیم می‌شود: کلید فهرست در ctx، نام مستعار عنصر، تعداد دکمه‌ها در ردیف و قالب دکمه (از {{alias.فیلد}} پشتیبانی می‌کند). بدین ترتیب کاتالوگ‌ها، فهرست رکوردها و منوهای داده از مجموعه ساخته می‌شوند. جزئیات بیشتر — دکمه‌های پویا و پارامترها.

پاسخ منتظر (مراحل مکالمه)

بلوک متنی می‌تواند منتظر پاسخ کاربر بماند — این پیام را به یک مرحله مکالمه تبدیل می‌کند و سناریو را تا پاسخ متوقف می‌کند. چند مرحله پشت سر هم یک پرسشنامه یا راهنما مستقیماً در چت تشکیل می‌دهند.

نوع محتوای انتظاری

بات می‌تواند منتظر نوع خاصی از پاسخ باشد: متن، انتخاب از گزینه‌ها (دکمه‌های گزینه‌ای)، عکس، ویدیو، ویدیو-یادداشت، صوت، سند، صوتی، موقعیت، مخاطب، تقویم یا تاس. اگر کاربر نوع اشتباهی ارسال کند، مرحله پاسخ را نامناسب تلقی می‌کند.

بررسی متن

برای پاسخ متنی می‌توان بررسی فرمت فعال کرد: تلفن، ایمیل، لینک، تاریخ، زمان یا تطابق با فرمول (عبارت منظم). پاسخی که بررسی را رد می‌کند رد می‌شود و بات پیام خطا نشان می‌دهد.

ذخیره پاسخ

پاسخ کاربر را می‌توان در پارامتر ذخیره کرد — پس از آن به عنوان {{param.کلید}} در جایگزینی‌ها و شرط‌ها در دسترس است. به این ترتیب مراحل مکالمه پروفایل کوچک مشتری را پر می‌کنند.

خطاها، یادآوری و تایم‌اوت

  • پیام هنگام خطای بررسی — چه چیزی نمایش دهد اگر پاسخ بررسی را رد کند.
  • یادآوری — چه چیزی ارسال شود اگر کاربر سکوت کند.
  • لغو انتظار بر اساس تایم‌اوت — بعد از چه مدت انتظار متوقف شود؛ هنگام تایم‌اوت می‌توان واکنشی اجرا کرد (مثلاً پرسشنامه را به آرامی خاتمه داد). این واکنش در ارتباطات به عنوان «تایم‌اوت انتظار» دیده می‌شود، و واکنش به خود پاسخ — به عنوان «پاسخ انتظاری».

جایگزینی‌ها

دکمه «جایگزینی‌ها» متغیرها را درج می‌کند: داده‌های فرستنده ({{first_name}}، {{username}}، {{user_id}}، رویدادها ({{text}}، {{chat_id}}، {{datetime}}) و پارامترها ({{param.کلید}}). فهرست کامل و فرمول‌ها — جایگزینی‌ها و فرمول‌ها.

مرحله بعد