متد ها

کلاس کلاینت

متد : __init__
ورودی

فیلد	نوع	توضیحات
`token`	`str`	توکن
`session_name`	`str or None`	اسم سشن برای ذخیره سازی اطلاعات
`user_agent`	`str or None`	اطلاعات مرورگر ریکوست دهنده
`auth`	`str or None`	اوث
`key`	`str or None`	کلید پرایو
`platform`	`str or None = "web"`	پلتفرم
`web_hook`	`str or None`	وبهوک
`timeout`	`int or None = 10`	زمان خروج برای درخواست ها
`show_progress`	`bool or None`	دیدن پروسس ها
`raise_errors`	`bool or None`	نمایش ارور ها
`proxy`	`str or None`	پروکسی
`retries`	`int or None = 2.5`	تعداد دفعات تلاش برای درخواست مجدد درخواست در صورت موفق نبودن درخواست
`retry_delay`	`float or None = 0.5`	زمان استراحت قبل انجام دوباره درخواست در صورت موفق نبودن درخواست
`safeSendMode`	`bool or None = False`	حالت ارسال ایمن(به ترتیب اجرا شدن دستورات)
`max_cache_size`	`int or None = 1000`	حداکثر اندازه کش برای پیام ها
`max_msg_age`	`int or None = 60`	حداکثر عمر پیام و در صف ماندن برای انجام دستور(به ثانیه)

مثال

from rubka.asynco import Robot

bot = Robot("my token")

گرفتن نام کاربری چت

متد : get_username
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی کاربر/گروه/کانال

خروجی

فیلد	نوع	توضیحات
`username`	`str`	نام کاربری چت یا "None" اگر موجود نباشد

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): username = await bot.get_username("chat id") print(username) asyncio.run(test())

گرفتن اطلاعات بات

متد : get_me

خروجی

فیلد	نوع	توضیحات
`get_me`	`Dict[str, Any]`	اطلاعات بات

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): me = await bot.get_me() print(me) asyncio.run(test())

ارسال پیام (Text, InlineKeypad)

متد : send_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`text`	`str`	متن پیام
`chat_keypad`	`Dict[str, Any] or None`	چت کی پد
`inline_keypad`	`Dict[str, Any] or None`	اینلاین کی پد
`disable_notification`	`bool or None`	غیرفعال کردن اعلان؟ (پیشفرض false)
`reply_to_message_id`	`str or None`	در جوابِ پیامِ؟
`chat_keypad_type`	`Literal['New', 'Removed'] or None`	چت کی پد تایپ

خروجی

فیلد	نوع	توضیحات
`message_id`	`str`	شناسه پیام

مثال

from rubka import Robot from rubka.button import InlineBuilder import asyncio bot = Robot("my token") async def test(): sending = await bot.send_message("chat id","my text") # ارسال متن معمولی print(sending) builder = InlineBuilder().row( InlineBuilder().button_simple(id="start", text="استارت") ).row( InlineBuilder().button_simple(id="about_we", text="درباره ما"), InlineBuilder().button_simple(id="creator", text="سازنده") ).build() sending2 = await bot.send_message("chat id","my text",inline_keypad=builder) # ارسال پیام همراه با کی پد print(sending2) asyncio.run(test())

باطل کردن لینک دعوت چت

متد : revoke_chat_invite_link
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت یا گروه مورد نظر
`link`	`str`	لینک دعوتی که باید باطل شود

خروجی

فیلد	نوع	توضیحات
`result`	`dict`	اطلاعات لینک دعوت باطل‌شده

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): result = await bot.revoke_chat_invite_link("chat id", "https://rubika.ir/Rubka_Library") print(result) asyncio.run(test())

بستن نظرسنجی

متد : close_poll
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت یا گروهی که نظرسنجی در آن ارسال شده است
`message_id`	`str`	آیدی پیامی که شامل نظرسنجی است

خروجی

فیلد	نوع	توضیحات
`result`	`dict`	اطلاعات نظرسنجی پس از بسته‌شدن

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    result = await bot.close_poll("chat id", "message id")
    print(result)

asyncio.run(test())

ارسال پیام با دکمه لینک

متد : send_button_link
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت مورد نظر برای ارسال پیام
`title_button`	`str \| list`	عنوان دکمه یا لیستی از عنوان‌ها
`url`	`str \| list`	آدرس یا لیستی از لینک‌ها که با دکمه‌ها مرتبط هستند
`text`	`str`	متن پیام ارسالی
`reply_to_message_id`	`str \| None`	در صورت پاسخ به پیام خاص، آیدی پیام هدف
`id`	`str`	شناسهٔ دلخواه برای دکمه (پیش‌فرض `"None"`)

خروجی

فیلد	نوع	توضیحات
`result`	`dict`	اطلاعات پیام ارسال‌شده به همراه دکمه‌ها

مثال‌ها

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def example_single():
    await bot.send_button_link(
        chat_id="chat id",
        title_button="سایت من",
        url="https://api-free.ir",
        text="برای مشاهده سایت کلیک کنید 👇"
    )

async def example_multi():
    await bot.send_button_link(
        chat_id="chat id",
        title_button=["گوگل", "یوتیوب"],
        url=["https://google.com", "https://youtube.com"],
        text="انتخاب کنید 👇"
    )

asyncio.run(example_single())

ارسال نظرسنجی

متد : send_poll
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`question`	`str`	متن سوال
`options`	`List[str]`	لیست گزینه‌ها
`type`	`Literal["Regular","Quiz"]`	نوع نظرسنجی: Regular یا Quiz
`allows_multiple_answers`	`bool`	اجازه انتخاب چند گزینه؟ پیشفرض False
`is_anonymous`	`bool`	آیا پاسخ‌ها ناشناس باشند؟ پیشفرض True
`correct_option_index`	`int or None`	در Quiz، شاخص پاسخ صحیح
`hint / explanation`	`str or None`	توضیح یا راهنمای پاسخ صحیح
`reply_to_message_id`	`str or None`	اگر پیام پاسخ باشد، شناسه پیام اصلی
`disable_notification`	`bool`	غیرفعال کردن اعلان؟ پیشفرض False
`show_results`	`bool`	نمایش نتیجه پس از رأی دادن؟ پیشفرض False
`inline_keypad`	`Dict[str, Any] or None`	اینلاین کیپد (دکمه‌های زیر پیام)
`chat_keypad`	`Dict[str, Any] or None`	چت کیپد، فقط وقتی `chat_keypad_type="New"` است
`chat_keypad_type`	`Literal["New","Removed","None"]`	نوع کیپد: New برای کیپد جدید، Removed برای حذف کیپد، None برای نداشتن کیپد

خروجی

فیلد	نوع	توضیحات
`message_id`	`str`	شناسه پیام ارسال شده

مثال

from rubka import Robot
import asyncio

bot = Robot("my token")

async def test():
    # ارسال نظرسنجی بدون کیپد
    options1 = ["وانیلی", "شکلاتی"]
    sending1 = await bot.send_poll("chat id", "به چه کیکی علاقه دارید؟", options1)
    print(sending1)

    # ارسال نظرسنجی Quiz با پاسخ صحیح
    options2 = ["گزینه1", "گزینه2", "گزینه3"]
    sending2 = await bot.send_poll(
        "chat id",
        "کدام گزینه درست است؟",
        options2,
        type="Quiz",
        correct_option_index=1,
        hint="گزینه دوم صحیح است",
        show_results=True
    )
    print(sending2)

    # ارسال نظرسنجی با کیپد جدید
    chat_keypad = {"type": "buttons", "buttons": [["دکمه1"], ["دکمه2"]]}
    sending3 = await bot.send_poll(
        "chat id",
        "کدام دکمه را انتخاب می‌کنید؟",
        ["گزینه1", "گزینه2"],
        chat_keypad=chat_keypad,
        chat_keypad_type="New"
    )
    print(sending3)

asyncio.run(test())

ارسال گروهی پیام

متد : send_bulk_message
ورودی

فیلد	نوع	توضیحات
`chat_ids`	`List[str]`	لیست آیدی‌های چت مقصد
`text`	`str`	متن پیام
`concurrency`	`int`	تعداد پیام‌های همزمان (پیش‌فرض 5)
`delay_between`	`float`	تأخیر بین ارسال هر پیام به ثانیه
`log_errors`	`bool`	لاگ خطاها فعال باشد یا خیر

خروجی

نوع	توضیحات
`Dict[str, Optional[Dict]]`	نتیجه ارسال برای هر چت؛ در صورت خطا `None`

مثال

results = await bot.send_bulk_message(
    ["chat_id1", "chat_id2"],
    "سلام به همه",
    concurrency=3,
    delay_between=1.0
)
print(results)

حذف گروهی پیام

متد : delete_bulk_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت
`message_ids`	`list[str]`	لیست آیدی پیام‌ها برای حذف

خروجی

نوع	توضیحات
`List`	نتایج حذف هر پیام (می‌تواند شامل استثناها باشد)

مثال

await bot.delete_bulk_message("chat_id1", ["msg_id1", "msg_id2"])

ویرایش گروهی پیام

متد : edit_bulk_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت
`messages`	`dict[str, str]`	کلید = آیدی پیام، مقدار = متن جدید

خروجی

نوع	توضیحات
`List`	نتایج ویرایش هر پیام (می‌تواند شامل استثناها باشد)

مثال

await bot.edit_bulk_message("chat_id1", {"msg_id1": "متن جدید", "msg_id2": "متن دیگر"})

ارسال پیام زمان‌بندی‌شده

متد : send_scheduled_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت مقصد
`text`	`str`	متن پیام
`delay`	`int`	تأخیر قبل از ارسال (ثانیه)

خروجی

نوع	توضیحات
`Dict`	نتیجه ارسال پیام

مثال

await bot.send_scheduled_message("chat_id1", "این پیام بعد از 10 ثانیه ارسال می‌شود", delay=10)

غیرفعال کردن کیبورد داخلی

متد : disable_inline_keyboard
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت
`message_id`	`str`	آیدی پیام
`text`	`Optional[str]`	متن جایگزین (پیش‌فرض "~")
`delay`	`float`	تأخیر قبل از غیرفعال کردن کیبورد (ثانیه)

خروجی

نوع	توضیحات
`Dict`	نتیجه ویرایش پیام و غیرفعال کردن کیبورد

مثال

await bot.disable_inline_keyboard("chat_id1", "msg_id1", text="غیرفعال شد", delay=5)

دریافت آپدیت‌ها

متد : get_updates
ورودی

فیلد	نوع	توضیحات
`offset_id`	`str \| None`	شناسهٔ آخرین آپدیت دریافت‌شده (برای ادامه از همان نقطه)
`limit`	`int \| None`	تعداد آپدیت‌هایی که باید دریافت شوند

خروجی

فیلد	نوع	توضیحات
`data`	`dict`	حاوی لیستی از آپدیت‌ها (پیام‌ها، کوئری‌ها و...)

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    updates = await bot.get_updates(limit=10)
    for update in updates.get("data", {}).get("updates", []):
        print(update)

asyncio.run(test())

دریافت آپدیت از وب‌هوک

متد : update_webhook
ورودی

فیلد	نوع	توضیحات
`offset_id`	`str \| None`	شناسهٔ آخرین آپدیت دریافت‌شده برای ادامه از همان نقطه
`limit`	`int \| None`	تعداد آپدیت‌هایی که باید از وب‌هوک گرفته شوند

خروجی

فیلد	نوع	توضیحات
`list[dict]`	`List`	لیستی از آپدیت‌های جدید دریافت‌شده از آدرس وب‌هوک

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")
bot.web_hook = "https://example.com/webhook"  # آدرس وب‌هوک شما

async def test():
    updates = await bot.update_webhook(limit=5)
    for update in updates:
        print(update)

asyncio.run(test())

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

متد : send_location
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`latitude`	`str`	عرض جغرافیایی
`longitude`	`str`	طول جغرافیایی
`disable_notification`	`str or None`	غیرفعال کردن اعلان؟ (پیشفرض false)
`inline_keypad`	`inline_keypad or None`	اینلاین کی پد
`reply_to_message_id`	`str or None`	در جوابِ پیامِ؟
`chat_keypad_type`	`str or None`	نوع keypad

خروجی

فیلد	نوع	توضیحات
`message_id`	`str`	شناسه پیام

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): sending = await bot.send_location("chat id", "35.6892", "51.3890") print(sending) asyncio.run(test())

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

متد : get_chat_info
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت (کاربر، گروه یا کانال)

خروجی

فیلد	نوع	توضیحات
`data`	`dict`	اطلاعات کامل چت شامل عنوان، نوع، توضیحات و...

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    info = await bot.get_chat_info("chat id")
    print(info)

asyncio.run(test())

دریافت مدیران چت

متد : get_chat_admins
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت (گروه یا کانال)

خروجی

فیلد	نوع	توضیحات
`data`	`dict`	لیست اطلاعات مدیران چت

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    admins = await bot.get_chat_admins("chat id")
    print(admins)

asyncio.run(test())

دریافت اعضای چت

متد : get_chat_members
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت
`start_id`	`str`	شناسه شروع برای صفحه‌بندی اعضا (اختیاری)

خروجی

فیلد	نوع	توضیحات
`data`	`dict`	لیست اعضای چت

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    members = await bot.get_chat_members("chat id")
    print(members)

asyncio.run(test())

تغییر عنوان چت

متد : set_chat_title
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت
`title`	`str`	عنوان جدید گروه یا کانال

خروجی

فیلد	نوع	توضیحات
`data`	`dict`	نتیجه تغییر عنوان

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    res = await bot.set_chat_title("chat id", "عنوان جدید من")
    print(res)

asyncio.run(test())

تغییر توضیحات چت

متد : set_chat_description
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت
`description`	`str`	توضیحات جدید گروه یا کانال

خروجی

فیلد	نوع	توضیحات
`data`	`dict`	نتیجه تغییر توضیحات

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    res = await bot.set_chat_description("chat id", "توضیحات جدید گروه")
    print(res)

asyncio.run(test())

سنجاق کردن پیام در چت

متد : pin_chat_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت یا گروه
`message_id`	`str`	آیدی پیامی که باید سنجاق شود

خروجی

فیلد	نوع	توضیحات
`result`	`dict`	اطلاعات نتیجه سنجاق پیام

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    result = await bot.pin_chat_message("chat id", "message id")
    print(result)

asyncio.run(test())

برداشتن سنجاق پیام در چت

متد : unpin_chat_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت یا گروه
`message_id`	`str`	آیدی پیامی که سنجاقش برداشته شود

خروجی

فیلد	نوع	توضیحات
`result`	`dict`	اطلاعات نتیجه سنجاق پیام

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    result = await bot.unpin_chat_message("chat id", "message id")
    print(result)

asyncio.run(test())

ارسال مخاطب

متد : send_contact
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`first_name`	`str`	نام مخاطب
`last_name`	`str`	نام‌خانوادگی مخاطب
`phone_number`	`str`	شماره مخاطب

خروجی

فیلد	نوع	توضیحات
`message_id`	`str`	شناسه پیام

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): sending = await bot.send_contact("chat id", "first name", "last name", "+989017760881") print(sending) asyncio.run(test())

دریافت پیام با آیدی

متد : get_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	آیدی چت کاربر/گروه/کانال
`message_id`	`str`	آیدی پیام

خروجی

فیلد	نوع	توضیحات
`message`	`dict`	دیکشنری حاوی اطلاعات پیام

مثال

import asyncio from rubka.asynco import Robot, Message bot = Robot("") bot.start_save_message() #این متود به معنای شروع شنود پیام ها توسط ربات هست برای استفاده داخل متود گت مسیج # اگه بخواید یه سورس متود گت مسیج داخلش کار کنه حتما باید اول سورس این متود رو بزارید تا ربات بعد از فعال شدن شروع به شنود مکالمات کنه برای دریافت از طریق متود گت مسیج @bot.on_message() async def info(bot: Robot, message: Message): if message.text == "info": data = await bot.get_message(message.chat_id, message.reply_to_message_id or message.message_id) #متود گت مسیج await message.reply(f"{data}") asyncio.run(bot.run())

گرفتن آواتار بات

متد : get_avatar_me
ورودی

فیلد	نوع	توضیحات
`save_as`	`str or None`	اگر مسیر فایل داده شود، آواتار بات در این مسیر ذخیره می‌شود

خروجی

فیلد	نوع	توضیحات
`url`	`str`	لینک دانلود آواتار بات یا "null" اگر آواتاری موجود نباشد

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): url = await bot.get_avatar_me(save_as="my_avatar.png") print(url) asyncio.run(test())

ویرایش پیام پس از تأخیر

متد : edit_after
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`message_id`	`str`	شناسه پیام
`text`	`str`	متن جدید برای ویرایش پیام
`delay`	`int`	مدت زمان انتظار قبل از ویرایش پیام (به ثانیه، پیشفرض 30)

خروجی

فیلد	نوع	توضیحات
`task`	`asyncio.Task`	تسک asyncio که پیام را پس از تأخیر ویرایش می‌کند

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): task = await bot.edit_after("chat id", "message id", "متن جدید", delay=10) print(task) asyncio.run(test())

دریافت تمام اعضای کانال

متد : get_all_member
ورودی

فیلد	نوع	توضیحات
`channel_guid`	`str`	آیدی کانال
`search_text`	`str \| None`	متن جستجو برای فیلتر اعضا (اختیاری)
`start_id`	`str \| None`	آیدی شروع از آن عضو (برای پیمایش)
`just_get_guids`	`bool`	اگر True باشد، فقط آیدی اعضا برگردانده می‌شود

خروجی

نوع	توضیحات
`list`	لیست اعضای کانال یا لیست آیدی‌ها بسته به پارامتر `just_get_guids`

مثال

from rubka.asynco import Robot bot = Robot("my token") members = bot.get_all_member("channel id", search_text="Ali", just_get_guids=True) print(members)

حذف پیام پس از تأخیر

متد : delete_after
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`message_id`	`str`	شناسه پیام
`delay`	`int`	مدت زمان انتظار قبل از حذف پیام (به ثانیه، پیشفرض 30)

خروجی

فیلد	نوع	توضیحات
`task`	`asyncio.Task`	تسک asyncio که پیام را پس از تأخیر حذف می‌کند

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): task = await bot.delete_after("chat id", "message id", delay=10) print(task) asyncio.run(test())

هندلر پیام متنی

متد : on_message_text
توضیح :

این دکوریتور زمانی اجرا می‌شود که پیام دریافتی شامل متن باشد.

ورودی

فیلد	نوع	توضیحات
`filters`	`callable \| None`	تابع فیلتر اختیاری برای بررسی پیام
`commands`	`list[str] \| None`	لیستی از دستورات که باید شناسایی شوند

مثال

from rubka.asynco import Robot, Message

bot = Robot("my token")

@bot.on_message_text()
async def handler(bot, message: Message):
    await bot.reply_message(message, "پیام متنی دریافت شد ✅")

هندلر فایل

متد : on_message_file
توضیح :

این دکوریتور زمانی اجرا می‌شود که پیام شامل فایل باشد.

مثال

@bot.on_message_file()
async def file_handler(bot, message: Message):
    await bot.reply_message(message, "فایل دریافت شد 📁")

هندلر پیام فورواردشده

متد : on_message_forwarded

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

@bot.on_message_forwarded()
async def forwarded_handler(bot, message: Message):
    await bot.reply_message(message, "این پیام فورواردی بود 🔁")

هندلر پیام ریپلای

زمانی اجرا می‌شود که پیام در پاسخ به پیام دیگری ارسال شده باشد.

@bot.on_message_reply()
async def reply_handler(bot, message: Message):
    await bot.reply_message(message, "این پیام در پاسخ به پیام دیگری بود 💬")

هندلر رسانه (عکس/ویدیو/گیف)

@bot.on_message_media()
async def media_handler(bot, message: Message):
    await bot.reply_message(message, "رسانه دریافت شد 🎬")

هندلر استیکر

@bot.on_message_sticker()
async def sticker_handler(bot, message: Message):
    await bot.reply_message(message, "استیکر قشنگی بود 😄")

هندلر مخاطب

@bot.on_message_contact()
async def contact_handler(bot, message: Message):
    await bot.reply_message(message, "مخاطب دریافت شد 👤")

هندلر موقعیت مکانی

@bot.on_message_location()
async def location_handler(bot, message: Message):
    await bot.reply_message(message, "موقعیت جغرافیایی دریافت شد 📍")

هندلر نظرسنجی

@bot.on_message_poll()
async def poll_handler(bot, message: Message):
    await bot.reply_message(message, "نظرسنجی جدید دریافت شد 📊")

هندلر همه آپدیت‌ها

برای بررسی تمام آپدیت‌ها بدون محدودیت نوع پیام.

@bot.on_update()
async def update_handler(bot, message: Message):
    print(message)

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

متد : on_message_group
توضیح :

این دکوریتور برای کنترل پیشرفتهٔ پیام‌ها در گروه‌ها استفاده می‌شود و فیلترهای متنوعی مثل نوع ارسال، فرستنده، محتوای پیام، طول متن و ... دارد.

ورودی

فیلد	نوع	توضیحات
`chat_id`	`str \| list \| None`	شناسه یا لیستی از چت‌های مجاز
`commands`	`list[str] \| None`	دستورات مجاز (مانند start/ یا info/)
`filters`	`callable \| None`	تابع فیلتر سفارشی برای بررسی پیام
`sender_id`	`str \| list \| None`	شناسه یا لیست شناسه‌های مجاز فرستنده
`sender_type`	`str \| None`	نوع فرستنده (مثلاً user یا bot)
`allow_forwarded`	`bool`	اجازهٔ پذیرش پیام فوروارد شده
`allow_files`	`bool`	اجازهٔ پذیرش پیام دارای فایل
`allow_stickers`	`bool`	اجازهٔ پذیرش استیکر
`allow_polls`	`bool`	اجازهٔ پذیرش نظرسنجی
`allow_contacts`	`bool`	اجازهٔ پذیرش پیام مخاطب
`allow_locations`	`bool`	اجازهٔ پذیرش موقعیت مکانی
`min_text_length`	`int \| None`	حداقل طول متن مجاز
`max_text_length`	`int \| None`	حداکثر طول متن مجاز
`contains`	`str \| None`	اجازه فقط به پیام‌هایی که شامل این عبارت هستند
`startswith`	`str \| None`	اجازه فقط به پیام‌هایی که با این عبارت شروع می‌شوند
`endswith`	`str \| None`	اجازه فقط به پیام‌هایی که با این عبارت تمام می‌شوند
`case_sensitive`	`bool`	حساسیت به حروف کوچک و بزرگ

مثال

from rubka.asynco import Robot, Message

bot = Robot("my token")

@bot.on_message_group(contains="سلام", allow_stickers=False)
async def greet(bot, message: Message):
    await bot.reply_message(message, "سلام 🌹 خوش اومدی به گروه!")

حذف هندلر

متد : remove_handler
توضیح :

برای حذف یک هندلر از لیست هندلرها با ارجاع به تابع اصلی آن استفاده می‌شود.

ورودی

فیلد	نوع	توضیحات
`func`	`callable`	تابع اصلی که باید از هندلرها حذف شود

مثال

@bot.on_message_text()
async def hello(bot, message: Message):
    await bot.reply_message(message, "سلام 👋")

# حذف هندلر:
bot.remove_handler(hello)

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

متد : on_edited_message
توضیح :

این دکوریتور زمانی اجرا می‌شود که پیام کاربر ویرایش شود (مانند تغییر متن پیام ارسال‌شده).

ورودی

فیلد	نوع	توضیحات
`filters`	`callable \| None`	تابع فیلتر برای بررسی پیام ویرایش‌شده
`commands`	`list[str] \| None`	دستورات مجاز در پیام ویرایش‌شده

مثال

@bot.on_edited_message()
async def edited(bot, message: Message):
    await bot.reply_message(message, "پیامت رو ویرایش کردی ✏️")

هندلر پیام‌های خصوصی پیشرفته

متد : on_message_private
توضیح :

این دکوریتور برای دریافت و مدیریت پیام‌های خصوصی (چت‌های دو نفره) با فیلترهای پیشرفته مانند فیلتر نوع فرستنده، طول پیام، محتوای متنی و... استفاده می‌شود.

ورودی

فیلد	نوع	توضیحات
`chat_id`	`str \| list \| None`	شناسه یا لیستی از چت‌های مجاز
`commands`	`list[str] \| None`	دستورات خاص که باید شناسایی شوند
`filters`	`callable \| None`	تابع فیلتر سفارشی
`sender_id`	`str \| list \| None`	شناسه یا لیستی از کاربران مجاز
`sender_type`	`str \| None`	نوع فرستنده (مثلاً user یا bot)
`allow_forwarded`	`bool`	اجازه برای پیام‌های فورواردی
`allow_files`	`bool`	اجازه ارسال فایل
`allow_stickers`	`bool`	اجازه ارسال استیکر
`allow_polls`	`bool`	اجازه ارسال نظرسنجی
`allow_contacts`	`bool`	اجازه ارسال مخاطب
`allow_locations`	`bool`	اجازه ارسال موقعیت مکانی
`min_text_length`	`int \| None`	حداقل طول متن
`max_text_length`	`int \| None`	حداکثر طول متن
`contains`	`str \| None`	اجازه فقط برای پیام‌هایی که شامل این عبارت هستند
`startswith`	`str \| None`	اجازه فقط برای پیام‌هایی که با این عبارت شروع می‌شوند
`endswith`	`str \| None`	اجازه فقط برای پیام‌هایی که با این عبارت تمام می‌شوند
`case_sensitive`	`bool`	حساسیت به حروف کوچک و بزرگ

مثال

from rubka.asynco import Robot, Message

bot = Robot("my token")

@bot.on_message_private(startswith="سلام", allow_files=False)
async def greet(bot, message: Message):
    await bot.reply_message(message, "سلام 👋 پیام خصوصی‌ت رو گرفتم!")

هندلر پیام‌های کانال پیشرفته

متد : on_message_channel
توضیح :

این دکوریتور برای کنترل پیام‌های ارسال‌شده در کانال‌ها با فیلترهای پیشرفته استفاده می‌شود (مثلاً بررسی نوع محتوا، فرستنده و متن).

ورودی

فیلد	نوع	توضیحات
`chat_id`	`str \| list \| None`	شناسه یا لیستی از کانال‌های مجاز
`commands`	`list[str] \| None`	دستورات مجاز
`filters`	`callable \| None`	تابع فیلتر سفارشی
`sender_id`	`str \| list \| None`	شناسه یا لیست شناسه‌های مجاز فرستنده
`sender_type`	`str \| None`	نوع فرستنده (user یا bot)
`allow_forwarded`	`bool`	اجازه برای پیام‌های فورواردی
`allow_files`	`bool`	اجازه ارسال فایل
`allow_stickers`	`bool`	اجازه ارسال استیکر
`allow_polls`	`bool`	اجازه ارسال نظرسنجی
`allow_contacts`	`bool`	اجازه ارسال مخاطب
`allow_locations`	`bool`	اجازه ارسال موقعیت مکانی
`min_text_length`	`int \| None`	حداقل طول متن مجاز
`max_text_length`	`int \| None`	حداکثر طول متن مجاز
`contains`	`str \| None`	عبارتی که باید در متن وجود داشته باشد
`startswith`	`str \| None`	عبارتی که متن باید با آن شروع شود
`endswith`	`str \| None`	عبارتی که متن باید با آن تمام شود
`case_sensitive`	`bool`	حساسیت به حروف کوچک و بزرگ

مثال

@bot.on_message_channel(contains="اطلاعیه", allow_stickers=False)
async def channel_announce(bot, message: Message):
    print("📢 پیام جدید در کانال:", message.text)

بستن نشست aiohttp

متد : close
توضیح :

این متد برای بستن امن نشست (Session) aiohttp استفاده می‌شود. در صورتی که نشست فعال باشد و هنوز بسته نشده باشد، با اجرای این متد، به صورت ایمن بسته می‌شود.

ورودی

فیلد	نوع	توضیحات
—	—	این متد هیچ ورودی‌ای دریافت نمی‌کند.

خروجی

نوع	توضیحات
`None`	خروجی ندارد، اما سشن داخلی `aiohttp` بسته می‌شود.

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def main():
    # انجام برخی عملیات
    await bot.send_message("chat_id", "سلام! 👋")
    
    # بستن امن نشست aiohttp
    await bot.close()

asyncio.run(main())

آپلود فایل رسانه‌ای

متد : upload_media_file
توضیح :

این متد برای آپلود فایل‌های رسانه‌ای (عکس، ویدیو، صوت و...) به سرور مورد استفاده قرار می‌گیرد. در صورتی که ورودی مسیر فایل یک لینک اینترنتی باشد، ابتدا فایل به‌صورت موقت دانلود شده و سپس آپلود می‌شود.

ورودی

فیلد	نوع	توضیحات
`upload_url`	`str`	آدرس آپلود فایل که از متدهای دیگر مانند `getFileUploadUrl` دریافت می‌شود.
`name`	`str`	نام فایلی که هنگام آپلود استفاده می‌شود.
`path`	`str \| Path`	مسیر فایل محلی یا لینک مستقیم فایل (درصورت لینک، فایل به‌صورت موقت دانلود می‌شود).

خروجی

نوع	توضیحات
`str`	در صورت موفقیت، شناسه فایل آپلودشده (`file_id`) را بازمی‌گرداند.

نکات

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

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    upload_url = "https://rubka.ir/upload"
    file_id = await bot.upload_media_file(upload_url, "photo.jpg", "C:/images/photo.jpg")
    print("File uploaded successfully! File ID:", file_id)

asyncio.run(test())

دریافت آدرس آپلود فایل

متد : get_upload_url
توضیح :

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

ورودی

فیلد	نوع	توضیحات
`media_type`	`Literal['File', 'Image', 'voice', 'Music', 'Gif', 'Video']`	نوع فایل مورد نظر برای آپلود. فقط یکی از مقادیر مجاز بالا باید انتخاب شود.

خروجی

نوع	توضیحات
`str`	در صورت موفقیت، لینک موقت آپلود فایل را بازمی‌گرداند.

نکات

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

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    upload_url = await bot.get_upload_url("Image")
    print("Upload URL:", upload_url)

asyncio.run(test())

اجرای اصلی ربات (run)

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

متد : run
پارامترها

پارامتر	نوع	توضیحات
`debug`	`bool`	فعال‌سازی حالت اشکال‌زدایی و لاگ دقیق
`sleep_time`	`float`	تأخیر بین چرخه‌های دریافت به‌روزرسانی (ثانیه)
`webhook_timeout`	`int`	زمان انتظار برای وبهوک (ثانیه)
`update_limit`	`int`	حداکثر به‌روزرسانی برای دریافت در هر درخواست
`retry_delay`	`float`	تأخیر قبل از تلاش مجدد پس از خطا (ثانیه)
`stop_on_error`	`bool`	قطع اجرای ربات در صورت بروز خطا
`auto_restart`	`bool`	راه‌اندازی مجدد خودکار ربات در صورت توقف ناخواسته
`max_runtime`	`float \| None`	حداکثر زمان اجرای ربات (ثانیه)
`allowed_update_types`	`list[str] \| None`	محدود کردن پردازش به انواع خاص به‌روزرسانی‌ها
`ignore_duplicate_messages`	`bool`	رد پیام‌های تکراری
`skip_inline_queries`	`bool`	رد پرسش‌های درون‌خطی
`ignore_users`	`set[str] \| None`	آیدی کاربرانی که نادیده گرفته شوند
`ignore_groups`	`set[str] \| None`	آیدی گروه‌هایی که نادیده گرفته شوند
`require_admin_rights`	`bool`	پردازش فقط در صورتی که فرستنده ادمین باشد
`process_in_background`	`bool`	پردازش به‌روزرسانی‌ها در پس‌زمینه با صف و تسک‌ها
`max_queue_size`	`int`	حداکثر طول صف پردازش
`thread_workers`	`int`	تعداد تسک‌های پس‌زمینه
`message_filter`	`callable \| None`	تابع فیلتر پیام‌ها
`max_concurrent_tasks`	`int \| None`	حداکثر تسک‌های همزمان
`metrics_enabled`	`bool`	فعال‌سازی جمع‌آوری آمار
`metrics_handler`	`callable \| None`	تابع پردازش آمار
`notify_on_error`	`bool`	ارسال اعلان هنگام بروز خطا
`notification_handler`	`callable \| None`	تابع ارسال اعلان
`watchdog_timeout`	`float \| None`	حداکثر زمان بیکاری قبل از راه‌اندازی مجدد

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def main():
    await bot.run(
        debug=True,
        sleep_time=0.1,
        allowed_update_types=["NewMessage", "ReceiveQuery"],
        ignore_duplicate_messages=True,
        process_in_background=True,
        thread_workers=3,
    )

asyncio.run(main())

گرفتن آپدیت پیام ها

متد : on_message , on_update
ورودی

فیلد	نوع	توضیحات
`filters`	`filters or None`	فیلتر کردن گرفتن پیام
`commands`	`List[str] or None`	فیلتر کردن با لیست دستورات

خروجی

فیلد	نوع	توضیحات
`Message`	`Message`	مسیج آپدیت

مثال

from rubka.asynco import Robot,Message import asyncio bot = Robot("my token") @bot.on_message() async def test(message:Message): print(f"message : {message}") print(f"text message : {message.text}") await message.reply("this is a reply text from rubka") asyncio.run(bot.run())

گرفتن آپدیت کلیک های دکمه های شیشه ای

متد : on_callback , on_callback_query
ورودی

فیلد	نوع	توضیحات
`button_id`	`str or None`	فیلتر کردن با آیدی دکمه

خروجی

فیلد	نوع	توضیحات
`InlineMessage`	`InlineMessage`	اینلاین مسیج

مثال

from rubka.asynco import Robot,InlineMessage import asynico bot = Robot("my token") @bot.on_callback() async def test(msg:InlineMessage): print(msg) await msg.reply("this is a text from rubka") asynico.run(bot.run())

گرفتن نام کامل چت/کاربر

متد : get_name
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی کاربر/گروه/کانال

خروجی

فیلد	نوع	توضیحات
`name`	`str`	نام کامل کاربر، یا عنوان گروه/کانال، یا "null" اگر موجود نباشد

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): name = await bot.get_name("chat id") print(name) asyncio.run(test())

گرفتن اطلاعات چت

متد : get_chat
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی کاربر/گروه/کانال

خروجی

فیلد	نوع	توضیحات
`chat`	`chat`	اطلاعات چت

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): chat = await bot.get_chat("chat id") print(chat) asyncio.run(test())

فوروارد کردن پیام

متد : forward_message
ورودی

فیلد	نوع	توضیحات
`from_chat_id`	`str`	از چتِ؟
`message_id`	`str`	شناسه پیام
`to_chat_id`	`str`	به چتِ؟
`disable_notification`	`bool or None`	غیرفعال کردن اعلان؟ (پیشفرض false)

خروجی

فیلد	نوع	توضیحات
`new_message_id`	`str`	شناسه پیام جدید

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): sending = await bot.forward_message("from chat id", "message id", "to chat id") print(sending) asyncio.run(test())

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

متد : edit_message_text
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`message_id`	`str`	شناسه پیام
`text`	`str`	پیام

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): editing = await bot.edit_message_text("chat id", "message id", "new text") print(editing) asyncio.run(test())

ویرایش Inline Keypad

متد : edit_inline_keypad
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`message_id`	`str`	شناسه پیام
`inline_keypad`	`Dict[str, Any]`	اینلاین کی پد
`text`	`str`	متن پیام

مثال

from rubka.asynco import Robot from rubka.button import InlineBuilder import asyncio bot = Robot("my token") async def test(): builder = InlineBuilder().row( InlineBuilder().button_simple(id="info", text="اطلاعات") ).build() editing = await bot.edit_inline_keypad("chat id", "message id", builder) print(editing) asyncio.run(test())

حذف پیام

متد : delete_message
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`message_id`	`str`	شناسه پیام

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): deleteing = await bot.delete_message("chat id", "message id") print(deleteing) asyncio.run(test())

تنظیم دستور‌ها (commands)

متد : set_commands

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): setting = await bot.set_commands([ {"command": "start", "description": "شروع"}, {"command": "help", "description": "راهنما"} ]) print(setting) asyncio.run(test())

آپدیت آدرس بات (URL Endpoint)

متد : update_bot_endpoint
ورودی

فیلد	نوع	توضیحات
`url`	`str`	آدرس جدید
`type`	`EndPoint`	نوع EndPoint

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): update_end_point = await bot.update_bot_endpoint("my url end point", "ReceiveUpdate") print(update_end_point) asyncio.run(test())

ارسال فایل/ویدیو/تصویر/پیغام صوتی/موسیقی/گیف

متد : send_file , send_document , send_video , send_image , send_voice , send_music , send_gif
ورودی

فیلد	نوع	توضیحات
`chat_id`	`str`	چت آیدی
`path`	`str or Path or None`	مسیر فایل یا URL (اختیاری)
`file_id`	`str or None`	فایل آیدی(اگر فایل قبلاً آپلود شده باشد)
`caption / text`	`str or None`	کپشن فایل
`file_name`	`str or None`	نام فایل
`inline_keypad`	`Dict[str, Any] or None`	اینلاین کی پد
`chat_keypad`	`Dict[str, Any] or None`	چت کی پد
`reply_to_message_id`	`str or None`	در جواب ؟
`disable_notification`	`bool or None`	غیرفعال کردن اعلان؟ (پیشفرض false)
`chat_keypad_type`	`Literal['New', 'Removed', 'None'] or None`	چت کی پد تایپ

مثال

from rubka.asynco import Robot import asyncio bot = Robot("my token") async def test(): sending = await bot.send_file("chat id", "test.json", file_name="data.json", caption="this is a caption") sending2 = await bot.send_image("chat id", "test.png", file_name="picture.png", text="this is a caption") print(sending) print(sending2) asyncio.run(test())

دانلود فایل

متد : download
ورودی

فیلد	نوع	توضیحات
`file_id`	`str`	فایل آیدی
`save_as`	`str`	آدرس ذخیره
`chunk_size`	`int = 1024 * 512`	مقدار تقسیم کردن آپلود
`timeout_sec`	`int = 60`	تایم اوت
`verbose`	`bool = False`	لاگ های آپلود

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
  await bot.download("file id","test.txt")
asyncio.run(test())

گرفتن لینک دانلود فایل

متد : get_url_file
ورودی

فیلد	نوع	توضیحات
`file_id`	`str`	فایل آیدی

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
  url = await bot.get_url_file("file id")
  print(url)

asyncio.run(test())

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

متد : check_join

این متد بررسی می‌کند که آیا یک کاربر عضو یک کانال مشخص است یا خیر. در صورت ارسال chat_id، اطلاعات چت گرفته شده و بر اساس username یا user_id، وضعیت عضویت کاربر بررسی می‌شود.

ورودی‌ها

فیلد	نوع	توضیحات
`channel_guid`	`str`	شناسه کانال برای بررسی عضویت
`chat_id`	`str or None`	شناسه چت کاربر (اختیاری)

خروجی

نوع	توضیحات
`bool`	اگر کاربر عضو کانال باشد `True`، در غیر این صورت `False`
`list[str]`	در برخی حالت‌ها (مثلاً زمانی که لیست اعضا بازگردانده می‌شود) شامل لیست شناسه‌ها است

مثال

from rubka.asynco import Robot
import asyncio

bot = Robot("my token")

async def test():
    is_joined = await bot.check_join("channel_guid", "chat_id")
    if is_joined:
        print("✅ کاربر در کانال عضو است")
    else:
        print("❌ کاربر در کانال عضو نیست")

asyncio.run(test())