🚀 کتابخانه رسمی و مدرن پایتون برای اتوماسیون شاد

مستندات کامل و هوشمند
کتابخانه قدرتمند shadism (شادیسم)

طراحی‌شده بر پایه پروتکل بومی پیام‌رسان شاد، رمزنگاری پیشرفته دوطرفه AES/RSA، معماری تماماً ناهمگام (Async/Await) و مجهز به دیسپچر رویدادمحور و مدل‌های شیء‌گرای داده.

👨‍💻 توسعه‌دهنده: امیرعلی خسروی نژاد • کانال رسمی: ble.ir/join/8jXbafMPwL • مستندات: amirali-khosravinejad.github.io/shadism
⚡ شروع سریع و نصب گیت‌هاب پروژه 🐙 کانال اطلاع‌رسانی 🔗
100%
ناهمگام (Asyncio Native)
E2E
رمزنگاری AES-CBC + RSA
20+
متدهای کاربردی و پیشرفته
WebRTC
پشتیبانی از ویس‌چت گروه/کانال

⚡ نصب و راه‌اندازی سریع Quickstart

CLI Terminal — Installation
bash

کتابخانه shadism به صورت مستقیم از طریق PyPI قابل نصب است و تمامی پیش‌نیازها را به صورت خودکار نصب خواهد کرد:

Bash / Terminal
pip install shadism
CLASS Client(phone_number, session_directory=".")
shadism.Client

کلاس اصلی کلاینت برای ایجاد سشن، اتصال امن، ذخیره سشن روی دیسک با فرمت .session و دریافت کد یکبار مصرف لاگین (OTP).

Python — Client Initialization
import asyncio
from shadism import Client

bot = Client("09000000000")

@bot.on_message
async def handler(message):
    print(f"New message: {message.text}")

async def main():
    await bot.start()

asyncio.run(main())

💬 متدهای مدیریت پیام‌ها و تاریخچه چت Messages API

NEW await bot.get_chat_history(guid, limit=50)
List[Message]

متد اختصاصی و هوشمند تاریخچه پیام‌ها: این متد پیشرفته با بهره‌گیری از صفحه‌بندی خودکار (Automatic Pagination)، تاریخچه یک گفتگو (کاربر، گروه یا کانال) را تا سقف مقدار درخواستی دریافت کرده و به‌صورت لیستی از اشیای کامل Message برمی‌گرداند.

نام پارامتر نوع پیش‌فرض توضیحات
guid / object_guid str اجباری شناسه اختصاصی کاربر (u0...)، گروه (g0...) یا کانال (c0...)
limit int 50 تعداد پیام‌های درخواستی (با پشتیبانی از مقادیر بزرگ و دریافت دسته‌ای)
sort str "FromMax" مرتب‌سازی پیام‌ها بر اساس شناسه ("FromMax" یا "FromMin")
Python — get_chat_history Example
from shadism import Client

bot = Client("09000000000")

@bot.on_message
async def history_example(message):
    if message.text == "تاریخچه":
        # دریافت ۲۰ پیام اخیر با تمام امکانات شیء‌گرا
        history = await bot.get_chat_history(message.chat_guid, limit=20)
        
        for msg in history:
            print(f"[{msg.id}] {msg.author_guid}: {msg.text}")
            
            # متدهای مستقیم روی تک تک پیام‌ها
            if "سلام" in (msg.text or ""):
                await msg.reply("درود!")
METHOD await bot.send_message(object_guid, text, reply_to_message_id=None)
Message

ارسال پیام متنی به چت، گروه یا کانال با پشتیبانی از ریپلای روی پیام دیگر. خروجی این متد شیء Message است که می‌توانید بلافاصله روی آن عملیات ویرایش، ریپلای یا حذف را انجام دهید.

Python — send_message
# ارسال پیام ساده
sent_msg = await bot.send_message(
    object_guid="u0DoNvd...",
    text="سلام از کتابخانه shadism! 🚀"
)

# ارسال در پاسخ به یک پیام مشخص
reply_msg = await bot.send_message(
    object_guid="u0DoNvd...",
    text="پاسخ به پیام شما",
    reply_to_message_id=sent_msg.id
)
METHOD await bot.edit_message(object_guid, message_id, text)
Message

ویرایش متن پیامی که قبلاً ارسال شده است. هم از طریق کلاینت و هم مستقیماً با فراخوانی await message.edit("متن جدید") قابل استفاده است.

Python — edit_message
# روش ۱: از طریق شیء پیام
await message.edit("متن این پیام با موفقیت ویرایش شد ✅")

# روش ۲: از طریق ربات و شناسه پیام
await bot.edit_message(
    object_guid=chat_guid,
    message_id="6209768942",
    text="متن اصلاح‌شده"
)
METHOD await bot.delete_message(object_guid, message_id, delete_type="Global")
Dict[str, Any]

حذف پیام به صورت دوطرفه (Global) یا یکطرفه (Local). با انتخاب حالت Global، پیام به صورت کامل برای هر دو طرف گفتگو پاکسازی می‌شود.

Python — delete_message
# حذف مستقیم از روی شیء پیام
await message.delete(delete_type="Global")

# حذف دسته‌ای چندین پیام همزمان
await bot.delete_messages(
    object_guid=message.chat_guid,
    message_ids=["6209768940", "6209768941"],
    delete_type="Global"
)
METHOD await bot.get_messages(chat_guid, min_id=None, max_id=None, limit=50)
Dict[str, Any]

دریافت مستقیم بسته پیام‌ها بر اساس بازه زمانی، آخرین شناسه (min_id/max_id) یا شناسه میانی با متد get_messages_interval و همچنین حذف کامل تاریخچه گفتگو با delete_chat_history.

نام پارامتر نوع پیش‌فرض توضیحات
chat_guid str اجباری شناسه چت، گروه یا کانال مورد نظر
limit int 50 تعداد پیام‌های دریافتی
sort str "FromMin" جهت پیمایش پیام‌ها ("FromMin" یا "FromMax")
Python — Raw Messages & History Deletion
# دریافت پیام‌ها با فیلتر شناسه
raw_msgs = await bot.get_messages(chat_guid="g0B123...", limit=30)

# دریافت پیام‌های قبل و بعد از یک پیام میانی
interval = await bot.methods.get_messages_interval(
    chat_guid="g0B123...",
    middle_message_id="6209801"
)

# پاکسازی کامل تاریخچه گفتگو
await bot.delete_chat_history(object_guid="u0DoNvd...")

📁 متدهای چندرسانه‌ای و آپلود فایل Media & Upload API

METHOD await bot.send_photo(object_guid, photo, caption=None)
Message

ارسال تصویر با فشرده‌سازی خودکار پیش‌نمایش (Thumbnail)، محاسبه خودکار ابعاد طول و عرض و ارسال مستقیم و بهینه‌شده. ورودی تصویر می‌تواند مسیر فایل روی دیسک، شیء Path یا بایت‌های خام تصویر باشد.

Python — send_photo
# ارسال عکس با مسیر محلی
await bot.send_photo(
    object_guid=message.chat_guid,
    photo="banner.jpg",
    caption="بنر جدید کانال ما 🖼️"
)

# ارسال عکس با بایت‌های خام یا در پاسخ
await message.reply_photo(
    photo=raw_image_bytes,
    caption="تصویر ساخته‌شده با هوش مصنوعی"
)
METHOD await bot.send_file(object_guid, file, file_name=None, mime=None, caption=None)
Message

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

Python — send_file
await bot.send_file(
    object_guid=message.chat_guid,
    file="archive.zip",
    file_name="source_code.zip",
    caption="سورس کد پروژه شادیسم 📦"
)
STREAM await bot.upload_file(file_data, mime_type, file_name)
Dict[str, Any]

آپلود مستقیم فایل‌ها با استفاده از استریم تکه‌ای (Chunked Upload) و تحمل خطای بالا در برابر قطعی‌های شبکه. خروجی شامل شناسه فایل و مشخصات لازم جهت ضمیمه در پیام‌ها است.

Python — Direct Chunked File Upload
# آپلود داده‌های باینری دلخواه
with open("data.bin", "rb") as f:
    binary_content = f.read()

upload_res = await bot.upload_file(
    file_data=binary_content,
    mime_type="application/octet-stream",
    file_name="data.bin"
)

file_id = upload_res["file_id"]
access_hash = upload_res["access_hash_send"]
print(f"فایل با شناسه {file_id} آپلود شد.")

👥 متدهای چت‌ها، گروه‌ها و کاربران Chats & Users

METHOD await bot.get_chat_info(object_guid)
Chat

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

Python — get_chat_info
chat = await bot.get_chat_info("g0B12345...")

print(f"نام چت: {chat.title}")
print(f"نوع گفتگو: {chat.chat_type}")  # Group / Channel / User
print(f"تعداد اعضا: {chat.members_count}")
print(f"آیدی عددی: {chat.guid}")

# ارسال مستقیم پیام از روی آبجکت Chat
await chat.send_message("سلام به همه اعضای گروه!")
METHOD await bot.get_user_info(user_guid=None)
User

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

Python — get_user_info & update_profile
# دریافت اطلاعات خودمان
me = await bot.get_user_info()
print(f"نام من: {me.first_name} {me.last_name}")
print(f"بیوگرافی: {me.bio}")

# ویرایش بیوگرافی یا نام پروفایل
await bot.update_profile(
    first_name="شادیسم",
    bio="توسعه‌یافته توسط امیرعلی خسروی نژاد"
)
METHOD await bot.get_chats(start_id=None) / seen_chats(...)
Dict[str, Any]

مدیریت گفتگوها و تعاملات: دریافت فهرست چت‌های فعال اکانت، ارسال حالت فعالیت (Typing / Recording)، سین زدن خودکار پیام‌ها با seen_chats، بلاک یا آنبلاک کاربران و دریافت تاریخچه آواتارها با get_avatars.

Python — Chats, Activities & Avatars
# ۱. دریافت لیست گفتگوهای اخیر اکانت
chats_res = await bot.get_chats()

# ۲. ارسال وضعیت در حال تایپ به چت
await bot.send_chat_activity(object_guid="g0B123...", activity="Typing")

# ۳. سین زدن پیام‌ها
await bot.seen_chats({"g0B123...": "6209842"})

# ۴. دریافت گالری تصاویر پروفایل هدف
avatars = await bot.get_avatars(object_guid="u0DoNvd...")

# ۵. استعلام آزاد بودن نام کاربری (یوزرنیم)
check_res = await bot.check_user_username("my_new_id")

📞 مخاطبین و جستجوی شماره تلفن (Contacts API) Contacts API

FEATURE await bot.get_user_by_phone(phone, auto_delete=True)
Optional[User]

استعلام هوشمند اطلاعات کامل با شماره موبایل: این متد اطلاعات کامل کاربر (شامل GUID یکتا، نام، نام خانوادگی، یوزرنیم، نشان رسمی و وضعیت آنلاین) را مستقیماً از روی شماره همراه استعلام کرده و به صورت شیء یکپارچه User بازمی‌گرداند.

نام پارامتر نوع پیش‌فرض توضیحات
phone str اجباری شماره همراه کاربر (فرمت ۰۹xxxxxxxxx یا +98...)
auto_delete bool True پاکسازی خودکار مخاطب موقت پس از دریافت پروفایل
Python — Phone Lookup & Contacts Management
# ۱. دریافت مشخصات کامل یک شماره موبایل
user = await bot.get_user_by_phone("09000000000")
if user:
    print(f"نام: {user.first_name} | آیدی: {user.guid} | یوزرنیم: @{user.username}")
    await user.send_message("سلام! شماره شما با موفقیت شناسایی شد.")

# ۲. دریافت کل مخاطبین ذخیره شده
contacts = await bot.get_contacts()

# ۳. افزودن مخاطب جدید
await bot.methods.add_contact(first_name="علی", last_name="رضایی", phone="09000000000")

# ۴. حذف مخاطب با شناسه کاربری
await bot.methods.delete_contact(user_guid=user.guid)

🔗 عضویت در کانال‌ها و گروه‌ها (Join & Channel API) Join API

METHOD await bot.join_chat(guid_or_link) / join_group(...)
Dict[str, Any]

عضویت هوشمند در انواع گفتگوهای شاد با پشتیبانی از پیوند دعوت (Join Link)، لینک‌های عمومی t.me/shad.ir و شناسه‌های مستقیم. همچنین امکان پیش‌نمایش اطلاعات گروه یا کانال پیش از عضویت نهایی با group_preview_by_join_link و channel_preview_by_join_link فراهم است.

Python — Smart Chat Joining
# ۱. پیوستن خودکار و هوشمند با پیوند دعوت
await bot.join_chat("https://shad.ir/joing/BADEAF...")

# ۲. عضویت در کانال با شناسه اختصاصی
await bot.join_channel_action(channel_guid="c0C123...", action="Join")

# ۳. پیش‌نمایش مشخصات گروه قبل از عضویت
preview = await bot.group_preview_by_join_link("BADEAF...")
print(f"عنوان گروه دعوت‌شده: {preview.get('title')}")

# ۴. لغو عضویت و خروج از گروه
await bot.leave_group(group_guid="g0B123...")

🎙️ متدهای ویس چت و WebRTC Voice Chat API

VOICE await bot.join_voice_chat(chat_guid, voice_chat_id)
Dict[str, Any]

پکیج کامل مدیریت صوتی گروه و کانال: ایجاد گفتگوی صوتی، ورود با SDP Offer (WebRTC)، تنظیم وضعیت میکروفون (Speaking / Mute) و خروج از ویس.

Python — Voice Chat Automation
# ۱. ایجاد ویس چت جدید در گروه
vc_info = await bot.create_voice_chat(group_guid)

# ۲. ورود به ویس چت
await bot.join_voice_chat(chat_guid=group_guid)

# ۳. تنظیم حالت صحبت کردن
await bot.methods.set_voice_chat_state(
    chat_guid=group_guid,
    voice_chat_id=vc_id,
    activity="Speaking"
)

# ۴. خروج از گفتگوی صوتی
await bot.leave_voice_chat(chat_guid=group_guid)

🔄 رویدادها و دریافت آپدیت‌ها (Updates API) Updates API

EVENTS await bot.get_chats_updates() / get_messages_updates(...)
Dict[str, Any]

موتور پولینگ ناهمگام شادیسم به‌صورت خودکار تغییرات چت‌ها و پیام‌ها را دریافت و مدیریت می‌کند. همچنین می‌توانید مستقیماً آخرین وضعیت و رویدادها را با متدهای اختصاصی استعلام نمایید یا با دکوراتور @bot.on_chat_updates تغییرات گفتگوها را شنود کنید.

Python — Updates & Event Polling
# شنود تغییرات چت‌ها (تغییر نام، اعضا و وضعیت)
@bot.on_chat_updates
async def chat_change_listener(update):
    print(f"تغییر در چت: {update}")

# واکشی دستی آپدیت‌های یک چت مشخص
msg_updates = await bot.get_messages_updates(chat_guid="g0B123...")

🎯 سیستم قدرتمند فیلترها (Event Filters) Filters

MODULE shadism.filters — Declarative Filter Engine
Filter

سیستم فیلتر ماژولار با پشتیبانی از عملگرهای منطقی & (AND)، | (OR) و ~ (NOT) برای پردازش انتخابی پیام‌ها.

فیلتر عملکرد نمونه استفاده
filters.command تشخیص دستورات با پیشوندهای دلخواه filters.command("start", prefixes=["/", "!"])
filters.regex تطبیق با الگوی منظم (Regular Expressions) filters.regex(r"^دانلود\s+(.+)")
filters.private تنها پیام‌های چت‌های خصوصی (PV) filters.private
filters.group تنها پیام‌های ارسال‌شده در گروه‌ها filters.group
filters.channel تنها پیام‌های کانال‌ها filters.channel
filters.reply پیام‌هایی که در پاسخ به پیام دیگری هستند filters.reply
filters.create ساخت فیلتر شرطی دلخواه و تابع سفارشی filters.create(lambda m: "سلام" in m.text)
Python — Filter Composition
from shadism import Client, filters

bot = Client("09000000000")

# فقط دستور پینگ در گروه‌ها
@bot.on_message(filters.command("ping") & filters.group)
async def ping_in_group(message):
    await message.reply("پونگ در گروه! 🏓")

# ترکیب دستورات چندگانه در پی‌وی
@bot.on_message(filters.command(["help", "راهنما"]) & filters.private)
async def private_help(message):
    await message.reply("راهنمای چت خصوصی...")

🧩 مدل‌های شیء‌گرا (OOP Data Models) Data Models

DATACLASS shadism.types.Message
Message

نمایش شیء‌گرای پیام‌های شاد با اتصالات خودکار به کلاینت. علاوه بر خصوصیات معمولی، امکان دسترسی شبه‌دیکشنری نظیر msg["message_id"] و دسترسی به ساختار داده کامل پیام از طریق msg.raw فراهم است.

Python — Message Model Features
# خصوصیات شیء پیام:
msg.id                    # شناسه پیام
msg.text                  # متن پیام
msg.author_guid           # فرستنده
msg.chat_guid             # چت مقصد
msg.is_edited             # آیا ادیت شده؟
msg.reply_to_message_id   # شناسه پیام ریپلای‌شده

# متدهای مستقیم پیام:
await msg.reply("متن پاسخ")
await msg.reply_photo("image.png")
await msg.reply_file("doc.pdf")
await msg.edit("متن جدید")
await msg.delete(delete_type="Global")
chat = await msg.get_chat()
author = await msg.get_author()
DATACLASS shadism.types.Chat
Chat

مدل جامع اطلاعات چت (PV، گروه یا کانال). دسترسی سریع به عنوان، تعداد اعضا، شناسه یکتا، بیوگرافی و امکان ارسال پیام مستقیم به این گفتگو بدون نیاز به پاس دادن مجدد شناسه.

Python — Chat Model Features
chat = await bot.get_chat_info("g0B123...")

print(chat.guid)           # شناسه یکتا
print(chat.title)          # نام گروه یا کانال
print(chat.chat_type)      # نوع ("Group", "Channel", "User")
print(chat.members_count)  # تعداد اعضا

# ارسال پیام مستقیم به گفتگو
await chat.send_message("پیام ارسال‌شده از روی آبجکت Chat!")
DATACLASS shadism.types.User
User

مدل شیء‌گرای کاربران شاد با متادیتاهای نام، نام خانوادگی، شماره موبایل، یوزرنیم، نشان تایید، وضعیت آنلاین و امکان ارسال مستقیم پیام به پی‌وی کاربر.

Python — User Model Features
user = await bot.get_user_info("u0DoNvd...")

print(user.first_name)     # نام کوچک
print(user.last_name)      # نام خانوادگی
print(user.username)       # یوزرنیم (@...)
print(user.phone)          # شماره موبایل در صورت اشتراک
print(user.is_verified)    # نشان رسمی

# ارسال مستقیم پیام خصوصی
await user.send_message("سلام! پیام خصوصی ارسال شد.")

💡 پروژه‌ها و مثال‌های ترکیبی کامل Full Projects

APP Advanced Userbot & Cleaner — test.py
Application

نمونه واقعی و تولیدی یک یوزربات چندکاره در شاد، شامل منوی تعاملی دستور /start، آپلود تصاویر تک‌پیکسلی، پاکسازی دوطرفه خودکار با get_chat_history و هندلرهای خوش‌آمدگویی.

Python — Real-World Complete Bot
import asyncio
from shadism import Client, filters

bot = Client("09000000000")

@bot.on_message(filters.command("start"))
async def start_cmd(message):
    await message.reply(
        "🤖 به یوزربات شادیسم خوش آمدید!\n\n"
        "1. ارسال تصویر\n"
        "2. پاکسازی دوطرفه پیام‌های من\n"
        "3. تاریخچه گفتگو"
    )

@bot.on_message(filters.command("history") | filters.command("تاریخچه"))
async def chat_history_cmd(message):
    history = await bot.get_chat_history(message.chat_guid, limit=10)
    lines = [f"📜 آخرین {len(history)} پیام چت:"]
    for i, m in enumerate(history, 1):
        lines.append(f"{i}. {m.text[:30]} | فرستنده: {m.author_guid[:8]}...")
    await message.reply("\n".join(lines))

@bot.on_message(filters.command("clean"))
async def clean_cmd(message):
    # پیدا کردن پیام‌ها با get_chat_history و پاکسازی دوطرفه
    history = await bot.get_chat_history(message.chat_guid, limit=50)
    my_messages = [m.id for m in history if m.author_guid == bot.session.user_guid]
    
    if my_messages:
        await bot.delete_messages(message.chat_guid, my_messages, delete_type="Global")
        await message.reply(f"🗑️ تعداد {len(my_messages)} پیام دوطرفه پاکسازی شد.")

async def main():
    await bot.start()

if __name__ == "__main__":
    asyncio.run(main())
✨ کد با موفقیت کپی شد!