آموزش ساخت پیام شیشه‌ای در روبیکا با پایتون و دکمه تعاملی

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

پاسخ کوتاه: برای ساخت پیام شیشه‌ای در روبیکا با پایتون، ابتدا توکن ربات را از مسیر رسمی دریافت کنید، سپس با یک درخواست JSON متد ارسال پیام را فراخوانی کرده و ساختار دکمه‌ها را به بدنه درخواست اضافه کنید. پس از آن باید رویداد کلیک کاربر را دریافت و بر اساس شناسه هر دکمه پاسخ مناسب ارسال کنید.

نکته مهم: آدرس پایه API، نام متدها، نام فیلدهای درخواست و ساختار دکمه‌ها ممکن است در نسخه‌های مختلف Bot API روبیکا متفاوت باشد. کدهای این آموزش یک الگوی عملی هستند؛ پیش از استفاده نهایی، آن‌ها را با مستندات رسمی و فعال حساب خود تطبیق دهید.

پیام شیشه‌ای در روبیکا چیست؟

پیام شیشه‌ای اصطلاحی رایج برای پیام دارای دکمه‌های تعاملی است. کاربر با لمس هر دکمه، یک رویداد یا شناسه دکمه را برای ربات ارسال می‌کند و ربات می‌تواند پاسخ متناسب را نمایش دهد. برای نمونه، دکمه‌های «پشتیبانی»، «محصولات» و «مشاهده سایت» می‌توانند منوی ابتدایی ربات شما را تشکیل دهند.

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

پیش‌نیازهای ساخت ربات روبیکا با پایتون

• حساب فعال روبیکا و دسترسی به مسیر رسمی ساخت یا مدیریت ربات
• توکن ربات
• پایتون 3.8 یا جدیدتر
• کتابخانه requests
• شناسه چت کاربر، گروه یا کانال برای ارسال پیام

pip install requests

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

مرحله ۱: ساخت ربات و دریافت توکن

از مسیر رسمی ساخت ربات در روبیکا، یک ربات جدید ایجاد کنید و توکن ارائه‌شده را در محل امن ذخیره کنید. نام دقیق منوها یا دستورات ممکن است تغییر کند؛ بنابراین مراحل نمایش‌داده‌شده در محیط رسمی روبیکا را مبنا قرار دهید.

در لینوکس یا macOS، توکن را به‌صورت موقت در متغیر محیطی قرار دهید:

export RUBIKA_BOT_TOKEN='YOUR_TOKEN'

در ویندوز PowerShell:

$env:RUBIKA_BOT_TOKEN='YOUR_TOKEN'

مرحله ۲: ایجاد تابع عمومی برای ارسال درخواست API

تابع زیر درخواست‌های POST را با بدنه JSON ارسال می‌کند، خطاهای HTTP را بررسی می‌کند و پاسخ ناموفق API را تشخیص می‌دهد. مقدار BASE_URL را مطابق مستندات API فعال روبیکا تنظیم کنید.

import os
import requests

TOKEN = os.environ.get("RUBIKA_BOT_TOKEN")
if not TOKEN:
    raise RuntimeError("متغیر محیطی RUBIKA_BOT_TOKEN تنظیم نشده است.")

# این مقدار را با URL اعلام‌شده در مستندات رسمی API خود تطبیق دهید.
BASE_URL = f"https://botapi.rubika.ir/v3/{TOKEN}"


def call_api(method, payload=None):
    response = requests.post(
        f"{BASE_URL}/{method}",
        json=payload or {},
        timeout=20
    )
    response.raise_for_status()

    try:
        data = response.json()
    except ValueError as error:
        raise RuntimeError("پاسخ API دارای JSON معتبر نیست.") from error

    if isinstance(data, dict) and data.get("ok") is False:
        raise RuntimeError(f"خطای API: {data}")

    return data

اگر مستندات روبیکا بدنه درخواست را با قالب دیگری مانند data یا پارامترهای متفاوت مشخص کرده‌اند، همان مستندات اولویت دارند.

مرحله ۳: تست توکن ربات

برخی نسخه‌های API متدی مانند getMe برای بررسی وضعیت توکن دارند. اگر این متد در API شما پشتیبانی می‌شود، آن را اجرا کنید:

try:
    result = call_api("getMe")
    print(result)
except requests.RequestException as error:
    print("خطای اتصال یا پاسخ HTTP:", error)
except RuntimeError as error:
    print("خطای API:", error)

در صورت دریافت خطای مجوز، توکن، فعال‌بودن ربات و آدرس API را بررسی کنید.

مرحله ۴: ارسال اولین پیام در روبیکا

برای ارسال پیام به chat_id نیاز دارید. معمولاً کاربر باید ابتدا ربات را شروع کند یا پیامی بفرستد تا بتوانید شناسه چت را از رویدادهای ورودی دریافت کنید.

def send_message(chat_id, text):
    payload = {
        "chat_id": chat_id,
        "text": text
    }
    return call_api("sendMessage", payload)

# مقدار واقعی شناسه چت را جایگزین کنید.
# print(send_message("YOUR_CHAT_ID", "سلام! پیام از ربات روبیکا ارسال شد."))

مرحله ۵: ساخت پیام شیشه‌ای و دکمه تعاملی در روبیکا

در الگوی زیر، دکمه‌ها با ساختار inline_keypad به درخواست ارسال پیام افزوده می‌شوند. هر دکمه یک id یکتا دارد تا پس از کلیک بتوانید تشخیص دهید کاربر کدام گزینه را انتخاب کرده است. نام فیلدهایی مانند inline_keypad، rows، buttons و type را با مستندات نسخه خود کنترل کنید.

def send_glass_message(chat_id):
    payload = {
        "chat_id": chat_id,
        "text": "به ربات خوش آمدید. یکی از گزینه‌ها را انتخاب کنید:",
        "inline_keypad": {
            "rows": [
                {
                    "buttons": [
                        {
                            "id": "site",
                            "type": "Simple",
                            "button_text": "مشاهده سایت"
                        }
                    ]
                },
                {
                    "buttons": [
                        {
                            "id": "support",
                            "type": "Simple",
                            "button_text": "پشتیبانی"
                        },
                        {
                            "id": "products",
                            "type": "Simple",
                            "button_text": "محصولات"
                        }
                    ]
                }
            ]
        }
    }
    return call_api("sendMessage", payload)

# print(send_glass_message("YOUR_CHAT_ID"))

اگر API شما برای دکمه لینک، تماس یا ارسال داده نوع جداگانه‌ای تعریف کرده است، مقدار type و فیلدهای همان دکمه را طبق مستندات رسمی تغییر دهید.

مدیریت کلیک روی دکمه شیشه‌ای

ارسال دکمه به‌تنهایی کافی نیست. ربات باید رویداد کلیک را دریافت کند و بر اساس شناسه دکمه پاسخ بدهد. برای نمونه، اگر شناسه دکمه support باشد، ربات می‌تواند پیام راه‌های ارتباط با پشتیبانی را ارسال کند.

def handle_button_click(button_id, chat_id):
    if button_id == "support":
        return send_message(chat_id, "برای پشتیبانی، پیام خود را ارسال کنید.")

    if button_id == "products":
        return send_message(chat_id, "فهرست محصولات در حال آماده‌سازی است.")

    if button_id == "site":
        return send_message(chat_id, "آدرس سایت: https://example.com")

    return send_message(chat_id, "گزینه انتخاب‌شده معتبر نیست.")

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

دریافت پیام‌ها و رویدادها: Polling یا Webhook

• Polling: برنامه در بازه‌های مشخص رویدادهای جدید را از API دریافت می‌کند. این روش برای یادگیری و تست اولیه ساده‌تر است.
• Webhook: روبیکا رویدادها را به یک آدرس HTTPS روی سرور شما ارسال می‌کند. این روش در صورت پشتیبانی API، برای اجرای پایدار مناسب‌تر است.

برای اجرای دائمی ربات، به محیطی همیشه فعال نیاز دارید. راهنمای راه‌اندازی ربات پایتون در سی‌پنل با ترمینال و اپ پایتون می‌تواند برای استقرار پروژه مفید باشد. اگر قبل از کدنویسی به طراحی سناریو، منو و جریان گفتگو نیاز دارید، مقاله آموزش ساخت سورس ربات روبیکا؛ از طراحی سناریو تا اجرا روی هاست را بخوانید.

نکات مهم برای دکمه‌های شیشه‌ای

• برای هر دکمه یک شناسه کوتاه، یکتا و معنادار مانند support یا products انتخاب کنید.
• متن دکمه را کوتاه و شفاف نگه دارید تا در صفحه موبایل خوانا باشد.
• در منوی اول تعداد دکمه‌ها را محدود کنید و گزینه‌های بیشتر را در منوهای بعدی قرار دهید.
• پاسخ هر دکمه را قبل از انتشار با یک حساب آزمایشی بررسی کنید.
• توکن را در متغیر محیطی نگه دارید و در صورت افشا شدن، آن را از مسیر رسمی بازنشانی کنید.

خطاهای رایج در ساخت پیام شیشه‌ای روبیکا

• نمایش داده نشدن دکمه‌ها: نام فیلدهای keypad، ساختار ردیف‌ها، نوع دکمه و نسخه API را بررسی کنید.
• خطای 401 یا مجوز: توکن، URL پایه و فعال‌بودن ربات را کنترل کنید.
• خطای 400: معمولاً به دلیل chat_id نامعتبر، بدنه ناقص یا نوع نادرست داده‌ها رخ می‌دهد.
• عمل نکردن کلیک دکمه: دریافت رویدادها را بررسی کنید و مطمئن شوید شناسه دکمه با شرط‌های برنامه یکسان است.
• قطع شدن ربات پس از بستن ترمینال: برای اجرای پایدار از هاست یا سرور مناسب استفاده کنید.

سوالات متداول

آیا ساخت پیام شیشه‌ای در روبیکا بدون برنامه‌نویسی ممکن است؟

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

چرا دکمه‌های پیام شیشه‌ای نمایش داده نمی‌شوند؟

ابتدا نام متد ارسال پیام و ساختار دقیق دکمه‌ها را در مستندات API فعال بررسی کنید. تفاوت در نام فیلدها، نوع دکمه، ساختار ردیف‌ها یا نسخه API از علت‌های رایج این مشکل است.

آیا باید توکن ربات را داخل فایل پایتون قرار دهم؟

خیر. بهتر است توکن را در متغیر محیطی یا تنظیمات امن سرور نگهداری کنید تا به‌صورت ناخواسته در مخزن کد یا فایل‌های عمومی منتشر نشود.

برای کارکرد دائمی ربات چه چیزی لازم است؟

ربات باید روی یک هاست، سرور یا محیط اجرایی همیشه فعال اجرا شود. اگر API از وب‌هوک پشتیبانی کند، به یک نشانی HTTPS معتبر نیز نیاز خواهید داشت.

جمع‌بندی

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

اگر قصد دارید ربات را برای پیام‌رسان‌ها و شبکه‌های اجتماعی با سناریوی اختصاصی توسعه دهید، صفحه ساخت ربات پیام‌رسان و شبکه‌های اجتماعی را بررسی کنید.

مطالب مرتبط

• آموزش ساخت سورس ربات روبیکا؛ از طراحی سناریو تا اجرا روی هاست
• آموزش راه اندازی ربات پایتون در سی پنل به وسیله ترمینال و اپ پایتون
• آموزش ساخت ربات تلگرام با Python
• آموزش ساخت ربات ایتا و ارسال خودکار پیام به کانال یا گروه

مطالب مرتبط

• آموزش ساخت ربات بله از صفر تا صد (۲۰۲۶) | راهنمای گام‌به‌گام