پایگاه دانش GetMyBot

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

پاسخ بات را با متن، عکس، دکمه و پرسش‌هایی که پاسخشان ذخیره می‌شود بسازید.

در این صفحه

برای فرستادن متن، عکس و دکمهٔ «انتخاب»، اقدام ارسال پیام را اضافه کنید. پاسخ از بخش‌های جداگانه‌ای به نام بلوک ساخته می‌شود؛ مثلاً عکس کالا و پس از آن توضیحی با دکمه‌های زیر پیام. این دکمه‌ها را دکمه‌های inline نیز می‌گویند.

در همان اقدام می‌توانید پرسشی بفرستید و منتظر پاسخ بمانید، مثلاً شمارهٔ تلفن را بپرسید و در پروندهٔ مشتری ذخیره کنید. در ادامه، بلوک‌ها، دکمه‌ها و پرسش‌ها توضیح داده می‌شوند.

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

افزودن بلوک را بزنید و محتوای آن را انتخاب کنید. می‌توانید متن خوش‌آمدگویی، عکس و فایل برنامهٔ کلاس را در یک پاسخ کنار هم بگذارید.

  • متن: متن قالب‌بندی‌شده تا ۴۰۹۶ نویسه، همراه جایگزینی و دکمه.
  • عکس: تصویر با زیرنویس.
  • فایل: سند با زیرنویس.
  • Voice (پیام صوتی): فایل OGG/OPUS، MP3 یا M4A تا ۵۰ مگابایت، که Telegram با sendVoice به‌صورت پیام صوتی نشان می‌دهد.
  • GIF: انیمیشن یا MP4 بی‌صدا تا ۵۰ مگابایت (sendAnimation).
  • Video note (ویدئوی دایره‌ای): MP4 مربعی تا ۶۰ ثانیه، بدون زیرنویس (sendVideoNote). فایل کتابخانهٔ رسانه در هر ارسال دوباره بارگذاری می‌شود؛ Telegram در sendVoice، sendAnimation یا sendVideoNote، file_id به‌دست‌آمده از روش دیگر را نمی‌پذیرد.
  • Carousel (کارت‌های عکس): ۲ تا ۱۰ کارت، هر کدام با عکس، زیرنویس و دکمه‌های خودش. در Telegram، کارت‌ها با «‹ ›» در یک پیام از راه editMessageMedia ورق می‌خورند فقط اگر برای تک‌تک عکس‌ها file_id قابل‌استفاده موجود باشد، چه در خود کارت تعیین شده باشد چه از کتابخانهٔ رسانه گرفته شود. اگر حتی یکی از عکس‌ها چنین ID نداشته باشد، همهٔ کارت‌ها پیام عکس جداگانه می‌شوند. در کانال‌های دیگر مانند VK نیز جداگانه فرستاده می‌شوند. زیرنویس و دکمهٔ هر کارت حفظ می‌شود.
  • تأخیر: مکث بر حسب ثانیه پیش از بلوک بعدی.
  • هوش مصنوعی: پاسخ ساخته‌شده توسط مدل از روی prompt.
  • واکنش: فراخوانی واکنش دیگر، در صورت نیاز با انتظار برای پایان آن.

پیام صوتی، GIF، ویدئوی دایره‌ای و کارت‌های عکس مانند دیگر بلوک‌ها در واکنش کار می‌کنند و در ارسال سریع واکنش نیز استفاده می‌شوند؛ ارسال همگانی.

بلوک‌ها را می‌توان جابه‌جا کرد. حالت نمایش به‌ترتیب همهٔ بلوک‌ها را پشت سر هم می‌فرستد؛ تصادفی برای پاسخ‌های متنوع یک بلوک را انتخاب می‌کند. منوی اصلی بات را می‌توانید بدون تغییر بگذارید، تنظیم یا پنهان کنید.

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

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

دکمه‌های inline

برای هر بلوک، متن دکمه و نوع دکمه را انتخاب کنید:

  • متن: نوشتهٔ دکمه را مانند پاسخ کاربر می‌فرستد. در Telegram و VK، دکمه روی صفحه‌کلید پاسخ قرار می‌گیرد و می‌تواند به یک پرسش پاسخ دهد یا واکنش متنی را آغاز کند. WhatsApp، Instagram، Messenger و ابزارک وب، دکمهٔ پاسخ بدون صفحه‌کلید دائمی نشان می‌دهند.
  • لینک: URL را باز می‌کند.
  • برنامه وب: Telegram Mini App را باز می‌کند. Mini App.
  • واکنش: فشار دکمه واکنش دیگری را اجرا می‌کند.
  • Inline query: متن «@bot query» را در کادر نوشتنِ چت فعلی می‌گذارد یا از فرد می‌خواهد چت دیگری انتخاب کند (switch_inline_query / switch_inline_query_current_chat). فقط در Telegram، پس از روشن کردن حالت inline در @BotFather با /setinline، کار می‌کند. GetMyBot به این درخواست‌ها پاسخ نمی‌دهد (answerInlineQuery پیاده‌سازی نشده است)، پس دکمه فقط متن پرس‌وجو را آماده می‌کند و جست‌وجو انجام نمی‌دهد.
  • Prefilled text: پیوند https://t.me/<bot>?text=… چت بات را باز می‌کند و متن را در کادر نوشتن می‌گذارد، بدون فرستادن پیام (prefill).
  • Payment link: URL ضروری پرداخت را باز می‌کند. ابتدا پرداخت را با اقدام صدور صورت‌حساب بسازید. این صفحهٔ پرداخت بیرونی است، نه صورتحساب بومی Telegram.
  • اعلان: پس از فشار، متن کوتاهی نشان می‌دهد، واکنش را اجرا نمی‌کند و دادهٔ Carry دکمه را نمی‌فرستد. در Telegram، اعلان کوتاه یا پنجره تا ۲۰۰ نویسه و در VK، نوار کوتاه بدون پنجره تا ۹۰ نویسه است.

متن یا متن آماده

کار موردنظرنوع و تنظیمنتیجهٔ فشار
انتخاب «بله» در پرسشنامهمتن، نوشتهٔ «بله»؛ پیام باید منتظر پاسخ باشد«بله» به گام گفت‌وگو می‌رسد
آماده کردن درخواستPrefilled text، نوشتهٔ «نوشتن»، متن آمادهٔ «می‌خواهم سفارش بدهم»پیش‌نویس در کادر چت ظاهر می‌شود؛ فرد خودش آن را ویرایش و ارسال می‌کند

نوشتهٔ روی دکمه با متن آماده دو کادر متفاوت‌اند. متن آماده خودش پیام نمی‌فرستد و واکنشی را اجرا نمی‌کند.

دکمهٔ واکنش رویداد مستقلی به بات می‌فرستد که از نظر فنی callback نام دارد. Inline query و Prefilled text فقط در برنامهٔ Telegram عمل می‌کنند و callback ندارند؛ پس نه answerCallbackQuery دارند و نه Carry را منتقل می‌کنند.

نماد و رنگ دکمه

می‌توانید پیش از نوشتهٔ دکمه، ایموجی ویژهٔ Premium بگذارید. در Premium emoji ID، شناسهٔ آن (icon_custom_emoji_id) را به‌صورت عدد صحیح مثبت ۶۴ بیتی وارد کنید. مثلاً 007 به‌صورت 7 خوانده می‌شود. حرف، صفر، عدد منفی یا عدد بیش‌ازحد بزرگ کنار گذاشته می‌شود و دکمه بدون نماد ذخیره می‌گردد.

Telegram این نماد را فقط برای بات‌هایی با حق لازم نشان می‌دهد: نام کاربری اضافه از Fragment یا Telegram Premium مالک هنگام ارسال مستقیم به چت خصوصی یا گروه. در موارد دیگر، Telegram نماد را نادیده می‌گیرد و ایموجی عادی جای آن نمی‌گذارد.

سبک دکمه رنگ را تعیین می‌کند: معمولی بدون رنگ، اصلی آبی، موفقیت سبز و خطرناک قرمز. نام فنی فیلد style است.

یک‌بار مصرف (سوزاندن پس از فشردن) (single_use) اجازه می‌دهد دادهٔ ذخیره‌شدهٔ دکمه فقط یک بار استفاده شود، مثلاً برای تأیید انتخاب. تغییر نوشتهٔ دکمه یا حذف پیام جداگانه در بخش رفتار پس از فشار تنظیم می‌شود.

پرچم‌های دکمه

پرچم، گزینه‌ای است که روشن یا خاموش می‌شود. در ویرایشگر:

  • از ردیف جدید: دکمه را به ردیف بعد می‌برد.
  • کشیدن به تمام عرض: دکمه در ردیف جدا قرار می‌گیرد و دکمهٔ بعدی نیز از ردیف تازه شروع می‌شود.

نمای تقریبی؛ براکت‌ها دکمه‌اند:

یک ردیف:        [فهرست] [کمک]

ردیف تازه:      [فهرست]
                 [کمک]

تمام عرض:       [         کمک         ]

ردیف و رنگ در Telegram و VK در دسترس‌اند و هنگام باز کردن دوباره و ویرایش حفظ می‌شوند. ایموجی Premium فقط در اتصال سازگار Telegram کار می‌کند. گزینهٔ عملی برای باز شدن داخل Telegram وجود ندارد؛ Bot API اجازهٔ کنترل آن را با چنین پرچمی نمی‌دهد.

محدودیت‌های کانال‌ها

برای بلوک یا دکمه، اتصال موردنظر را انتخاب کنید. برای همهٔ کانال‌ها، ویرایشگر فقط امکانات مشترک را مجاز می‌داند؛ نوع پشتیبانی‌نشده ذخیره نمی‌شود.

  • Telegram: URL، Mini App، واکنش، اعلان یا پنجره، ردیف‌ها، رنگ‌ها و custom emoji در صورت داشتن حق لازم.
  • VK: URL، واکنش، اعلان کوتاه، ردیف و رنگ. VK Mini App و VK Pay فقط با اتصال سازگار VK.
  • WhatsApp: یک دکمهٔ URL از نوع CTA، بدون دکمهٔ دیگر در همان پیام. دکمه‌های پاسخ تا ۳ مورد معمولی و از ۴ تا ۱۰ مورد به‌صورت فهرست نشان داده می‌شوند؛ نوشته حداکثر ۲۰ نویسه. ردیف، رنگ، Mini App و اعلان ندارد.
  • Instagram / Messenger: اتصال فعلی فقط دکمه‌های پاسخ سریع با نوشتهٔ حداکثر ۲۰ نویسه می‌فرستد. URL، Mini App، اعلان، ردیف و رنگ پشتیبانی نمی‌شوند.
  • ابزارک وب: URL و دکمهٔ پاسخ، بدون ردیف، رنگ و اعلان.
  • Email: پیوند، از جمله پیوند پرداخت؛ بدون دکمهٔ پاسخ و اعلان.

برای دکمه‌هایی که از فهرست ساخته می‌شوند، تعداد ستون‌ها فقط در کانال‌های دارای ردیف قابل تعیین است. در بقیه، خود کانال چیدمان را انتخاب می‌کند. تعداد دکمه‌ها و طول نوشته هنگام ارسال بررسی می‌شوند.

رفتار پس از فشار

برای دکمه‌هایی که فشار را به بات می‌فرستند، اگر کانال پشتیبانی کند، می‌توانید پیام را جایگزین کنید، با متن یا محتوای واکنش دیگر، پیام را حذف کنید، برچسب بگذارید یا پارامتر ذخیره کنید. تغییر نوشتهٔ خود دکمه پس از فشار فقط در Telegram کار می‌کند، مثلاً «ثبت‌نام» به «انتخاب شد» بدل شود. ویرایش پیام در VK شامل تغییر نوشتهٔ دکمه نیست.

Telegram منتظر تأیید فشار دکمه با answerCallbackQuery می‌ماند. GetMyBot معمولاً خودش آن را می‌فرستد و علامت بارگذاری دکمه را برمی‌دارد. نادیده گرفتن answerCallbackQuery این تأیید را خاموش می‌کند.

در Text on press (notification) برای دکمهٔ واکنش می‌توانید تأیید کوتاهی مانند «کلاس انتخاب شد» بنویسید. سقف در Telegram ۲۰۰ و در VK ۹۰ نویسه است؛ جایگزینی‌ها کار می‌کنند. Telegram آن را کوتاه‌مدت بالای چت نشان می‌دهد. Show as a popup (alert) فقط در Telegram در دسترس است و با show_alert در answerCallbackQuery پنجره باز می‌کند. اگر متن خالی باشد، بات فقط علامت بارگذاری را حذف می‌کند. با نادیده گرفتن answerCallbackQuery نه متن و نه پنجره فرستاده می‌شود.

داده‌های دکمه (Carry)

Carry به دکمه کمک می‌کند بداند به کدام مورد مربوط است. مثلاً روی پالتو و لباس هر دو دکمهٔ «خرید» هست؛ برای اولی product_id=101 و برای دومی product_id=102 بگذارید. با فشار دکمهٔ لباس، واکنش بعدی {{ctx.product_id}} را با مقدار 102 دریافت می‌کند.

نام این بخش در ویرایشگر داده‌های ارسالی هنگام کلیک است. کلید نام مقدار را تعیین می‌کند و مقدار می‌تواند عدد، متن یا جایگزینی باشد. بات داده را هنگام فرستادن پیام ثبت می‌کند و هنگام فشار در دادهٔ موقت واکنش (ctx) می‌گذارد. هر دکمه دادهٔ خودش را دارد.

مدت اعتبار داده‌های دکمه، ثانیه (ttl_seconds یا TTL): 3600 یک ساعت است و 0 مقدار پیش‌فرض ۳۰ روز را می‌گیرد. پس از پایان مدت، داده در دسترس نیست. یک‌بار مصرف (single_use) آن را پس از اولین فشار حذف می‌کند. قیمت ذخیره‌شده با تغییر کاتالوگ به‌روز نمی‌شود؛ پیش از دریافت پول، قیمت روز را با ID کالا دوباره بخوانید.

راهنمای گام‌به‌گام و تفاوت با پارامترهای ماندگار: دکمه‌های پویا و پارامترها.

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

اگر کالاها یا کلاس‌ها در یک فهرست‌اند، دکمه‌ها را دستی نسازید. دکمه‌های پویا از فهرست برای هر عضو یک دکمه می‌سازد. محل فهرست در ctx، نام مستعار یک عضو، تعداد دکمه در هر ردیف و الگوی نوشته را تعیین کنید. مثلاً {{item.name}} نام کالای فعلی را می‌گذارد. دکمه‌های پویا و پارامترها.

ایموجی Premium در متن

دکمهٔ قالب‌بندی Premium emoji در بلوک متن، <tg-emoji emoji-id="…">🙂</tg-emoji> را می‌گذارد. دارندهٔ Telegram Premium ایموجی سفارشی را می‌بیند؛ بقیه همان ایموجی معمولی داخل تگ را می‌بینند. در قالب HTML و Markdown بلوک کار می‌کند. ID ایموجی عددی تا ۳۲ رقم است؛ می‌توانید آن را با getCustomEmojiStickers یا فرستادن پیام دارای ایموجی به باتی مانند @idstickerbot پیدا کنید.

پیوند بات و متن آماده

پیوند t.me/<bot>?start=<param> در Telegram دستور /start <param> را اجرا می‌کند. نمی‌توان با این پیوند چت را همراه پارامتر باز کرد اما /start را اجرا نکرد. گزینه‌های موجود:

  • /start بی‌صدا: در واکنش با ماشهٔ دستور /start و مقدار لازم در برچسب پیوند شروع، می‌توانید اقدام ارسال پیام را بدون بلوک بگذارید. پاسخ آشکاری به /start فرستاده نمی‌شود، اما مقدار برچسب در زمینهٔ رویداد هست و همان واکنش می‌تواند در شرط‌ها یا اقدام‌های دیگر از آن استفاده کند.
  • متن آماده: پیوند https://t.me/<bot>?text=<text>، با دکمهٔ Prefilled text یا دکمهٔ پیوند عادی، چت را باز و متن را در کادر نوشتن می‌گذارد، بدون ارسال. /start اجرا نمی‌شود؛ خود فرد پیام را می‌فرستد.
  • پیام خودکار به نام کاربر هنگام باز کردن پیوند با Bot API ممکن نیست؛ بات نمی‌تواند از طرف فرد پیام بفرستد. نزدیک‌ترین راه، deep link با ?start= و واکنشی است که خودش به نام بات پاسخ می‌دهد.

پاسخ مورد انتظار (گام‌های گفت‌وگو)

بلوک متن می‌تواند منتظر پاسخ کاربر بماند. پیام به گامی از گفت‌وگو بدل می‌شود و مسیر تا رسیدن پاسخ مکث می‌کند. چند گام پشت سر هم یک فرم پرسش و پاسخ در خود چت می‌سازند.

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

بات می‌تواند نوع مشخصی را بخواهد: متن، انتخاب از گزینه‌ها با دکمه، عکس، ویدئو، ویدئوی دایره‌ای، صوت، سند، پیام صوتی، موقعیت، مخاطب، تقویم یا تاس. اگر نوع دیگری فرستاده شود، پاسخ برای آن گام مناسب نیست.

بررسی متن

برای پاسخ متنی می‌توانید تلفن، ایمیل، پیوند، تاریخ، زمان یا بررسی با فرمول را بخواهید. مثلاً اگر تلفن می‌خواهید، متن دلخواه پذیرفته نمی‌شود و بات خطا نشان می‌دهد. فرمول پیشرفته برای پاسخ درست باید متن خالی و برای پاسخ نادرست متن خطا برگرداند.

ذخیرهٔ پاسخ

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

خطا، یادآوری و پایان انتظار

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

خروج از گام با دستور

/cancel یا واژهٔ روسی «отмена» انتظار را لغو می‌کند و پاسخ «Отменено.» را می‌فرستد، مگر آنکه واکنش لغو تنظیم شده باشد. دستورهای دیگر به‌طور پیش‌فرض مانند پاسخ عادی بررسی می‌شوند تا گام تا دریافت پاسخ مناسب باقی بماند. اگر Bot commands (e.g. /start) end the wait (escape_on_command) را روشن کنید، هر دستور، مثلاً /start وسط فرم، بی‌صدا انتظار را قطع می‌کند و به شکل عادی اجرا می‌شود.

جایگزینی‌ها

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

دکمهٔ منوی بات

اقدام Menu button منوی معمولی بات، دستورها یا دکمهٔ Mini App با متن و URL را انتخاب می‌کند. می‌توانید آن را فقط برای چت فعلی یا به‌صورت تنظیم عمومی بات بگذارید، مثلاً Mini App اختصاصی برای یک مشتری. دسترس‌پذیری به امکانات کانال بستگی دارد.

مراحل بعدی