نسخه جدید داکیومنت روبکا رفتن به نسخه قدیمی داکیومنت

rubka - rubika library official BotApi

مستندات کامل متدها — ساخت ربات‌های قدرتمند در پیام‌رسان روبیکا

نسخه 2.0 | async/await

فهرست سریع متدها

__init__
سازنده کلاس Robot — مقداردهی اولیه با توکن و تنظیمات پیشرفته
پارامترنوعتوضیحات
tokenstrتوکن ربات دریافتی از روبیکا (اجباری)
session_namestr | Noneنام نشست برای ذخیره اطلاعات
authstr | Noneاوث (Authentication)
Keystr | Noneکلید خصوصی (Private Key)
platformstrپلتفرم (پیشفرض "web")
web_hookstr | Noneآدرس وب‌هوک برای دریافت آپدیت
timeoutintزمان تایم‌اوت درخواست‌ها (پیشفرض 10)
show_progressboolنمایش نوار پیشرفت آپلود/دانلود
raise_errorsboolدر صورت خطا استثنا پرتاب شود (پیشفرض True)
proxystr | Noneآدرس پروکسی (مثال: http://user:pass@host:port)
retriesintتعداد دفعات تلاش مجدد (پیشفرض 2)
retry_delayfloatزمان استراحت بین تلاش مجدد (پیشفرض 0.5 ثانیه)
user_agentstr | Noneاطلاعات مرورگر درخواست‌دهنده
safeSendModeboolحالت ارسال ایمن (اجرای ترتیبی دستورات)
max_cache_sizeintحداکثر اندازه کش برای پیام‌ها (پیشفرض 2000)
max_msg_ageintحداکثر عمر پیام در صف (به ثانیه، پیشفرض 60)
chunk_sizeintسایز تکه‌های آپلود (پیشفرض 64KB)
parse_modeLiteral["HTML", "Markdown"] | Noneحالت پارس کردن متن (پیشفرض "Markdown")
api_endpointLiteral["botapi", "messenger"]نقطه پایانی API (پیشفرض "botapi")
target_languagestr | Noneزبان هدف (پیشفرض "en")
save_interval_offset_idint | Noneفاصله ذخیره‌سازی offset_id (پیشفرض 120)
enable_offsetbool | Noneفعالسازی offset (پیشفرض False)
show_loggerbool | Noneنمایش لاگر (پیشفرض False)
Noneشیء Robot ساخته می‌شود
from rubka import Robot

bot = Robot(
    token="YOUR_TOKEN",
    session_name="my_session",
    timeout=15,
    show_progress=True,
    retries=3,
    safeSendMode=True,
    parse_mode="HTML",
    api_endpoint="botapi"
)
get_me
دریافت اطلاعات بات جاری
ندارد
dictشامل id، username، first_name، last_name، is_bot
me = await bot.get_me()
print(me['username'])
run
اجرای حلقه اصلی ربات با پشتیبانی از وب‌هوک یا لانگ پولینگ
پارامترنوعتوضیحات
debugboolفعالسازی حالت اشکال‌زدایی
sleep_timefloatتأخیر بین درخواست‌ها (پیشفرض 0.1)
allowed_update_typeslist[str] | Noneفیلتر نوع آپدیت (مثل NewMessage)
process_in_backgroundboolپردازش در پس‌زمینه با صف
Noneربات تا زمان قطع اجرا می‌شود
await bot.run(debug=True, sleep_time=0.05)
send_message
ارسال پیام متنی با کیبورد معمولی یا شیشه‌ای
پارامترنوعتوضیحات
chat_idstrشناسه چت
textstrمتن پیام
inline_keypaddict | Noneدکمه‌های شیشه‌ای
chat_keypaddict | Noneدکمه های کیبوردی
reply_to_message_idstr | Noneپاسخ به پیام مشخص
disable_notificationboolغیرفعال کردن اعلان
strشناسه پیام ارسال‌شده
from rubka import Robot,Message
from rubka.button import ChatKeypadBuilder,InlineBuilder


bot = Robot(
    "token",
    #web_hook="https://....." #برای دریافت اپدیت های اینلاین نیاز به وبهوک هست
)

#دکمه کیبورد
chat_keypad = (
    ChatKeypadBuilder()
    .row(
        ChatKeypadBuilder().button(id="one", text="button one"),
        ChatKeypadBuilder().button(id="two", text="button two")
    )
    .row( #برای اضافه شدن یه ردیف جدید باید row کنید
        ChatKeypadBuilder().button(id="three", text="button three")
    )
    .build()
)

#دکمه اینلاین (شیشه ای) 
inline_keypad = (
    InlineBuilder()
    .row(
        InlineBuilder().button_simple(id="one", text="button one"),
        InlineBuilder().button_simple(id="two", text="button two")
    )
    .row(  #برای اضافه شدن یه ردیف جدید باید row کنید
        InlineBuilder().button_simple(id="three", text="button three")
    )
    .build()
)

@bot.on_message()
async def start(bot:Robot,message:Message):
    await message.reply(
            "ارسال کیبورد",
            chat_keypad=chat_keypad,
        )
    #await bot.send_message(message.chat_id,"ارسال کیبورد",chat_keypad=chat_keypad) #مثال با سند مسیج


    await message.reply(
            "ارسال اینلاین",
            inline_keypad=inline_keypad,
        )
    #await bot.send_message(message.chat_id,"ارسال اینلاین",inline_keypad=inline_keypad) #مثال با سند مسیج

@bot.on_callback('one')
async def btn_help(bot: Robot, message: Message):
    await message.answer("پاسخ به دکمه یک")

@bot.on_callback('two')
async def btn_help(bot: Robot, message: Message):
    await message.answer("پاسخ به دکمه دو")

@bot.on_callback('three')
async def btn_help(bot: Robot, message: Message):
    await message.answer("پاسخ به دکمه سه")

bot.run()
send_file / send_document
ارسال فایل (سند، هر نوع فایل)
پارامترنوعتوضیحات
chat_idstrشناسه چت
pathstr | Pathمسیر فایل یا URL
file_namestr | Noneنام فایل (اختیاری)
captionstr | Noneتوضیحات
strشناسه پیام
await bot.send_file("chat_id", "document.pdf", caption="فایل پی دی اف")
send_image
ارسال عکس
chat_idstrشناسه چت
pathstrمسیر عکس
captionstr | Noneکپشن
strmessage_id
await bot.send_image("chat", "photo.jpg", caption="منظره زیبا")
send_video
ارسال ویدیو
chat_idstr
pathstr
captionstr | None
str
await bot.send_video("chat", "video.mp4")
send_voice
ارسال پیام صوتی
chat_idstr
pathstr
str
await bot.send_voice("chat", "voice.ogg")
send_gif
ارسال گیف
chat_idstr
pathstr
str
await bot.send_gif("chat", "animation.gif")
send_poll
ارسال نظرسنجی (Regular یا Quiz)
پارامترنوعتوضیحات
chat_idstr
questionstrسوال
optionslist[str]گزینه‌ها
typeLiteral["Regular","Quiz"]نوع نظرسنجی
correct_option_indexint | Noneشاخص پاسخ صحیح (Quiz)
is_anonymousboolناشناس بودن (پیشفرض True)
strشناسه پیام نظرسنجی
await bot.send_poll("chat", "رنگ مورد علاقه؟", ["قرمز","آبی"], type="Regular")
send_location
ارسال موقعیت مکانی
chat_idstr
latitudestrعرض جغرافیایی
longitudestrطول جغرافیایی
strmessage_id
await bot.send_location("chat", "35.6892", "51.3890")
send_contact
ارسال مخاطب
chat_idstr
first_namestr
last_namestr
phone_numberstr
str
await bot.send_contact("chat", "علی", "رضایی", "09123456789")
edit_message_text
ویرایش متن پیام
chat_idstr
message_idstr
textstr
boolموفقیت
await bot.edit_message_text("chat", "msg_id", "متن جدید")
edit_inline_keypad
ویرایش کیبورد شیشه‌ای پیام
chat_idstr
message_idstr
inline_keypaddictکیبورد جدید
textstr | Noneمتن جدید (اختیاری)
bool
await bot.edit_inline_keypad("chat", "msg_id", new_keypad)
delete_message
حذف پیام
chat_idstr
message_idstr
dict
await bot.delete_message("chat", "msg_id")
forward_message
فوروارد پیام به چت دیگر
from_chat_idstr
message_idstr
to_chat_idstr
strشناسه پیام جدید
await bot.forward_message("from_chat", "msg_id", "to_chat")
copy_message
کپی محتوای پیام به چت دیگر (بدون نشانی فرستنده)
to_chat_idstr
message_idstrپیام اصلی (اختیاری)
strmessage_id جدید
await message.copy_message("target_chat")
pin_chat_message
سنجاق کردن پیام
chat_idstr
message_idstr
dict
await bot.pin_chat_message("group", "msg_id")
unpin_chat_message
برداشتن سنجاق پیام
chat_idstr
message_idstr
dict
await bot.unpin_chat_message("group", "msg_id")
get_chat
دریافت اطلاعات چت (مدل Chat)
chat_idstr
Chatشیء حاوی اطلاعات چت
chat = await bot.get_chat("chat_id")
print(chat.title)
get_chat_info
دریافت اطلاعات کامل چت (دیکشنری)
dictشامل title، type، description، members_count
info = await bot.get_chat_info("channel_id")
get_chat_admins
دریافت لیست مدیران چت
chat_idstrشناسه گروه یا کانال
list[dict]لیست مدیران
admins = await bot.get_chat_admins("group_id")
get_chat_members
دریافت اعضای چت (با صفحه‌بندی)
dictلیست اعضا
members = await bot.get_chat_members("group", start_id="...")
set_chat_title
تغییر عنوان گروه یا کانال
chat_idstr
titlestrعنوان جدید
dict
await bot.set_chat_title("group", "عنوان جدید")
set_chat_description
تغییر توضیحات چت
chat_idstr
descriptionstr
dict
await bot.set_chat_description("group", "توضیحات جدید")
ban_member_chat
بن کردن کاربر در چت
chat_idstr
user_idstr
dict
await bot.ban_member_chat("group", "user_id")
unban_chat_member
لغو بن کاربر
chat_idstr
user_idstr
dict
await bot.unban_chat_member("group", "user_id")
get_all_member
دریافت تمام اعضای کانال (حتی بیش از ۲۰۰ عضو)
channel_guidstr
search_textstr | None
just_get_guidsbool
listلیست اعضا یا لیست guidها
members = await bot.get_all_member("channel_id", just_get_guids=True)
check_join
بررسی عضویت کاربر در کانال
channel_guidstr
chat_idstr
bool
is_joined = await bot.check_join("channel", "user_id")
get_username
گرفتن نام کاربری چت
chat_idstr
str | None
username = await bot.get_username("chat_id")
get_name
گرفتن نام کامل چت/کاربر
chat_idstr
str
name = await bot.get_name("user_id")
get_avatar_me
گرفتن آواتار بات (لینک دانلود)
save_asstr | Noneمسیر ذخیره (اختیاری)
strلینک آواتار
url = await bot.get_avatar_me(save_as="avatar.png")
get_message
دریافت اطلاعات کامل یک پیام با استفاده از chat_id و message_id
پارامترنوعتوضیحات
chat_idstrشناسه چت
message_idstrشناسه پیام
dictاطلاعات کامل پیام (متن، فرستنده، زمان، نوع رسانه و...)
msg_data = await bot.get_message("chat_id", "message_id")
print(msg_data['text'])
set_chat_photo
تنظیم تصویر پروفایل گروه یا کانال
پارامترنوعتوضیحات
chat_idstrشناسه چت
photo_pathstrمسیر فایل تصویر جدید
dictنتیجه عملیات
await bot.set_chat_photo("group_id", "new_photo.jpg")
on_message_reply
هندلر پیام‌هایی که در پاسخ به پیام دیگری ارسال شده‌اند
پارامترنوعتوضیحات
filterscallable | Noneتابع فیلتر سفارشی
commandslist[str] | Noneلیست دستورات
Messageشیء پیام
@bot.on_message_reply()
async def reply_handler(bot, message):
    await message.reply("شما به پیام دیگری پاسخ دادید")
on_message_media
هندلر پیام‌های حاوی رسانه (عکس، ویدیو، گیف)
پارامترنوعتوضیحات
filterscallable | Noneتابع فیلتر سفارشی
Messageشیء پیام
@bot.on_message_media()
async def media_handler(bot, message):
    await message.reply("رسانه دریافت شد 📷")
on_message_sticker
هندلر پیام‌های حاوی استیکر
filterscallable | Noneتابع فیلتر سفارشی
Messageشیء پیام
@bot.on_message_sticker()
async def sticker_handler(bot, message):
    await message.reply("استیکر قشنگی بود 😊")
on_message_contact
هندلر پیام‌های حاوی مخاطب
filterscallable | Noneتابع فیلتر سفارشی
Messageشیء پیام
@bot.on_message_contact()
async def contact_handler(bot, message):
    await message.reply("مخاطب دریافت شد 👤")
on_message_location
هندلر پیام‌های حاوی موقعیت مکانی
filterscallable | Noneتابع فیلتر سفارشی
Messageشیء پیام
@bot.on_message_location()
async def location_handler(bot, message):
    await message.reply("موقعیت دریافت شد 📍")
on_message_poll
هندلر پیام‌های حاوی نظرسنجی
filterscallable | Noneتابع فیلتر سفارشی
Messageشیء پیام
@bot.on_message_poll()
async def poll_handler(bot, message):
    await message.reply("نظرسنجی جدید دریافت شد 📊")
on_message_forwarded
هندلر پیام‌های فوروارد شده از چت دیگر
filterscallable | Noneتابع فیلتر سفارشی
Messageشیء پیام
@bot.on_message_forwarded()
async def forwarded_handler(bot, message):
    await message.reply("این پیام فوروارد شده است 🔁")
on_message_text
هندلر اختصاصی پیام‌های متنی
پارامترنوعتوضیحات
filterscallable | Noneتابع فیلتر سفارشی
commandslist[str] | Noneلیست دستورات
Messageشیء پیام
@bot.on_message_text(commands=["help"])
async def help_command(bot, message):
    await message.reply("راهنمای ربات...")
on_message_file
هندلر پیام‌های حاوی فایل (سند، فایل ضمیمه)
filterscallable | Noneتابع فیلتر سفارشی
Messageشیء پیام
@bot.on_message_file()
async def file_handler(bot, message):
    await message.reply("فایل دریافت شد 📁")
get_upload_url
دریافت آدرس آپلود فایل
media_typeLiteral["File","Image","Voice","Music","Gif","Video"]
strلینک آپلود
upload_url = await bot.get_upload_url("Image")
upload_media_file
آپلود فایل روی سرور روبیکا
upload_urlstr
namestr
pathstr | Path
strfile_id
file_id = await bot.upload_media_file(url, "photo.jpg", "local.jpg")
download
دانلود فایل با file_id
file_idstr
save_asstr
chunk_sizeint
strمسیر ذخیره شده
await bot.download("file_id", "downloaded.pdf")
get_url_file
گرفتن لینک مستقیم دانلود فایل
file_idstr
str
link = await bot.get_url_file("file_id")
close_poll
بستن نظرسنجی فعال
chat_idstr
message_idstr
dict
await bot.close_poll("chat", "poll_msg_id")
set_commands
تنظیم منوی دستورات بات
commandslist[dict]لیست دستورات با کلیدهای command و description
bool
await bot.set_commands([{"command":"start","description":"شروع"}])
update_webhook
دریافت آپدیت از وب‌هوک
offset_idstr | None
limitint | None
list[dict]
updates = await bot.update_webhook(limit=10)
get_updates
دریافت آپدیت‌ها (لانگ پولینگ)
offset_idstr | None
limitint | None
dict
updates = await bot.get_updates(limit=5)
export_chat_invite_link
ساخت لینک دعوت چت
chat_idstr
strلینک دعوت
link = await bot.export_chat_invite_link("group")
revoke_chat_invite_link
باطل کردن لینک دعوت
chat_idstr
linkstr
dict
await bot.revoke_chat_invite_link("group", "https://rubika.ir/...")
send_bulk_message
ارسال گروهی پیام به چند چت
chat_idslist[str]
textstr
concurrencyint
dict[str, dict]
results = await bot.send_bulk_message(["id1","id2"], "متن گروهی")
delete_bulk_message
حذف گروهی پیام‌ها در یک چت
chat_idstr
message_idslist[str]
list
await bot.delete_bulk_message("chat", ["msg1","msg2"])
edit_bulk_message
ویرایش گروهی پیام‌ها
chat_idstr
messagesdict[str, str]کلید: message_id، مقدار: متن جدید
list
await bot.edit_bulk_message("chat", {"msg1":"متن جدید"})
delete_after
حذف پیام پس از تأخیر زمانی
chat_idstr
message_idstr
delayintتأخیر به ثانیه
asyncio.Task
task = await bot.delete_after("chat", "msg_id", delay=10)
edit_after
ویرایش پیام پس از تأخیر
chat_idstr
message_idstr
textstr
delayint
asyncio.Task
await bot.edit_after("chat", "msg_id", "جدید", delay=5)
send_scheduled_message
ارسال پیام زمانبندی‌شده
chat_idstr
textstr
delayint
dict
await bot.send_scheduled_message("chat", "پیام بعد 20 ثانیه", delay=20)
disable_inline_keyboard
غیرفعال کردن کیبورد شیشه‌ای پیام
chat_idstr
message_idstr
textstr
dict
await bot.disable_inline_keyboard("chat", "msg_id", text="غیرفعال شد")
close
بستن نشست aiohttp
None
await bot.close()
on_message / on_update
دکوریتور عمومی برای دریافت همه پیام‌ها
filterscallable | None
commandslist[str] | None
Message
@bot.on_message(commands=["start"])
async def start(bot, message):
    await message.reply("شروع شد")
on_callback / on_callback_query
دریافت کلیک دکمه‌های شیشه‌ای
button_idstr | Noneفیلتر بر اساس آیدی دکمه
InlineMessage
@bot.on_callback(button_id="info")
async def info_callback(query):
    await query.answer("اطلاعات محصول")
on_edited_message
هندلر پیام ویرایش‌شده
filterscallable | None
commandslist[str] | None
Message
@bot.on_edited_message()
async def edited(bot, msg):
    await msg.reply("ویرایش شد")
on_message_private
هندلر پیشرفته پیام‌های خصوصی با فیلترهای متنوع
chat_idstr | list | None
commandslist[str] | None
allow_filesbool
containsstr | None
Message
@bot.on_message_private(contains="سلام")
async def hello_private(bot, msg):
    await msg.reply("سلام کاربر عزیز")
on_message_group
هندلر پیشرفته پیام‌های گروهی
allow_forwardedbool
min_text_lengthint | None
Message
@bot.on_message_group(allow_stickers=False)
async def group_handler(bot, msg):
    await msg.reply("پیام گروهی")
on_message_channel
هندلر پیام‌های کانال
chat_idstr | list | None
commandslist[str] | None
Message
@bot.on_message_channel(contains="اطلاعیه")
async def announce(bot, msg):
    print("اطلاعیه جدید:", msg.text)
remove_handler
حذف یک هندلر از لیست
funccallableتابع هندلر
None
bot.remove_handler(my_handler_function)

مستندات کامل متدهای کتابخانه روبیکا — تمام متدها async/await · پشتیبانی از وب‌هوک و لانگ پولینگ

طراحی شده با استانداردهای مدرن برای توسعه‌دهندگان حرفه‌ای