⚡ نصب و راهاندازی سریع Quickstart
کتابخانه shadism به صورت مستقیم از طریق PyPI قابل نصب است و تمامی پیشنیازها را به صورت خودکار نصب خواهد کرد:
pip install shadism
کلاس اصلی کلاینت برای ایجاد سشن، اتصال امن، ذخیره سشن روی دیسک با فرمت .session و دریافت کد یکبار مصرف لاگین (OTP).
import asyncio
from shadism import Client
bot = Client("0937xxxxxxx")
@bot.on_message
async def handler(message):
print(f"New message: {message.text}")
async def main():
await bot.start()
asyncio.run(main())
💬 متدهای مدیریت پیامها و تاریخچه چت Messages API
متد اختصاصی و هوشمند تاریخچه پیامها: این متد با ترکیب اندپوینتهای پیام و آپدیت و با بهرهگیری از صفحهبندی خودکار (Automatic Pagination)، تاریخچه یک گفتگو (کاربر، گروه یا کانال) را تا سقف مقدار درخواستی دریافت کرده و بهصورت لیستی از اشیای کامل Message برمیگرداند.
| نام پارامتر | نوع | پیشفرض | توضیحات |
|---|---|---|---|
| guid / object_guid | str | اجباری | شناسه اختصاصی کاربر (u0...)، گروه (g0...) یا کانال (c0...) |
| limit | int | 50 | تعداد پیامهای درخواستی (با پشتیبانی از مقادیر بزرگ و دریافت دستهای) |
| sort | str | "FromMax" | مرتبسازی پیامها بر اساس شناسه ("FromMax" یا "FromMin") |
from shadism import Client
bot = Client("0937xxxxxxx")
@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("درود!")
ارسال پیام متنی به چت، گروه یا کانال با پشتیبانی از ریپلای روی پیام دیگر. خروجی این متد شیء 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
)
ویرایش متن پیامی که قبلاً ارسال شده است. هم از طریق کلاینت و هم مستقیماً با فراخوانی await message.edit("متن جدید") قابل استفاده است.
# روش ۱: از طریق شیء پیام
await message.edit("متن این پیام با موفقیت ویرایش شد ✅")
# روش ۲: از طریق ربات و شناسه پیام
await bot.edit_message(
object_guid=chat_guid,
message_id="6209768942",
text="متن اصلاحشده"
)
حذف پیام به صورت دوطرفه (Global) یا یکطرفه (Local). پروتکل شاد با ارسال نوع Global پیام را از دو طرف پاکسازی میکند.
# حذف مستقیم از روی شیء پیام
await message.delete(delete_type="Global")
# حذف دستهای چندین پیام همزمان
await bot.delete_messages(
object_guid=message.chat_guid,
message_ids=["6209768940", "6209768941"],
delete_type="Global"
)
📁 متدهای چندرسانهای و آپلود فایل Media & Upload API
ارسال تصویر با فشردهسازی هوشمند بندانگشتی (Thumbnail)، محاسبه خودکار ابعاد طول و عرض و ارسال مستقیم به سرورهای آپلود شاد (UploadFile.ashx). ورودی تصویر میتواند آدرس فایل، شیء Path یا بایتهای خام باشد.
# ارسال عکس با مسیر محلی
await bot.send_photo(
object_guid=message.chat_guid,
photo="banner.jpg",
caption="بنر جدید کانال ما 🖼️"
)
# ارسال عکس با بایتهای خام یا در پاسخ
await message.reply_photo(
photo=raw_image_bytes,
caption="تصویر ساختهشده با هوش مصنوعی"
)
ارسال اسناد، فایلهای فشرده zip، صوت، ویدیو یا هر نوع فایل دیگر با آپلود تکهای (Chunked Streaming) و مقاومت بالا در برابر قطعیهای شبکه.
await bot.send_file(
object_guid=message.chat_guid,
file="archive.zip",
file_name="source_code.zip",
caption="سورس کد پروژه شادیسم 📦"
)
👥 متدهای چتها، گروهها و کاربران Chats & Users
دریافت اطلاعات جامع چت (پیوی، گروه یا کانال). این متد بهطور خودکار نوع چت را بر اساس پیشوند شناسه (u0/g0/c0) تشخیص داده و متد مرتبط شاد (getUserInfo, getGroupInfo, getChannelInfo) را فراخوانی میکند.
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("سلام به همه اعضای گروه!")
دریافت اطلاعات یک کاربر با شناسه او؛ یا اگر پارامتر خالی بماند، اطلاعات صاحب اکانت جاری (سلف بات) برگردانده میشود.
# دریافت اطلاعات خودمان
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="توسعهیافته توسط امیرعلی خسروی نژاد"
)
🎙️ متدهای ویس چت و WebRTC Voice Chat API
پکیج کامل مدیریت صوتی گروه و کانال: ایجاد گفتگوی صوتی، ورود با SDP Offer (WebRTC)، تنظیم وضعیت میکروفون (Speaking / Mute) و خروج از ویس.
# ۱. ایجاد ویس چت جدید در گروه
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)
🎯 سیستم قدرتمند فیلترها (Event Filters) Filters
سیستم فیلتر ماژولار با پشتیبانی از عملگرهای منطقی & (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) |
from shadism import Client, filters
bot = Client("0937xxxxxxx")
# فقط دستور پینگ در گروهها
@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
نمایش شیءگرای پیامهای شاد با اتصالات خودکار به کلاینت. علاوه بر خصوصیات معمولی، امکان دسترسی شبهدیکشنری نظیر msg["message_id"] و دسترسی به بایتهای خام سرور msg.raw فراهم است.
# خصوصیات شیء پیام:
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()
💡 پروژهها و مثالهای ترکیبی کامل Full Projects
نمونه واقعی و تولیدی یک یوزربات چندکاره در شاد، شامل منوی تعاملی دستور /start، آپلود تصاویر تکپیکسلی، پاکسازی دوطرفه خودکار با get_chat_history و هندلرهای خوشآمدگویی.
import asyncio
from shadism import Client, filters
bot = Client("0937xxxxxxx")
@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())