⚡ نصب و راهاندازی سریع Quickstart
کتابخانه shadism به صورت مستقیم از طریق PyPI قابل نصب است و تمامی پیشنیازها را به صورت خودکار نصب خواهد کرد:
pip install shadism
کلاس اصلی کلاینت برای ایجاد سشن، اتصال امن، ذخیره سشن روی دیسک با فرمت .session و دریافت کد یکبار مصرف لاگین (OTP).
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
متد اختصاصی و هوشمند تاریخچه پیامها: این متد پیشرفته با بهرهگیری از صفحهبندی خودکار (Automatic Pagination)، تاریخچه یک گفتگو (کاربر، گروه یا کانال) را تا سقف مقدار درخواستی دریافت کرده و بهصورت لیستی از اشیای کامل Message برمیگرداند.
| نام پارامتر | نوع | پیشفرض | توضیحات |
|---|---|---|---|
| guid / object_guid | str | اجباری | شناسه اختصاصی کاربر (u0...)، گروه (g0...) یا کانال (c0...) |
| limit | int | 50 | تعداد پیامهای درخواستی (با پشتیبانی از مقادیر بزرگ و دریافت دستهای) |
| sort | str | "FromMax" | مرتبسازی پیامها بر اساس شناسه ("FromMax" یا "FromMin") |
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("درود!")
ارسال پیام متنی به چت، گروه یا کانال با پشتیبانی از ریپلای روی پیام دیگر. خروجی این متد شیء 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"
)
دریافت مستقیم بسته پیامها بر اساس بازه زمانی، آخرین شناسه (min_id/max_id) یا شناسه میانی با متد get_messages_interval و همچنین حذف کامل تاریخچه گفتگو با delete_chat_history.
| نام پارامتر | نوع | پیشفرض | توضیحات |
|---|---|---|---|
| chat_guid | str | اجباری | شناسه چت، گروه یا کانال مورد نظر |
| limit | int | 50 | تعداد پیامهای دریافتی |
| sort | str | "FromMin" | جهت پیمایش پیامها ("FromMin" یا "FromMax") |
# دریافت پیامها با فیلتر شناسه
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
ارسال تصویر با فشردهسازی خودکار پیشنمایش (Thumbnail)، محاسبه خودکار ابعاد طول و عرض و ارسال مستقیم و بهینهشده. ورودی تصویر میتواند مسیر فایل روی دیسک، شیء 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="سورس کد پروژه شادیسم 📦"
)
آپلود مستقیم فایلها با استفاده از استریم تکهای (Chunked 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
دریافت اطلاعات جامع چت (پیوی، گروه یا کانال). این متد بهطور خودکار نوع گفتگو را بر اساس شناسه هدف تشخیص داده و مدل یکپارچه Chat را به همراه عنوان، نوع چت و تعداد اعضا برمیگرداند.
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="توسعهیافته توسط امیرعلی خسروی نژاد"
)
مدیریت گفتگوها و تعاملات: دریافت فهرست چتهای فعال اکانت، ارسال حالت فعالیت (Typing / Recording)، سین زدن خودکار پیامها با seen_chats، بلاک یا آنبلاک کاربران و دریافت تاریخچه آواتارها با get_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
استعلام هوشمند اطلاعات کامل با شماره موبایل: این متد اطلاعات کامل کاربر (شامل GUID یکتا، نام، نام خانوادگی، یوزرنیم، نشان رسمی و وضعیت آنلاین) را مستقیماً از روی شماره همراه استعلام کرده و به صورت شیء یکپارچه User بازمیگرداند.
| نام پارامتر | نوع | پیشفرض | توضیحات |
|---|---|---|---|
| phone | str | اجباری | شماره همراه کاربر (فرمت ۰۹xxxxxxxxx یا +98...) |
| auto_delete | bool | True | پاکسازی خودکار مخاطب موقت پس از دریافت پروفایل |
# ۱. دریافت مشخصات کامل یک شماره موبایل
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
عضویت هوشمند در انواع گفتگوهای شاد با پشتیبانی از پیوند دعوت (Join Link)، لینکهای عمومی t.me/shad.ir و شناسههای مستقیم. همچنین امکان پیشنمایش اطلاعات گروه یا کانال پیش از عضویت نهایی با group_preview_by_join_link و channel_preview_by_join_link فراهم است.
# ۱. پیوستن خودکار و هوشمند با پیوند دعوت
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
پکیج کامل مدیریت صوتی گروه و کانال: ایجاد گفتگوی صوتی، ورود با 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)
🔄 رویدادها و دریافت آپدیتها (Updates API) Updates API
موتور پولینگ ناهمگام شادیسم بهصورت خودکار تغییرات چتها و پیامها را دریافت و مدیریت میکند. همچنین میتوانید مستقیماً آخرین وضعیت و رویدادها را با متدهای اختصاصی استعلام نمایید یا با دکوراتور @bot.on_chat_updates تغییرات گفتگوها را شنود کنید.
# شنود تغییرات چتها (تغییر نام، اعضا و وضعیت)
@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
سیستم فیلتر ماژولار با پشتیبانی از عملگرهای منطقی & (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("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
نمایش شیءگرای پیامهای شاد با اتصالات خودکار به کلاینت. علاوه بر خصوصیات معمولی، امکان دسترسی شبهدیکشنری نظیر 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()
مدل جامع اطلاعات چت (PV، گروه یا کانال). دسترسی سریع به عنوان، تعداد اعضا، شناسه یکتا، بیوگرافی و امکان ارسال پیام مستقیم به این گفتگو بدون نیاز به پاس دادن مجدد شناسه.
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!")
مدل شیءگرای کاربران شاد با متادیتاهای نام، نام خانوادگی، شماره موبایل، یوزرنیم، نشان تایید، وضعیت آنلاین و امکان ارسال مستقیم پیام به پیوی کاربر.
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
نمونه واقعی و تولیدی یک یوزربات چندکاره در شاد، شامل منوی تعاملی دستور /start، آپلود تصاویر تکپیکسلی، پاکسازی دوطرفه خودکار با get_chat_history و هندلرهای خوشآمدگویی.
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())