متدهای بات

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

ساخت نمونه¶

این کلاس شامل پارامترهایی برای تنظیم برخی تنظیمات است.

client = BotClient(
    token="YOUR_BOT_TOKEN",
    rate_limit=0.5,          # تأخیر بین درخواست‌ها (ثانیه)
    use_webhook=False        # True برای وبهوک
)

پارامترهای سازنده¶

پارامتر	نوع	پیش‌فرض	توضیحات
`token`	`str`	—	توکن صادرشده توسط روبیکا.
`rate_limit`	`float`	`0.5`	حداقل فاصله بین درخواست‌ها برای جلوگیری از محدودیت.
`use_webhook`	`bool`	`False`	تعیین حالت اجرا (وب‌هوک یا پولینگ).
`timeout`	`float`	`10.0`	تایم‌اوت کلی هر درخواست HTTP.
`connector`	`aiohttp.TCPConnector`	`None`	اشتراک‌گذاری کانکشن با اپلیکیشن‌های دیگر.
`max_retries`	`int`	`3`	تعداد تلاش مجدد برای خطاهای قابل بازیابی.
`backoff_factor`	`float`	`1.0`	ضریب تصاعدی برای تأخیر بین تلاش‌های مجدد.
`retry_statuses`	`Tuple[int,...]`	`(408,425,429,500,502,503,504)`	کدهای HTTP که باعث تلاش مجدد می‌شوند.
`long_poll_timeout`	`float`	`30.0`	افزودن تایم‌اوت به درخواست (`getUpdates`) برای پولینگ طولانی.
`parse_mode`	`ParseMode \\| str`	`ParseMode.MARKDOWN`	حالت پیش‌فرض قالب‌بندی متن.
`fallback_urls`	`Sequence[str]`	`("https://botapi.rubika.ir/v3/{}/",)`	URLهای جایگزین در صورت قطعی آدرس اصلی.
`ignore_timeout`	`bool`	`False`	ادامهٔ تلاش در خطاهای Timeout.
`plugins`	`Sequence[str]`	`None`	فهرست پلاگین‌های فعال شوندهٔ خودکار.
`auto_enable_plugins`	`bool`	`False`	فعال‌سازی خودکار پلاگین‌ها هنگام `start`.
`plugin_entry_point_group`	`str`	`"rubpy.plugins"`	گروه entry point برای کشف پلاگین‌ها.
`plugin_manager_class`	`Type[PluginManager]`	`PluginManager`	کلاس مدیریت پلاگین.

نکته: از کانتکست‌منیجرهای async with BotClient(...) و with BotClient(...) نیز می‌توان برای مدیریت خودکار start/stop استفاده کرد.

چرخهٔ حیات¶

شروع بات¶

متد: start

پارامتر	نوع	توضیحات
—	—	شروع و آماده سازی `BotClient` برای ارتباط با API بات روبیکا

شرح کوتاه: آماده‌سازی سشن HTTP برای ارسال درخواست‌ها.

بازگشت: None (async)

مدیریت پلاگین‌ها¶

متد	توضیحات
`enable_plugins(identifiers: Optional[Sequence[str]] = None)`	پلاگین‌های مشخص‌شده یا فهرست پیش‌فرضِ سازنده را فعال می‌کند. خروجی: `List[Plugin]`.
`disable_plugins(identifiers: Optional[Sequence[str]] = None)`	اگر شناسه ندهید تمام پلاگین‌های فعال غیرفعال می‌شوند.
`register_plugin(plugin_cls, name=None)`	پلاگین جدید را به مدیر داخلی ثبت می‌کند و نام یکتا بازمی‌گرداند.

نکته: این API با سیستم entry points پایتون سازگار است؛ با فعال بودن auto_enable_plugins پلاگین‌ها هنگام start فعال می‌شوند.

مدیریت کیپد چت¶

edit_chat_keypad: برای تغییر کیبورد نمایشی چت.
middleware + process_update: امکان ساخت کیبوردهای تعاملی پیچیده را فراهم می‌کند.

فرمت‌دهی متن و متادیتا¶

_apply_text_formatting: براساس parse_mode متن را به Markdown داخلی تبدیل کرده و metadata را (در صورت ارسال Metadata از rubpy.bot.models) به payload اضافه می‌کند.
حالت‌های معتبر: ParseMode.MARKDOWN, ParseMode.HTML, یا None (متن خام).

غیرفعال کردن بات¶

متد: stop

پارامتر	نوع	توضیحات
—	—	آماده سازی برای متوقف کردن

شرح کوتاه: متوقف کردن client و بستن منابع.

بازگشت: None (async)

اجرای بات¶

متد: run

پارامتر	نوع	توضیحات
`webhook_url`	`Optional[str]`	اگر تعیین شود، وب‌هوک فعال می‌شود
`path`	`Optional[str]`	مسیر وب‌هوک (پیش‌فرض `/webhook`)
`host`	`str`	میزبان برای وب‌سرور (پیش‌فرض `0.0.0.0`)
`port`	`int`	پورت وب‌سرور (پیش‌فرض `8080`)

شرح کوتاه: متد اجرایی اصلی:

اگر webhook_url ارائه شده باشد: یک سرور aiohttp.web برای دریافت وب‌هوک‌ها راه‌اندازی و endpoint‌ها به API ثبت می‌شوند.
در غیر این صورت: وارد حلقهٔ پولینگ (updater) شده و به‌صورت دوره‌ای getUpdates می‌خواند و process_update اجرا می‌شود.

بازگشت: None (async)

نکات: run خودش start() را فراخوانی می‌کند؛ در حالت وب‌هوک باید HTTPS و احیاناً مکانیزم اعتبارسنجی اضافه در نظر گرفته شود.

کانتکست‌منیجر¶

__aenter__ / __aexit__: اجرای خودکار start/stop در محیط‌های async.
__enter__ / __exit__: نسخهٔ همگام برای اسکریپت‌های ساده.

مدیریت سشن و محدودیت سرعت¶

_ensure_session: ایجاد aiohttp.ClientSession با هدر کاربری روبیکا و تنظیمات محدودیت اتصال.
_rate_limit_delay: قبل از هر درخواست، اختلاف زمان آخرین درخواست را بررسی کرده و در صورت نیاز await asyncio.sleep انجام می‌دهد.
_make_request: تمهیدات کامل برای تلاش مجدد، سوییچ خودکار بین BASE_URL و FALLBACK_URLS و تبدیل خطاها به APIException.

اطلاعات پایه‌ای بات¶

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

متد: get_me

پارامتر	نوع	توضیحات
—	—	دریافت اطلاعات بات

شرح کوتاه: دریافت اطلاعات بات.

بازگشت: Bot (async)

مثال:

bot = await client.get_me()

ارسال پیام‌ها و محتوا¶

ارسال پیام متنی¶

متد: send_message

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ مقصد
`text`	`str`	متن پیام
`chat_keypad`	`Optional[Keypad]`	کیپد چت
`inline_keypad`	`Optional[Keypad]`	کیپد اینلاین
`disable_notification`	`bool`	غیرفعال کردن اعلان؟ (پیشفرض False)
`reply_to_message_id`	`Optional[str]`	در جوابِ پیامِ؟
`chat_keypad_type`	`ChatKeypadTypeEnum`	نوع کیپد چت

شرح کوتاه: ارسال پیام های متنی، به همراه پشتیبانی از Keypad و InlineKeypad.

بازگشت: MessageId (async)

مثال:

mid = await client.send_message("chat_id", "سلام!", chat_keypad=keypad, chat_keypad_type=ChatKeypadTypeEnum.SIMPLE)

ارسال استیکر¶

متد: send_sticker

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسه مقصد
`sticker_id`	`str`	شناسهٔ استیکر
سایر پارامترها	—	مشابه `send_message`

شرح کوتاه: ارسال استیکر به چت.

بازگشت: MessageId (async)

ارسال فایل¶

متد: send_file

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسه مقصد
`file`	`Optional[Union[str, Path]]`	مسیر فایل در حافظه برای آپلود (اختیاری)
`file_id`	`Optional[str]`	شناسهٔ فایل اگر از قبل آپلود شده
`text`	`Optional[str]`	به عنوان کپشن فایل
`file_name`	`Optional[str]`	نام فایل هنگام آپلود
`type`	`Literal["File","Image","Voice","Music","Gif","Video"]`	نوع فایل
سایر پارامترها	—	مشابه `send_message`

شرح کوتاه: اگر مسیر فایل به پارامتر file داده شود، ابتدا فایل آپلود شده و سپس ارسال می‌شود، در غیر این صورت، اگر file_id به پارامتر مربوطه داده شود، فایل مستقیما، بدون نیاز به آپلود مجدد ارسال می‌شود.

بازگشت: MessageId (async) — file_id نیز در نتیجه قرار می‌گیرد.

مثال:

mid = await client.send_file("chat_id", file="/tmp/photo.jpg", type="Image", text="عکس")

درخواست ارسال فایل¶

متد: request_send_file

پارامتر	نوع	توضیحات
`type`	`Literal[...]`	نوع فایل مجاز

شرح کوتاه: ارسال درخواست آپلود فایل به سرور روبیکا و دریافت upload_url در صورت مجاز بودن type برای آپلود فایل در سرور روبیکا.

بازگشت: str — upload_url

خطا: اگر type نامعتبر باشد ValueError خواهد داد.

بارگذاری فایل¶

متد: upload_file

پارامتر	نوع	توضیحات
`url`	`str`	آدرس آپلود دریافت‌شده
`file_name`	`str`	نام فایل
`file_path`	`str`	مسیر محلی فایل

شرح کوتاه: آپلود فایل در سرور روبیکا با استفاده از آدرسی که توسط متد request_send_file دریافت کرده‌ایم.

بازگشت: str — file_id

دریافت فایل¶

متد: get_file

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

شرح کوتاه: دریافت آدرس دانلود فایل (download_url) با استفاده از file_id

بازگشت: str — download_url

بارگیری فایل¶

متد: download_file

پارامتر	نوع	توضیحات
`file_id`	`str`	شناسهٔ فایل
`save_as`	`Optional[str]`	مسیر ذخیره (اگر `as_bytes=False`)
`progress`	`Optional[Callable[[int,int],None]]`	کال‌بک پیشرفت (downloaded, total)
`chunk_size`	`int`	اندازهٔ chunk (بایت)
`as_bytes`	`bool`	اگر True، محتوای بایتی برگردانده شود

شرح کوتاه: دانلود فایل از سرور روبیکا با استفاده از آدرس دانلود فایل. اگر as_bytes برابر True باشد، محتوای کامل فایل را به صورت کامل برمی‌گرداند، در غیر این صورت فایل را در حافظه ذخیره می‌کند و مسیر را بازمی‌گرداند.

بازگشت: Union[str, bytes, None] (async)

خطاها: اگر get_file شکست بخورد ValueError پرتاب می‌شود؛ اگر دانلود ناموفق باشد Exception پرتاب می‌شود.

پیام‌های تعاملی¶

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

متد: send_poll

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسه مقصد
`question`	`str`	متن سوال
`options`	`List[str]`	گزینه‌ها

شرح کوتاه: ارسال نظرسنجی.

بازگشت: MessageId (async)

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

متد: send_location

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسه مقصد
`latitude`	`Union[str,float]`	عرض جغرافیایی
`longitude`	`Union[str,float]`	طول جغرافیایی
سایر پارامترها	—	مشابه `send_message`

شرح کوتاه: ارسال موقعیت مکانی.

بازگشت: MessageId (async)

ارسال مخاطب¶

متد: send_contact

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسه مقصد
`first_name`	`str`	نام مخاطب
`last_name`	`str`	نام خانوادگی
`phone_number`	`str`	شماره تلفن
سایر پارامترها	—	مشابه `send_message`

شرح کوتاه: ارسال اطلاعات تماس.

بازگشت: MessageId (async)

خواندن آپدیت‌ها و پولینگ¶

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

متد: get_updates

پارامتر	نوع	توضیحات
`limit`	`int`	تعداد آپدیت‌ها برای درخواست (پیش‌فرض 100)
`offset_id`	`str`	آفست (اختیاری)

شرح کوتاه: فراخوانی سادهٔ getUpdates و تولید لیستی از اشیاء Update/InlineMessage (نسخهٔ نمونه حداقلی پیاده‌سازی شده).

بازگشت: List[Union[Update, InlineMessage]] (async)

حلقهٔ پولینگ پیشرفته¶

متد: updater

پارامتر	نوع	توضیحات
`limit`	`int`	حداکثر تعداد آپدیت در هر درخواست.
`offset_id`	`str`	آیدی ادامهٔ آپدیت‌ها؛ در صورت عدم مقدار از `next_offset_id` داخلی استفاده می‌شود.
`poll_timeout`	`float`	افزودن تایم‌اوت به درخواست (`getUpdates`) برای پولینگ طولانی.

شرح کوتاه: wrapper هوشمند برای getUpdates که موارد قدیمی را حذف کرده، آپدیت‌های حذف‌شده را نادیده می‌گیرد و self.next_offset_id را نگه می‌دارد.

بازگشت: List[Union[Update, InlineMessage]] (async) — هر آپدیت با client تزریق‌شده بازمی‌گردد تا بتوان متدهای پاسخ‌دهی مثل update.reply را صدا زد.

پردازش آپدیت¶

متدها: process_update, _dispatch_update, _filters_pass

process_update: زنجیرهٔ middlewareها را اجرا و سپس _dispatch_update را صدا می‌زند.
_dispatch_update: deduplication بر اساس message_id، اجرای نخستین هندلر که تمام فیلترها را پاس کند و پشتیبانی از هندلرهای sync/async.
_filters_pass: نمونه‌سازی خودکار فیلترهایی که کلاس پاس داده شده‌اند و اجرای await filter.check(update).

دریافت وب‌هوک¶

متد: handle_webhook

تنها درخواست‌های POST را می‌پذیرد و JSON را به Update یا InlineMessage تبدیل می‌کند.
برای هر آپدیت asyncio.create_task(self.process_update(update)) فراخوانی می‌شود تا پاسخ سریع ارسال گردد.
پاسخ موفق: {"status": "OK"}.

نکته: run هنگام فعال بودن وب‌هوک endpointهای ReceiveUpdate, ReceiveInlineMessage, ... را با آدرس جدید ثبت می‌کند.

اطلاعات چت و فوروارد¶

دریافت اطلاعات گفتگو¶

متد: get_chat

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ چت

شرح کوتاه: دریافت اطلاعات گفتگو.

بازگشت: Chat (async)

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

متد: get_chat_administrators

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ گفتگو

شرح کوتاه: دریافت لیست مدیران گروه. (در صورتی که بات در گروه مورد نظر مدیر باشد)

بازگشت: Dict[str, Any] — پاسخ خام API شامل فهرست مدیران.

مثال:

admins = await client.get_chat_administrators("chat_id")

دریافت تعداد اعضای گروه¶

متد: get_chat_member_count

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ گفتگو

شرح کوتاه: دریافت تعداد ممبرهای یک گروه، در صورتی که بات در گروه ادمین باشد.

بازگشت: int — تعداد اعضا.

مثال:

member_count = await client.get_chat_member_count("chat_id")

حذف عضو از گروه¶

متد: ban_chat_member

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ گفتگو
`user_id`	`str`	شناسهٔ کاربر مورد نظر

شرح کوتاه: حذف یک عضو از گروه.

بازگشت: bool — آیا حذف انجام شد؟

مثال:

await client.ban_chat_member("chat_id", "user_id")

حذف عضو از لیست سیاه¶

متد: unban_chat_member

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ گفتگو
`user_id`	`str`	شناسهٔ کاربر مورد نظر

شرح کوتاه: حذف یک عضو از لیست سیاه گروه.

بازگشت: bool — آیا حذف انجام شد؟

مثال:

await client.unban_chat_member("chat_id", "user_id")

دریافت اطلاعات عضو¶

متد: get_chat_member

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ گروه یا کانال
`user_id`	`str`	شناسهٔ کاربر مورد نظر

شرح کوتاه: دریافت اطلاعات عضو از گروه یا کانال در صورت عضو بودن.

بازگشت: ChatMember — اطلاعات عضو.

مثال:

await client.get_chat_member("chat_id", "user_id")

ارتقای عضو¶

متد: promote_chat_member

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسهٔ گروه یا کانال
`user_id`	`str`	شناسهٔ کاربر مورد نظر

شرح کوتاه: ارتقا از عضو به مدیر در گروه یا کانال.

بازگشت: bool — آیا ارتقا انجام شد؟

مثال:

await client.promote_chat_member("chat_id", "user_id")

تنظیم دسترسی کاربران در گفتگو¶

متد: set_chat_permissions

پارامتر	نوع	توضیحات
`chat_id`	`str`	شناسه گروه

شرح کوتاه: تنظیم دسترسی های کاربران در گفتگو.

بازگشت: bool — آیا تنظیم دسترسی انجام شد؟

مثال:

await client.set_chat_permissions("chat_id", ...)

ثبت هندلرها و فیلترها¶

دکوراتور هندلر آپدیت¶

متد: on_update

پارامتر	نوع	توضیحات
`*filters`	`Filter...`	مجموعه‌ای از فیلترها (کلاس یا نمونه)

شرح کوتاه: دکوراتور on_update یک دکوراتور سطح بالا برای ثبت هندلرها به همراه فیلترها است. شما میتوانید هندلرهای async و sync را همزمان در کنار یکدیگر استفاده کنید.

مثال:

@client.on_update()
async def echo(client, update):
    if update.new_message and update.new_message.text:
        await update.reply("pong")

افزودن هندلر¶

متد: add_handler

پارامتر	نوع	توضیحات
`handler`	`Callable`	تابعی با امضای `(bot, update)`
`*filters`	`Filter...`	فیلترهای اجرایی مشابه `on_update`

بازگشت: str — کلید یکتا برای حذف بعدی.

مثال:

async def hello_world(client, update):
    if update.new_message and update.new_message.text:
        await update.reply("Hello, World!")

client.add_handler(hello_world, filters.commands("hello"))
my_handler = client.add_handler(hello_world)

حذف هندلر¶

متد: remove_handler

پارامتر	نوع	توضیحات
`handler_key`	`str`	خروجی `add_handler` یا `on_update`.
`handler`	`Callable`	(اختیاری) حذف فقط یک تابع خاص زیر همان کلید.

بازگشت: bool — آیا هندلری حذف شد؟

مثال:

my_handler = client.add_handler(hello_world)
client.remove_handler(my_handler)

به محض شروع¶

متد: on_start

مثال:

@app.on_start()
async def greet(bot):
    print("Bot started...")
    print(await bot.get_me())

به محض خاموش شدن¶

متد: on_shutdown

مثال:

@app.on_shutdown()
async def bye(bot):
    print("👋 Bot is shutting down!")

میان‌افزار (Middleware)¶

متد: middleware

پارامتر	نوع	توضیحات
—	—	این متد دکوراتور است؛ تابعی را می‌گیرد که قبل از رسیدن هر آپدیت به هندلرها اجرا می‌شود.

شرح کوتاه: میان‌افزارها لایه‌هایی هستند که روی جریان آپدیت‌ها قرار می‌گیرند. هر آپدیت قبل از رسیدن به هندلرها از زنجیرهٔ middlewareها عبور می‌کند. هر middleware سه آرگومان دریافت می‌کند:

async def middleware(bot, update, call_next):
    ...
    await call_next()   # ادامه مسیر به middleware بعدی یا هندلر اصلی

bot: نمونه‌ی BotClient
update: شیء Update یا InlineMessage
call_next: تابعی برای ارسال کنترل به middleware بعدی یا در نهایت هندلر

اگر یک middleware await call_next() را صدا نزند، زنجیره متوقف می‌شود و هندلرها اجرا نمی‌شوند (برای مسدود کردن یا فیلتر کردن مفید است).

بازگشت: None (async)

مثال‌های کاربردی¶

مثال ۱ — ارسال پیام ساده¶

client = BotClient("MY_TOKEN")
await client.start()
mid = await client.send_message("chat_id", "سلام، ربات آزمایشی!")
await client.stop()

مثال ۲ — آپلود و ارسال عکس¶

mid = await client.send_file("chat_id", file="/tmp/photo.jpg", type="Image", text="عکس تست")

مثال ۳ — ثبت هندلر و اجرای پولینگ¶

@client.on_update()
async def echo(client, update):
    if update.new_message and update.new_message.text:
        await update.reply("دریافت شد: " + update.new_message.text)

await client.run()  # اجرای پولینگ (یا use webhook اگر webhook_url داده باشد)

مثال ۴ — اجرا با وب‌هوک¶

# فرض: سرویس شما در https://example.com است
await client.run(webhook_url="https://example.com", path="/rubika/webhook", host="0.0.0.0", port=8080)

مثال ۵ — استفاده از پلاگین و middleware¶

client = BotClient("TOKEN", auto_enable_plugins=True, plugins=["echo"])

@client.middleware()
async def logger(bot, update, call_next):
    print("Update arrived", update.type)
    await call_next()

await client.run()