📚 Rubka Bot Python Library Documentation

نمونه تنظیم وب‌هوک (Webhook) در کتابخونه rubka

برای مشاهده مستندات کامل و آخرین نسخه راهنما، لطفاً به آدرس زیر مراجعه کنید:
github.com/Mahdy-Ahmadi)

🧠 Introduction

rubka is a Python library to interact with the Rubika Bot API. This library helps you create Telegram-like bots with support for messages, inline buttons, chat keypads, and callback handling.

⚙️ Installation

pip install rubka

If importlib.metadata is not available, it installs importlib-metadata automatically.

🚀 Getting Started

from rubka import Robot
from rubka.context import Message

bot = Robot(token="YOUR_TOKEN_HERE")

@bot.on_message(commands=["start"])
def start(bot: Robot, message: Message):
    message.reply("سلام! خوش آمدید!")

bot.run()

📬 Handling Messages

You can handle incoming text messages using @bot.on_message():

@bot.on_message(commands=["hello"])
def greet(bot: Robot, message: Message):
    message.reply("سلام کاربر عزیز 👋")

You can also add filters.

🎮 Handling Callback Buttons

from rubka.keypad import ChatKeypadBuilder

@bot.on_message(commands=["gender"])
def gender(bot: Robot, message: Message):
    keypad = ChatKeypadBuilder().row(
        ChatKeypadBuilder().button(id="male", text="👨 مرد"),
        ChatKeypadBuilder().button(id="female", text="👩 زن")
    ).build()
    message.reply_keypad("جنسیت خود را انتخاب کنید:", keypad)

@bot.on_callback("male")
def on_male(bot: Robot, message: Message):
    message.reply("شما مرد هستید")

@bot.on_callback("female")
def on_female(bot: Robot, message: Message):
    message.reply("شما زن هستید")

🔘 Inline Button Builder

from rubka.button import InlineBuilder

builder = InlineBuilder().row(
    InlineBuilder().button_simple(id="info", text="اطلاعات")
).build()

🔄 Check if User Joined a Channel

channel_guid = "c0xABCDEF..."

@bot.on_message(commands=["check"])
def check(bot: Robot, message: Message):
    if bot.check_join(channel_guid, message.chat_id):
        message.reply("✅ شما عضو کانال هستید")
    else:
        message.reply("❌ لطفاً ابتدا در کانال عضو شوید")

💬 Utility Methods

| Method | Description | |--------|-------------| | get_chat(chat_id) | دریافت اطلاعات چت | | get_name(chat_id) | دریافت نام کاربر | | get_username(chat_id) | دریافت نام‌کاربری | | send_message(...) | ارسال پیام متنی | | edit_message_text(...) | ویرایش پیام | | delete_message(...) | حذف پیام | | send_location(...) | ارسال موقعیت مکانی | | send_poll(...) | ارسال نظرسنجی | | send_contact(...) | ارسال مخاطب | | forward_message(...) | فوروارد پیام |

🎛 Inline Query Support

@bot.on_inline_query()
def inline(bot: Robot, message: InlineMessage):
    message.answer("نتیجه اینلاین")

🧱 Button Types

Supported inline button types include:

Simple
Payment
Calendar
Location
CameraImage, CameraVideo
GalleryImage, GalleryVideo
File, Audio, RecordAudio
MyPhoneNumber, MyLocation
Textbox, Barcode, Link

See InlineBuilder for more.

🧩 Dynamic Chat Keypad

builder = ChatKeypadBuilder()
keypad = builder.row(
    builder.button(id="play", text="🎮 بازی کن"),
    builder.button(id="exit", text="❌ خروج")
).build()

🧪 Set Commands

bot.set_commands([
    {"command": "start", "description": "شروع"},
    {"command": "help", "description": "راهنما"}
])

🔄 Update Offset Automatically

Bot updates are handled using get_updates() and offset_id is managed internally.

🛠 Advanced Features

update_bot_endpoint() – تنظیم webhook یا polling
remove_keypad() – حذف صفحه‌کلید چت
edit_chat_keypad() – ویرایش یا افزودن صفحه‌کلید چت

📘 Rubka Bot Method Reference

مستندات مربوط به متدهای اصلی کلاس Robot در کتابخانه Rubka.

✅ پیام‌ها و هندلرها

`on_message(filters=None, commands=None)`

توضیح: ثبت هندلر برای پیام‌های ورودی.

filters: تابع شرطی برای فیلتر پیام‌ها (اختیاری)
commands: لیست دستورهایی که شروع با / هستند (اختیاری)

`on_callback(button_id=None)`

توضیح: ثبت هندلر برای دکمه‌های فشرده‌شده

button_id: آیدی دکمه‌ای که باید هندل شود (اختیاری)

`on_inline_query()`

توضیح: ثبت هندلر برای پیام‌های اینلاین (inline query)

📨 ارسال پیام

`send_message(...)`

توضیح: ارسال پیام متنی به چت

chat_id: آیدی چت مقصد (str) ✅
text: محتوای پیام (str) ✅
chat_keypad: کی‌پد معمولی (dict)
inline_keypad: کی‌پد اینلاین (dict)
reply_to_message_id: پاسخ به پیام خاص (str)
disable_notification: بدون نوتیف (bool)
chat_keypad_type: حالت کی‌پد ("New" | "Removed")

📁 ارسال فایل‌ها

متدهای مشترک (فایل، موزیک، ویس، گیف، عکس):

send_document(...)
send_music(...)
send_voice(...)
send_gif(...)
send_image(...)

پارامترهای اصلی:

chat_id: آیدی چت
path: مسیر فایل یا URL (اختیاری)
file_id: اگر فایل قبلاً آپلود شده باشد
text: کپشن فایل
file_name: نام فایل
inline_keypad, chat_keypad, reply_to_message_id, disable_notification, chat_keypad_type

📍 سایر متدهای مهم

`get_me()`

دریافت اطلاعات ربات

`get_chat(chat_id)`

دریافت اطلاعات یک چت

`get_name(chat_id)`

دریافت نام مخاطب بر اساس first_name و last_name

`get_username(chat_id)`

دریافت نام کاربری چت (در صورت وجود)

`check_join(channel_guid, chat_id)`

بررسی عضویت کاربر در کانال خاص

`remove_keypad(chat_id)`

حذف کی‌پد معمولی چت

`edit_chat_keypad(chat_id, chat_keypad)`

ویرایش یا اضافه کردن کی‌پد چت

`edit_message_text(chat_id, message_id, text)`

ویرایش متن پیام ارسال‌شده

`edit_inline_keypad(chat_id, message_id, inline_keypad)`

ویرایش کی‌پد اینلاین پیام

`delete_message(chat_id, message_id)`

حذف پیام از چت

`send_poll(chat_id, question, options)`

ارسال نظرسنجی به چت

`send_location(chat_id, latitude, longitude, ...)`

ارسال موقعیت مکانی به چت

`send_contact(chat_id, first_name, last_name, phone_number)`

ارسال مخاطب به چت

`forward_message(from_chat_id, message_id, to_chat_id)`

فروارد کردن پیام از یک چت به چت دیگر

`set_commands(bot_commands)`

تنظیم دستورات رسمی ربات (برای /help و ...)

`update_bot_endpoint(url, type)`

تنظیم وب‌هوک یا polling برای دریافت پیام‌ها

📦 مدیریت فایل و آپلود

`get_upload_url(media_type)`

دریافت آدرس آپلود فایل برای انواع مختلف: File, Image, Voice, Music, Gif

`upload_media_file(upload_url, name, path)`

آپلود فایل از مسیر محلی یا URL به Rubika و دریافت file_id

🔄 دریافت بروزرسانی‌ها

`get_updates(offset_id=None, limit=None)`

دریافت بروزرسانی‌ها (برای polling)

📦 Rubka `Message` Class & Media Reply API Documentation

🧾 معرفی کلاس `Message`

کلاس Message در کتابخانه Rubka ابزاری کلیدی برای مدیریت پیام‌های دریافتی در ربات است. این کلاس، قابلیت‌هایی همچون پاسخ به پیام، ارسال مدیا، حذف یا ویرایش پیام، و استفاده از صفحه‌کلید و دکمه‌های اینلاین را فراهم می‌کند.

⚙️ مشخصات کلاس `Message`

Message(bot, chat_id, message_id, sender_id, text=None, raw_data=None)

پارامترها:

| پارامتر | توضیح | | ------------ | ---------------------------------------- | | bot | نمونه‌ی شی ربات | | chat_id | شناسه چت | | message_id | آیدی پیام | | sender_id | شناسه فرستنده | | text | متن پیام | | raw_data | داده‌ی خام پیام (دیکشنری دریافتی از API) |

ویژگی‌ها (Attributes):

reply_to_message_id – اگر پیام در پاسخ ارسال شده باشد، آیدی پیام اولیه
file, sticker, poll, contact_message, location, ... – داده‌های مربوطه اگر وجود داشته باشند

📩 متدهای پاسخ‌دهی

✉️ `reply(text: str, **kwargs)`

پاسخ متنی به پیام با قابلیت ارسال دکمه و گزینه‌های اضافی.

📊 `reply_poll(question, options, **kwargs)`

ارسال نظرسنجی در پاسخ به پیام.

📎 `reply_document(...)`

ارسال فایل یا سند با متن اختیاری و دکمه.

🖼 `reply_image(...)`

ارسال تصویر با قابلیت reply همراه دکمه‌های chat یا inline.

🎵 `reply_music(...)`

ارسال موزیک در پاسخ.

🎤 `reply_voice(...)`

ارسال پیام صوتی (voice).

🎞 `reply_gif(...)`

ارسال گیف در پاسخ به پیام.

🗺 `reply_location(latitude, longitude, **kwargs)`

ارسال لوکیشن در پاسخ.

📇 `reply_contact(first_name, last_name, phone_number, **kwargs)`

ارسال مخاطب در پاسخ.

🔘 پاسخ با دکمه‌ها

`reply_keypad(text, keypad, **kwargs)`

ارسال پیام با صفحه‌کلید چتی (ChatKeypad).

`reply_inline(text, inline_keypad, **kwargs)`

ارسال پیام با دکمه‌های شیشه‌ای (Inline).

📦 پاسخ با فایل‌ها و استیکر

`reply_sticker(sticker_id, **kwargs)`

ارسال استیکر در پاسخ به پیام.

`reply_file(file_id, **kwargs)`

ارسال فایل بر اساس File ID.

✏️ ویرایش و حذف

`edit(new_text)`

ویرایش متن پیام.

`delete()`

حذف پیام فعلی.

📤 مثال کاربردی کامل

@bot.on_message()
def handler(bot: Robot, message: Message):
    # پاسخ با تصویر و دکمه‌های مختلف
    message.reply_image(
        path="https://s6.uupload.ir/files/sample.png",
        text="📷 تصویر پاسخ‌داده‌شده با دکمه‌ها",
        inline_keypad=inline_keypad
    )

    message.reply_image(
        path="https://s6.uupload.ir/files/sample.png",
        text="📷 تصویر دوم با صفحه‌کلید",
        chat_keypad=chat_keypad,
        chat_keypad_type="New"
    )

@bot.on_callback()
def callback_handler(bot: Robot, message: Message):
    data = message.aux_data.button_id
    if data == "btn_male":
        message.reply("سلام آقا 👨")
    elif data == "btn_female":
        message.reply("سلام خانم 👩")
    else:
        message.reply(f"دکمه ناشناخته: {data}")

🧠 نکته

تمامی متدهای `reply_*

Rubka

Install / Use

README

📚 Rubka Bot Python Library Documentation

نمونه تنظیم وب‌هوک (Webhook) در کتابخونه rubka

🧠 Introduction

⚙️ Installation

🚀 Getting Started

📬 Handling Messages

🎮 Handling Callback Buttons

🔘 Inline Button Builder

🔄 Check if User Joined a Channel

💬 Utility Methods

🎛 Inline Query Support

🧱 Button Types

🧩 Dynamic Chat Keypad

🧪 Set Commands

🔄 Update Offset Automatically

🛠 Advanced Features

📘 Rubka Bot Method Reference

✅ پیام‌ها و هندلرها

on_message(filters=None, commands=None)

on_callback(button_id=None)

on_inline_query()

📨 ارسال پیام

send_message(...)

📁 ارسال فایل‌ها

متدهای مشترک (فایل، موزیک، ویس، گیف، عکس):

📍 سایر متدهای مهم

get_me()

get_chat(chat_id)

get_name(chat_id)

get_username(chat_id)

check_join(channel_guid, chat_id)

remove_keypad(chat_id)

edit_chat_keypad(chat_id, chat_keypad)

edit_message_text(chat_id, message_id, text)

edit_inline_keypad(chat_id, message_id, inline_keypad)

delete_message(chat_id, message_id)

send_poll(chat_id, question, options)

send_location(chat_id, latitude, longitude, ...)

send_contact(chat_id, first_name, last_name, phone_number)

forward_message(from_chat_id, message_id, to_chat_id)

set_commands(bot_commands)

update_bot_endpoint(url, type)