📘 مستندات کامل BaleNull
توسط Henry (آرتین طهماسبی) • بیش از ۱۲۰ متد • توضیحات کامل و مثال
معرفی کتابخانه
BaleNull یک کتابخانه قدرتمند و آسان برای ساخت ربات در پیامرسان بله است. این کتابخانه توسط Henry (آرتین طهماسبی) توسعه داده شده و تمام امکانات API رسمی بله را پوشش میدهد.
✨ ویژگیهای کلیدی:
- ✅ بیش از ۱۲۰ متد کاربردی
- ✅ پشتیبانی از مینیاپ (Web App)
- ✅ کیبوردهای خطی و شیشهای
- ✅ ارسال انواع فایل (عکس، ویدیو، صدا، سند)
- ✅ مدیریت کامل چت (بن، آنبن، ترفیع، محدودیت)
- ✅ نظرسنجی، استیکر، بازی و پرداخت
- ✅ وبهوک و Polling
نصب و راهاندازی
pip install balenull
برای نصب آخرین نسخه از PyPI استفاده کنید.
ساخت Client
from balenull import Client
bot = Client("YOUR_BOT_TOKEN")
توکن ربات خود را از @BotFather در بله دریافت کنید.
هندلر پیام
@bot.on_message()
async def handler(message):
print(f"پیام از {message.from_user.first_name}: {message.text}")
هندلرها توابع ناهمگام (async) هستند و یک شیء Message دریافت میکنند.
شیء Message
ویژگیهای مهم شیء message:
message.text- متن پیامmessage.chat_id- شناسه چتmessage.message_id- شناسه پیامmessage.from_user- اطلاعات فرستندهmessage.caption- کپشن (برای رسانهها)message.photo- لیست عکسهاmessage.video- اطلاعات ویدیوmessage.audio- اطلاعات صداmessage.document- اطلاعات فایلmessage.reply_to_message- پیام پاسخ داده شده
📤 متدهای ارسال پیام (۱۷ متد)
send_message
ارسال پیام متنی با پشتیبانی از HTML و Markdown. پارامترهای مهم: chat_id, text, parse_mode, reply_to_message_id, reply_markup
مثال:
await bot.send_message(chat_id, "سلام", parse_mode="HTML")
send_photo
ارسال عکس با کپشن و قابلیت اسپویلر. پارامترها: chat_id, photo, caption, has_spoiler
مثال:
await bot.send_photo(chat_id, "photo.jpg", caption="عکس زیبا")
send_audio
ارسال فایل صوتی با عنوان، خواننده و مدت زمان. پارامترها: chat_id, audio, title, performer, duration
مثال:
await bot.send_audio(chat_id, "song.mp3", title="آهنگ", performer="خواننده")
send_video
ارسال ویدیو با پشتیبانی از استریم، اسپویلر و ابعاد. پارامترها: chat_id, video, caption, width, height, supports_streaming
مثال:
await bot.send_video(chat_id, "video.mp4", supports_streaming=True)
send_document
ارسال هر نوع فایل (PDF، ZIP، DOCX و غیره). پارامترها: chat_id, document, caption, thumb
مثال:
await bot.send_document(chat_id, "file.pdf", caption="مستند")
send_animation
ارسال فایل GIF یا انیمیشن. پارامترها: chat_id, animation, caption, duration, width, height
مثال:
await bot.send_animation(chat_id, "gif.gif", caption="حرکت")
send_voice
ارسال پیام صوتی (ویس) با مدت زمان. پارامترها: chat_id, voice, caption, duration
مثال:
await bot.send_voice(chat_id, "voice.ogg")
send_sticker
ارسال استیکر (WEBP یا PNG). پارامترها: chat_id, sticker
مثال:
await bot.send_sticker(chat_id, "sticker.webp")
send_location
ارسال موقعیت مکانی با طول و عرض جغرافیایی. پارامترها: chat_id, latitude, longitude
مثال:
await bot.send_location(chat_id, 35.6892, 51.3890)
send_contact
ارسال مخاطب با شماره و نام. پارامترها: chat_id, phone_number, first_name, last_name
مثال:
await bot.send_contact(chat_id, "09123456789", "علی")
send_poll
ارسال نظرسنجی با گزینهها و تنظیمات. پارامترها: chat_id, question, options, is_anonymous, allows_multiple_answers
مثال:
await bot.send_poll(chat_id, "سوال؟", ["گزینه۱", "گزینه۲"])
send_dice
ارسال تاس یا بازی شانس (🎲، 🎯، 🏀، ⚽، 🎳، 🎰). پارامترها: chat_id, emoji
مثال:
await bot.send_dice(chat_id, emoji="🎲")
send_media_group
ارسال گروهی عکسها یا ویدیوها (آلبوم). پارامترها: chat_id, media (لیست InputMedia)
مثال:
await bot.send_media_group(chat_id, [media1, media2])
send_video_note
ارسال ویدیوی گرد (دایرهای). پارامترها: chat_id, video_note, duration, length
مثال:
await bot.send_video_note(chat_id, "video.mp4", length=240)
send_invoice
ارسال فاکتور برای پرداخت. پارامترها: chat_id, title, description, payload, currency, prices
مثال:
await bot.send_invoice(chat_id, "محصول", "توضیحات", "payload", "IRT", [{"label": "قیمت", "amount": 10000}])
send_game
ارسال بازی. پارامترها: chat_id, game_short_name
مثال:
await bot.send_game(chat_id, "game_name")
send_chat_action
نمایش وضعیت تایپ، آپلود، ضبط و ... پارامترها: chat_id, action (typing, upload_photo, record_video, ...)
مثال:
await bot.send_chat_action(chat_id, "typing")✏️ ویرایش و حذف (۸ متد)
edit_message_text
ویرایش متن یک پیام قبلی. پارامترها: chat_id, message_id, text, parse_mode
مثال:
await bot.edit_message_text(chat_id, message_id, "متن جدید")
edit_message_caption
ویرایش کپشن رسانه. پارامترها: chat_id, message_id, caption, parse_mode
مثال:
await bot.edit_message_caption(chat_id, message_id, "کپشن جدید")
edit_message_reply_markup
ویرایش کیبورد یا دکمههای پیام. پارامترها: chat_id, message_id, reply_markup
مثال:
await bot.edit_message_reply_markup(chat_id, message_id, new_markup)
edit_message_media
تعویض رسانه پیام با رسانه جدید. پارامترها: chat_id, message_id, media (InputMedia)
مثال:
await bot.edit_message_media(chat_id, message_id, new_media)
edit_message_live_location
ویرایش موقعیت زنده. پارامترها: chat_id, message_id, latitude, longitude
مثال:
await bot.edit_message_live_location(chat_id, message_id, 35.6892, 51.3890)
stop_message_live_location
توقف بهروزرسانی موقعیت زنده. پارامترها: chat_id, message_id
مثال:
await bot.stop_message_live_location(chat_id, message_id)
delete_message
حذف یک پیام از چت. پارامترها: chat_id, message_id
مثال:
await bot.delete_message(chat_id, message_id)
delete_webhook
حذف وبهوک. پارامترها: drop_pending_updates
مثال:
await bot.delete_webhook(drop_pending_updates=True)👍 واکنشها و گزارش (۷ متد)
set_message_reaction
تنظیم واکنش روی پیام با ایموجی. پارامترها: chat_id, message_id, reaction (لیست ایموجیها)
مثال:
await bot.set_message_reaction(chat_id, message_id, ["❤️", "👍"])
get_message_reaction
دریافت واکنشهای یک پیام. پارامترها: chat_id, message_id
مثال:
await bot.get_message_reaction(chat_id, message_id)
report_message
گزارش پیام به ادمینهای بله. پارامترها: chat_id, message_id
مثال:
await bot.report_message(chat_id, message_id)
view_message
علامت مشاهده روی پیام بگذارید. پارامترها: chat_id, message_id
مثال:
await bot.view_message(chat_id, message_id)
add_to_saved
ذخیره پیام در بخش ذخیرهشدهها. پارامترها: chat_id, message_id
مثال:
await bot.add_to_saved(chat_id, message_id)
report_chat
گزارش چت به ادمینهای بله. پارامترها: chat_id, reason
مثال:
await bot.report_chat(chat_id, "هرزنامه")
pin_message
سنجاق کردن پیام در چت. پارامترها: chat_id, message_id, disable_notification
مثال:
await bot.pin_message(chat_id, message_id)👥 مدیریت چت (۳۲ متد)
get_chat
دریافت اطلاعات کامل چت (نوع، عنوان، توضیحات، عکس). پارامترها: chat_id
مثال:
await bot.get_chat(chat_id)
get_me
دریافت اطلاعات ربات (آیدی، نام، یوزرنیم، توضیحات). بدون پارامتر
مثال:
await bot.get_me()
get_chat_administrators
دریافت لیست ادمینهای چت با نقشهای آنها. پارامترها: chat_id
مثال:
await bot.get_chat_administrators(chat_id)
get_chat_member_count
تعداد اعضای چت (گروه یا کانال). پارامترها: chat_id
مثال:
await bot.get_chat_member_count(chat_id)
get_chat_member
اطلاعات یک عضو خاص (نقش، وضعیت). پارامترها: chat_id, user_id
مثال:
await bot.get_chat_member(chat_id, user_id)
forward_message
فوروارد پیام از یک چت به چت دیگر. پارامترها: chat_id, from_chat_id, message_id
مثال:
await bot.forward_message(to_chat, from_chat, message_id)
copy_message
کپی محتوای پیام بدون شناسه اصلی. پارامترها: chat_id, from_chat_id, message_id
مثال:
await bot.copy_message(to_chat, from_chat, message_id)
unpin_message
برداشتن سنجاق یک پیام. پارامترها: chat_id, message_id
مثال:
await bot.unpin_message(chat_id, message_id)
unpin_all_chat_messages
برداشتن سنجاق همه پیامهای چت. پارامترها: chat_id
مثال:
await bot.unpin_all_chat_messages(chat_id)
leave_chat
خروج از چت (گروه یا کانال). پارامترها: chat_id
مثال:
await bot.leave_chat(chat_id)
set_chat_title
تغییر عنوان چت. پارامترها: chat_id, title
مثال:
await bot.set_chat_title(chat_id, "عنوان جدید")
set_chat_description
تغییر توضیحات چت. پارامترها: chat_id, description
مثال:
await bot.set_chat_description(chat_id, "توضیحات جدید")
set_chat_photo
تغییر عکس چت. پارامترها: chat_id, photo
مثال:
await bot.set_chat_photo(chat_id, "photo.jpg")
delete_chat_photo
حذف عکس چت. پارامترها: chat_id
مثال:
await bot.delete_chat_photo(chat_id)
set_chat_permissions
تنظیم دسترسیهای چت (ارسال پیام، رسانه و ...). پارامترها: chat_id, permissions
مثال:
await bot.set_chat_permissions(chat_id, {"can_send_messages": True})
export_chat_invite_link
دریافت لینک دعوت چت. پارامترها: chat_id
مثال:
await bot.export_chat_invite_link(chat_id)
create_chat_invite_link
ساخت لینک دعوت جدید با تنظیمات (مدت زمان، تعداد استفاده). پارامترها: chat_id, expire_date, member_limit
مثال:
await bot.create_chat_invite_link(chat_id, expire_date=time.time()+3600)
edit_chat_invite_link
ویرایش لینک دعوت موجود. پارامترها: chat_id, invite_link, expire_date, member_limit
مثال:
await bot.edit_chat_invite_link(chat_id, "link", member_limit=10)
revoke_chat_invite_link
لغو و غیرفعال کردن لینک دعوت. پارامترها: chat_id, invite_link
مثال:
await bot.revoke_chat_invite_link(chat_id, "link")
ban_chat_member
بن کردن کاربر از چت (با امکان حذف پیامها). پارامترها: chat_id, user_id, until_date, revoke_messages
مثال:
await bot.ban_chat_member(chat_id, user_id, until_date=time.time()+86400)
unban_chat_member
لغو بن کاربر. پارامترها: chat_id, user_id, only_if_banned
مثال:
await bot.unban_chat_member(chat_id, user_id)
restrict_chat_member
محدود کردن کاربر در چت (تنظیم دسترسیها). پارامترها: chat_id, user_id, permissions, until_date
مثال:
await bot.restrict_chat_member(chat_id, user_id, {"can_send_messages": False})
promote_chat_member
ترفیع کاربر به ادمین با تنظیم حقوق. پارامترها: chat_id, user_id, can_change_info, can_delete_messages, ...
مثال:
await bot.promote_chat_member(chat_id, user_id, can_delete_messages=True)
set_chat_administrator_custom_title
تنظیم عنوان سفارشی برای ادمین. پارامترها: chat_id, user_id, custom_title
مثال:
await bot.set_chat_administrator_custom_title(chat_id, user_id, "مدیر ارشد")
approve_chat_join_request
تایید درخواست عضویت در چت خصوصی. پارامترها: chat_id, user_id
مثال:
await bot.approve_chat_join_request(chat_id, user_id)
decline_chat_join_request
رد درخواست عضویت در چت خصوصی. پارامترها: chat_id, user_id
مثال:
await bot.decline_chat_join_request(chat_id, user_id)
set_chat_sticker_set
تنظیم مجموعه استیکر برای چت. پارامترها: chat_id, sticker_set_name
مثال:
await bot.set_chat_sticker_set(chat_id, "sticker_set")
delete_chat_sticker_set
حذف مجموعه استیکر چت. پارامترها: chat_id
مثال:
await bot.delete_chat_sticker_set(chat_id)
create_forum_topic
ساخت تاپیک جدید در انجمن. پارامترها: chat_id, name, icon_color
مثال:
await bot.create_forum_topic(chat_id, "تاپیک جدید")
edit_forum_topic
ویرایش تاپیک انجمن (نام، آیکون). پارامترها: chat_id, message_thread_id, name, icon_custom_emoji_id
مثال:
await bot.edit_forum_topic(chat_id, thread_id, "نام جدید")
close_forum_topic
بستن تاپیک انجمن. پارامترها: chat_id, message_thread_id
مثال:
await bot.close_forum_topic(chat_id, thread_id)
reopen_forum_topic
باز کردن مجدد تاپیک بسته شده. پارامترها: chat_id, message_thread_id
مثال:
await bot.reopen_forum_topic(chat_id, thread_id)
delete_forum_topic
حذف تاپیک انجمن. پارامترها: chat_id, message_thread_id
مثال:
await bot.delete_forum_topic(chat_id, thread_id)
unpin_all_forum_topic_messages
برداشتن سنجاق همه پیامهای تاپیک. پارامترها: chat_id, message_thread_id
مثال:
await bot.unpin_all_forum_topic_messages(chat_id, thread_id)📂 فایل و وبهوک (۱۰ متد)
get_file
دریافت اطلاعات فایل (مسیر، حجم) با استفاده از file_id. پارامترها: file_id
مثال:
await bot.get_file(file_id)
download
دانلود فایل از سرور بله در مسیر مشخص. پارامترها: file_path, save_as
مثال:
await bot.download(file_path, "local.jpg")
upload_file
آپلود فایل به سرور بله. پارامترها: file_path, file_type
مثال:
await bot.upload_file("photo.jpg", "photo")
set_webhook
تنظیم وبهوک برای دریافت آپدیتها به صورت HTTP. پارامترها: url, max_connections, allowed_updates
مثال:
await bot.set_webhook("https://your-server.com/webhook")
delete_webhook
حذف وبهوک و بازگشت به Polling. پارامترها: drop_pending_updates
مثال:
await bot.delete_webhook(drop_pending_updates=True)
get_webhook_info
دریافت وضعیت و اطلاعات وبهوک فعلی. بدون پارامتر
مثال:
await bot.get_webhook_info()
get_updates
دریافت آپدیتها با روش Polling (برای رباتهای بدون وبهوک). پارامترها: offset, limit, timeout
مثال:
await bot.get_updates(offset=0, limit=100)
log_out
خروج از حساب ربات (بستن نشست). بدون پارامتر
مثال:
await bot.log_out()
close_bot
بستن ربات و آزادسازی منابع. بدون پارامتر
مثال:
await bot.close_bot()
get_file_url
دریافت لینک مستقیم دانلود فایل. پارامترها: file_path
مثال:
await bot.get_file_url(file_path)🎮 مینیاپ و کیبورد (۱۲ متد)
send_web_app
ارسال دکمهای که یک مینیاپ (برنامه وب) را باز میکند. پارامترها: chat_id, text, web_app_url
مثال:
await bot.send_web_app(chat_id, "باز کردن اپ", "https://app.com")
open_web_app
باز کردن مستقیم مینیاپ با دکمه. پارامترها: chat_id, web_app_url
مثال:
await bot.open_web_app(chat_id, "https://app.com")
inline_keyboard
ساخت کیبورد خطی با دکمههای قابل کلیک (callback_data, url, web_app). پارامترها: buttons (لیست لیست دکمهها)
مثال:
markup = InlineKeyboardMarkup([[button1, button2]])
reply_keyboard
کیبورد شیشهای برای پاسخ سریع کاربر با دکمههای متنی. پارامترها: keyboard, resize_keyboard, one_time_keyboard
مثال:
markup = ReplyKeyboardMarkup([["سلام", "خداحافظ"]])
force_reply
اجبار کاربر به پاسخ به پیام (نمایش باکس پاسخ). پارامترها: force_reply, selective
مثال:
markup = ForceReply(force_reply=True)
remove_keyboard
حذف کیبورد از صفحه چت. پارامترها: remove_keyboard, selective
مثال:
markup = ReplyKeyboardRemove(remove_keyboard=True)
answer_callback_query
پاسخ به کلیک دکمه خطی (نمایش پیام یا آلرت). پارامترها: callback_query_id, text, show_alert, url
مثال:
await bot.answer_callback_query(callback_id, "پاسخ شما")
answer_inline_query
پاسخ به درخواست اینلاین (نتایج جستجو). پارامترها: inline_query_id, results, cache_time
مثال:
await bot.answer_inline_query(query_id, results, cache_time=300)
set_chat_menu_button
تنظیم دکمه منوی چت (برای باز کردن مینیاپ). پارامترها: chat_id, menu_button (با url یا web_app)
مثال:
await bot.set_chat_menu_button(chat_id, {"web_app": {"url": "https://app.com"}})
get_chat_menu_button
دریافت دکمه منوی فعلی چت. پارامترها: chat_id
مثال:
await bot.get_chat_menu_button(chat_id)
callback_button
ساخت دکمه با callback_data (برای پاسخهای تعاملی). پارامترها: text, callback_data
مثال:
btn = InlineKeyboardButton("کلیک", callback_data="click")
web_app_button
ساخت دکمه بازکننده مینیاپ. پارامترها: text, web_app_url
مثال:
btn = InlineKeyboardButton("اپ", web_app={"url": "https://app.com"})📊 نظرسنجی و استیکر (۱۰ متد)
stop_poll
توقف نظرسنجی و نمایش نتایج نهایی. پارامترها: chat_id, message_id, reply_markup
مثال:
await bot.stop_poll(chat_id, message_id)
get_sticker_set
دریافت اطلاعات مجموعه استیکر (نام، تعداد، نوع). پارامترها: name
مثال:
await bot.get_sticker_set("set_name")
upload_sticker_file
آپلود فایل برای ساخت استیکر (فقط PNG یا WEBP). پارامترها: user_id, sticker, sticker_format
مثال:
await bot.upload_sticker_file(user_id, "sticker.png", "static")
create_new_sticker_set
ساخت مجموعه استیکر جدید با لیست استیکرها. پارامترها: user_id, name, title, stickers, sticker_format
مثال:
await bot.create_new_sticker_set(user_id, "set", "عنوان", stickers)
add_sticker_to_set
اضافه کردن استیکر به مجموعه موجود. پارامترها: user_id, name, sticker, emoji_list
مثال:
await bot.add_sticker_to_set(user_id, "set", sticker, ["😊"])
set_sticker_position_in_set
جابجایی استیکر در مجموعه (تغییر ترتیب). پارامترها: sticker, position
مثال:
await bot.set_sticker_position_in_set(sticker_file_id, 0)
delete_sticker_from_set
حذف استیکر از مجموعه. پارامترها: sticker
مثال:
await bot.delete_sticker_from_set(sticker_file_id)
set_sticker_emoji_list
تغییر ایموجیهای یک استیکر. پارامترها: sticker, emoji_list
مثال:
await bot.set_sticker_emoji_list(sticker_file_id, ["❤️"])
get_poll
دریافت اطلاعات نظرسنجی (نتایج). پارامترها: chat_id, message_id
مثال:
await bot.get_poll(chat_id, message_id)
get_poll_votes
دریافت لیست رایدهندگان نظرسنجی. پارامترها: chat_id, message_id, option_id
مثال:
await bot.get_poll_votes(chat_id, message_id, 0)🔧 سایر متدها (۲۰ متد)
set_my_commands
تنظیم لیست دستورات ربات (نمایش در منوی /). پارامترها: commands (لیست دیکشنریهای command و description)
مثال:
await bot.set_my_commands([{"command": "start", "description": "شروع"}])
get_my_commands
دریافت لیست دستورات فعلی ربات. بدون پارامتر
مثال:
await bot.get_my_commands()
delete_my_commands
حذف همه دستورات ربات. بدون پارامتر
مثال:
await bot.delete_my_commands()
set_my_description
تنظیم توضیح کامل ربات (حداکثر ۵۱۲ کاراکتر). پارامترها: description
مثال:
await bot.set_my_description("توضیحات ربات")
get_my_description
دریافت توضیح کامل ربات. بدون پارامتر
مثال:
await bot.get_my_description()
set_my_short_description
تنظیم توضیح کوتاه ربات (حداکثر ۱۲۰ کاراکتر). پارامترها: short_description
مثال:
await bot.set_my_short_description("توضیح کوتاه")
get_my_short_description
دریافت توضیح کوتاه ربات. بدون پارامتر
مثال:
await bot.get_my_short_description()
set_my_name
تنظیم نام ربات (حداکثر ۶۴ کاراکتر). پارامترها: name
مثال:
await bot.set_my_name("نام جدید")
get_my_name
دریافت نام ربات. بدون پارامتر
مثال:
await bot.get_my_name()
set_my_default_administrator_rights
تنظیم حقوق پیشفرض ادمین برای ربات. پارامترها: rights (دیکشنری حقوق)
مثال:
await bot.set_my_default_administrator_rights({"can_delete_messages": True})
get_my_default_administrator_rights
دریافت حقوق پیشفرض ادمین. بدون پارامتر
مثال:
await bot.get_my_default_administrator_rights()
get_user_profile_photos
دریافت عکسهای پروفایل کاربر. پارامترها: user_id, offset, limit
مثال:
await bot.get_user_profile_photos(user_id, limit=10)
set_passport_data_errors
ثبت خطاهای گذرنامه (برای احراز هویت). پارامترها: user_id, errors
مثال:
await bot.set_passport_data_errors(user_id, errors)
get_invoice_link
دریافت لینک پرداخت فاکتور. پارامترها: invoice_data
مثال:
await bot.get_invoice_link(data)
get_star_transactions
دریافت تراکنشهای ستاره (برای پرداختها). پارامترها: limit, offset
مثال:
await bot.get_star_transactions(limit=50)
get_game_high_scores
دریافت امتیازهای بازی. پارامترها: user_id, chat_id, message_id
مثال:
await bot.get_game_high_scores(user_id)
set_game_score
ثبت امتیاز بازی برای کاربر. پارامترها: user_id, score, chat_id, message_id
مثال:
await bot.set_game_score(user_id, 1000)
get_birthdays
دریافت لیست تولدهای کاربران. بدون پارامتر
مثال:
await bot.get_birthdays()
get_chat_folders
دریافت پوشههای چت کاربر. بدون پارامتر
مثال:
await bot.get_chat_folders()
add_chat_to_folder
اضافه کردن چت به پوشه. پارامترها: chat_id, folder_id
مثال:
await bot.add_chat_to_folder(chat_id, folder_id)💻 نمونه کدهای کامل
ربات حاضر جواب (Echo Bot)
from balenull import Client
bot = Client("TOKEN")
@bot.on_message()
async def echo(message):
# پاسخ با همان متن
await message.reply(message.text)
bot.run()
ربات با دکمه و مینیاپ
from balenull import Client, InlineKeyboardMarkup, InlineKeyboardButton
bot = Client("TOKEN")
@bot.on_message()
async def start(message):
if message.text == "/start":
# ساخت دکمه با مینیاپ
btn = InlineKeyboardButton(
"باز کردن اپ",
web_app={"url": "https://my-app.com"}
)
markup = InlineKeyboardMarkup([[btn]])
await bot.send_message(
message.chat_id,
"به ربات خوش آمدید!",
reply_markup=markup