کیبوردها و عناصر تعاملی (Keyboards)

کدمیت از انواع کیبوردهای تعاملی برای ساده‌سازی تعامل کاربران با ربات پشتیبانی می‌کند: ۱. کیبوردهای شیشه‌ای (Inline Keyboards): دکمه‌هایی که مستقیماً زیر پیام قرار می‌گیرند و قابلیت اجرای Callback یا باز کردن لینک دارند. ۲. کیبوردهای معمولی (Reply Keyboards): دکمه‌های سفارشی که در پایین صفحه چت به جای کیبورد متن قرار می‌گیرند. ۳. حذف کیبورد (ReplyKeyboardRemove): حذف کیبورد معمولی از صفحه کاربر. ۴. پاسخ اجباری (ForceReply): باز کردن حالت ریپلای اجباری روی پیام برای دریافت ورودی سریع از کاربر.

---

۱. کیبورد شیشه‌ای (InlineKeyboardMarkup)

کیبورد شیشه‌ای به عنوان شیء reply_markup به متدهایی مانند sendMessage ارسال می‌شود.

ساختار دکمه‌های شیشه‌ای (InlineKeyboardButton)

هر دکمه باید دارای فیلد text و دقیقاً یکی از عملکردهای زیر باشد:

فیلد	نوع	توضیحات
text	String	متن نمایشی روی دکمه (حداکثر ۱۲۸ کاراکتر).
callback_data	String	داده‌ای که با کلیک کاربر در قالب callback_query به ربات ارسال می‌شود (۱ تا ۶۴ بایت UTF-8).
url	String	آدرس اینترنتی معتبر (https:// یا http:// یا codemeet://).
switch_inline_query	String	باز کردن حالت اینلاین ربات در چت.

/// note | قوانین و محدودیت‌های چیدمان - حداکثر ۱۰۰ سطر (rows) در هر کیبورد مجاز است. - در هر سطر بین ۱ تا ۸ دکمه می‌تواند قرار گیرد. ///

نمونه کیبورد شیشه‌ای با دکمه‌های چند سطری

{
  "chat_id": "e9b2a1c0-4411-4fa3-9f88-d4508671b122",
  "text": "لطفاً گزینه مورد نظر خود را انتخاب کنید:",
  "reply_markup": {
    "inline_keyboard": [
      [
        {"text": "تأیید سفارش", "callback_data": "order_confirm_102"},
        {"text": "انصراف", "callback_data": "order_cancel_102"}
      ],
      [
        {"text": "مشاهده فاکتور در وب‌سایت", "url": "https://example.com/invoice/102"}
      ]
    ]
  }
}

---

۲. پاسخ به کلیک دکمه‌های شیشه‌ای (answerCallbackQuery)

هنگامی که کاربر روی یک دکمه callback_data دار کلیک می‌کند، یک رویداد callback_query در آپدیت‌های ربات ارسال می‌شود. ربات باید با متد answerCallbackQuery به این رویداد پاسخ دهد تا حالت لودینگ دکمه در اپلیکیشن متوقف شده و در صورت نیاز پیام پاپ‌آپ (Alert) یا نوتیفیکیشن به کاربر نمایش داده شود:

POST https://botapi.codemeet.chat/bot<TOKEN>/answerCallbackQuery

پارامترهای ورودی

پارامتر	نوع	وضعیت	توضیحات
callback_query_id	String	اجباری	شناسه منحصر‌به‌فرد کلیک دریافت شده در update.callback_query.id.
text	String	اختیاری	متن پیام ارسالی به کاربر (حداکثر ۲۰۰ کاراکتر).
show_alert	Boolean	اختیاری	اگر true باشد پیام به صورت پنجره هشدار (Alert Modal) و اگر false باشد به صورت پیام موقت نوار اعلان نمایش داده می‌شود.
url	String	اختیاری	آدرس وب برای باز شدن.
cache_time	Integer	اختیاری	مدت زمان کش کردن پاسخ به ثانیه.

نمونه درخواست

{
  "callback_query_id": "a90f12d83b4c",
  "text": "سفارش شما با موفقیت ثبت شد.",
  "show_alert": true
}

---

۳. کیبورد معمولی چت (ReplyKeyboardMarkup)

این کیبورد دکمه‌هایی را در پایین صفحه چت کاربر جایگزین کیبورد عادی دستگاه می‌کند:

{
  "chat_id": "e9b2a1c0-4411-4fa3-9f88-d4508671b122",
  "text": "منوی اصلی خدمات:",
  "reply_markup": {
    "keyboard": [
      [
        {"text": "پروفایل من"},
        {"text": "پیگیری سفارشات"}
      ],
      [
        {"text": "تنظیمات"},
        {"text": "پشتیبانی آنلاین"}
      ]
    ],
    "resize_keyboard": true,
    "one_time_keyboard": false
  }
}

---

۴. حذف کیبورد معمولی (ReplyKeyboardRemove)

برای مخفی کردن و حذف کیبورد معمولی از صفحه چت کاربر:

{
  "chat_id": "e9b2a1c0-4411-4fa3-9f88-d4508671b122",
  "text": "کیبورد سفارشی مخفی شد.",
  "reply_markup": {
    "remove_keyboard": true
  }
}