telegrampx 1.3.0

یک کتابخانه فوق سریع برای ربات تلگرام

# داکیومنت

لینک داکیومنت ("https://iliya8989.github.io/telegrampx/")

TelegramPX

کتابخانه قدرتمند و ساده پایتون برای ساخت ربات‌های تلگرام

فهرست مطالب

• معرفی
• ویژگی‌های اصلی
• نصب و راه‌اندازی
• ساخت اولین ربات
• کلاس TelegramBot
• ارسال پیام‌ها
• کار با کیبوردها
• پردازش پیام‌های دریافتی
• مدیریت فایل‌ها و رسانه‌ها
• مدیریت گروه‌ها و کانال‌ها
• مدیریت وضعیت کاربر
• وبهوک و پولینگ
• ذخیره‌سازی داده‌ها
• نمونه‌های کاربردی
• مباحث پیشرفته
• عیب‌یابی و رفع خطاها
• سوالات متداول

معرفی

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

با استفاده از TelegramPX، می‌توانید در کمترین زمان ممکن ربات‌های کاربردی ایجاد کنید و روی منطق کسب و کار خود تمرکز کنید.

ویژگی‌های اصلی

• آسان و سریع: ساخت ربات‌های تلگرام با حداقل کدنویسی و API ساده و روان
• قابلیت‌های کامل: پشتیبانی از تمام قابلیت‌های اصلی API تلگرام با رابط کاربری ساده
• دکمه‌های تعاملی: ایجاد آسان کیبوردها، دکمه‌های اینلاین و منوهای تعاملی
• رویدادمحور: معماری رویدادمحور برای مدیریت آسان پیام‌ها و تعاملات کاربر
• امن و قابل اعتماد: استفاده از بهترین شیوه‌های امنیتی و مدیریت خطا
• مستندات کامل: آموزش‌ها و مثال‌های کاربردی برای شروع سریع توسعه
• پشتیبانی از فایل‌ها و رسانه‌ها: ارسال و دریافت انواع فایل‌ها، تصاویر و ویدیوها
• مدیریت گروه‌ها و کانال‌ها: ابزارهای کامل برای کار با گروه‌ها و کانال‌های تلگرام
• مدیریت وضعیت: ذخیره و بازیابی اطلاعات کاربران و وضعیت گفتگو
• پشتیبانی از وبهوک: امکان استفاده از وبهوک برای پاسخگویی سریع‌تر
• فارسی‌سازی کامل: پشتیبانی کامل از زبان فارسی در تمام بخش‌های کتابخانه

نصب و راه‌اندازی

نصب TelegramPX بسیار ساده است. کافیست با استفاده از pip، کتابخانه را نصب کنید:

pip install telegrampx

نیازمندی‌ها

TelegramPX با پایتون 3.7 و نسخه‌های بالاتر سازگار است و تنها به کتابخانه‌های استاندارد پایتون نیاز دارد.

ساخت اولین ربات

برای ایجاد اولین ربات، ابتدا باید یک توکن از BotFather دریافت کنید. سپس می‌توانید با کد زیر یک ربات ساده ایجاد کنید:

import telegrampx

# ایجاد نمونه از کلاس TelegramBot
bot = telegrampx.TelegramBot(token='YOUR_TOKEN_HERE')

# تعریف تابع پاسخ‌دهنده به دستور /start
def send_welcome(message):
    bot.send_message(
        message.chat.id,
        'سلام! به ربات من خوش آمدید.'
    )
    
# ثبت تابع پاسخ‌دهنده برای دستور start
bot.register_message_handler(send_welcome, ['start'])

# شروع گوش دادن به پیام‌های دریافتی
if __name__ == '__main__':
    bot.polling()

نکته: مطمئن شوید که YOUR_TOKEN_HERE را با توکن واقعی رباتی که از BotFather دریافت کرده‌اید، جایگزین کنید.

کلاس TelegramBot

کلاس TelegramBot کلاس اصلی برای تعامل با API تلگرام است. تمام عملیات ربات از طریق این کلاس انجام می‌شود.

# ایجاد نمونه ربات
bot = telegrampx.TelegramBot(token='YOUR_TOKEN_HERE')

پارامترهای اختیاری

هنگام ایجاد نمونه از کلاس TelegramBot، می‌توانید پارامترهای اختیاری زیر را نیز تنظیم کنید:

bot = telegrampx.TelegramBot(
    token='YOUR_TOKEN_HERE',  # توکن ربات (اجباری)
    parse_mode='HTML',        # نوع پیش‌فرض پردازش متن (HTML, Markdown, یا None)
    proxy=None,               # پروکسی برای اتصال به API تلگرام
    timeout=30,               # زمان انتظار برای درخواست‌های API
    use_webhook=False,        # استفاده از وبهوک به جای پولینگ
    webhook_url=None,         # آدرس وبهوک (اگر use_webhook=True باشد)
    webhook_port=8443,        # پورت وبهوک
    debug=False               # فعال‌سازی حالت اشکال‌زدایی
)

متدهای مهم کلاس TelegramBot

متد	توضیحات
send_message(chat_id, text, reply_markup=None)	ارسال پیام متنی به کاربر. پارامتر reply_markup می‌تواند برای افزودن دکمه‌ها استفاده شود.
send_photo(chat_id, photo, caption=None)	ارسال تصویر به کاربر. پارامتر photo می‌تواند آدرس فایل یا فایل ID باشد.
send_document(chat_id, document)	ارسال فایل به کاربر.
send_video(chat_id, video, caption=None)	ارسال ویدیو به کاربر.
send_audio(chat_id, audio, caption=None)	ارسال فایل صوتی به کاربر.
send_location(chat_id, latitude, longitude)	ارسال موقعیت جغرافیایی به کاربر.
register_message_handler(handler, commands=None)	ثبت تابع پردازش‌کننده برای دستورات خاص.
register_callback_query_handler(handler, callback_data=None)	ثبت تابع پردازش‌کننده برای دکمه‌های اینلاین.
register_content_type_handler(handler, content_types)	ثبت تابع پردازش‌کننده برای انواع محتوا مانند عکس، ویدیو و غیره.
create_reply_keyboard(buttons)	ایجاد کیبورد پاسخ برای افزودن به پیام‌ها.
create_inline_keyboard(buttons)	ایجاد کیبورد اینلاین برای افزودن به پیام‌ها.
polling(timeout=30)	شروع گوش دادن به رویدادهای تلگرام و اجرای پردازش‌کننده‌های مناسب.
set_webhook(url)	تنظیم وبهوک برای دریافت آپدیت‌ها.
delete_webhook()	حذف وبهوک و بازگشت به حالت پولینگ.
send_chat_action(chat_id, action='typing')	نمایش وضعیت فعالیت ربات (مانند در حال تایپ کردن).
answer_callback_query(callback_query_id, text=None)	پاسخ به یک callback query از دکمه‌های اینلاین.
edit_message_text(chat_id, message_id, text)	ویرایش متن یک پیام قبلی.
delete_message(chat_id, message_id)	حذف یک پیام.
get_user_profile_photos(user_id)	دریافت عکس‌های پروفایل یک کاربر.
get_chat(chat_id)	دریافت اطلاعات یک چت.
get_chat_member(chat_id, user_id)	دریافت اطلاعات یک عضو چت.
ban_chat_member(chat_id, user_id)	مسدود کردن یک کاربر از چت.
unban_chat_member(chat_id, user_id)	رفع مسدودیت یک کاربر از چت.
pin_chat_message(chat_id, message_id)	سنجاق کردن یک پیام در چت.

ارسال پیام‌ها

ارسال پیام متنی ساده

bot.send_message(chat_id, 'سلام! به ربات من خوش آمدید.')

ارسال پیام با فرمت HTML

bot.send_message(
    chat_id,
    '<b>سلام!</b> به ربات <i>من</i> خوش آمدید.',
    parse_mode='HTML'
)

ارسال پیام با فرمت Markdown

bot.send_message(
    chat_id,
    '*سلام!* به ربات _من_ خوش آمدید.',
    parse_mode='Markdown'
)

ارسال پیام با دکمه‌های پاسخ

keyboard = bot.create_reply_keyboard([
    ['گزینه ۱', 'گزینه ۲'],
    ['گزینه ۳']
])

bot.send_message(
    chat_id,
    'لطفاً یک گزینه را انتخاب کنید:',
    reply_markup=keyboard
)

ارسال پیام با دکمه‌های اینلاین

keyboard = bot.create_inline_keyboard([
    [{'text': 'گزینه ۱', 'callback_data': 'option_1'}],
    [{'text': 'گزینه ۲', 'callback_data': 'option_2'}],
    [{'text': 'وب‌سایت ما', 'url': 'https://example.com'}]
])

bot.send_message(
    chat_id,
    'لطفاً یک گزینه را انتخاب کنید:',
    reply_markup=keyboard
)

ویرایش پیام‌های قبلی

def update_message(message):
    # ارسال پیام اولیه
    sent_message = bot.send_message(message.chat.id, 'در حال بارگذاری...')
    
    # انجام عملیات طولانی مدت
    # ...
    
    # ویرایش پیام
    bot.edit_message_text(
        message.chat.id,
        sent_message.message_id,
        'عملیات با موفقیت انجام شد!'
    )

حذف پیام‌ها

def delete_after_delay(message):
    # ارسال پیام
    sent_message = bot.send_message(message.chat.id, 'این پیام بعد از ۵ ثانیه حذف می‌شود.')
    
    # تاخیر ۵ ثانیه‌ای
    import time
    time.sleep(5)
    
    # حذف پیام
    bot.delete_message(message.chat.id, sent_message.message_id)

کار با کیبوردها

کیبورد پاسخ (Reply Keyboard)

کیبوردهای پاسخ جایگزین کیبورد معمولی کاربر می‌شوند و برای گرفتن ورودی‌های ساده مناسب هستند.

def show_main_menu(message):
    # ایجاد کیبورد پاسخ
    keyboard = bot.create_reply_keyboard([
        ['ثبت سفارش 🛍', 'استعلام سفارش 🧪'],
        ['محصولات 📦', 'درباره ما 🏢'],
        ['پشتیبانی 👨‍💻', 'تماس با ما 📞']
    ], resize_keyboard=True, one_time_keyboard=False)
    
    # ارسال پیام با کیبورد
    bot.send_message(
        message.chat.id,
        'به فروشگاه ما خوش آمدید. لطفاً یک گزینه را انتخاب کنید:',
        reply_markup=keyboard
    )

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

keyboard = bot.create_reply_keyboard(
    buttons,                # آرایه دو بعدی از دکمه‌ها
    resize_keyboard=True,   # تغییر اندازه خودکار کیبورد
    one_time_keyboard=False, # استفاده یک‌بار از کیبورد
    selective=False         # نمایش کیبورد فقط برای کاربران خاص
)

کیبورد اینلاین (Inline Keyboard)

کیبوردهای اینلاین به پیام متصل می‌شوند و می‌توانند اکشن‌های مختلفی مانند بازکردن URL یا ارسال callback data را انجام دهند.

def show_product(message, product_id):
    # ایجاد کیبورد اینلاین
    keyboard = bot.create_inline_keyboard([
        [
            {'text': '➕ افزودن به سبد خرید', 'callback_data': f'add_to_cart_{product_id}'},
            {'text': '❤️ افزودن به علاقه‌مندی‌ها', 'callback_data': f'add_to_wishlist_{product_id}'}
        ],
        [{'text': '📋 مشخصات فنی', 'callback_data': f'specs_{product_id}'}],
        [{'text': '🌐 مشاهده در وب‌سایت', 'url': f'https://example.com/product/{product_id}'}]
    ])
    
    # ارسال اطلاعات محصول با کیبورد
    bot.send_message(
        message.chat.id,
        f'محصول: کفش ورزشی برند X\nقیمت: ۵۰۰,۰۰۰ تومان\nموجودی انبار: ۱۵ عدد',
        reply_markup=keyboard
    )

انواع دکمه‌های اینلاین

# دکمه با callback data
{'text': 'متن دکمه', 'callback_data': 'داده برگشتی'}

# دکمه URL
{'text': 'متن دکمه', 'url': 'https://example.com'}

# دکمه سوئیچ به حالت اینلاین
{'text': 'متن دکمه', 'switch_inline_query': 'متن پیش‌فرض'}

# دکمه سوئیچ به حالت اینلاین در چت فعلی
{'text': 'متن دکمه', 'switch_inline_query_current_chat': 'متن پیش‌فرض'}

# دکمه بازی اینلاین
{'text': 'متن دکمه', 'callback_game': {}}

# دکمه پرداخت
{'text': 'متن دکمه', 'pay': True}

حذف کیبورد

def remove_keyboard(message):
    # ایجاد کیبورد خالی برای حذف کیبورد قبلی
    keyboard = bot.create_reply_keyboard([], remove_keyboard=True)
    
    bot.send_message(
        message.chat.id,
        'کیبورد حذف شد.',
        reply_markup=keyboard
    )

پردازش پیام‌های دریافتی

پردازش دستورات

def start_command(message):
    bot.send_message(message.chat.id, 'ربات شروع به کار کرد!')

def help_command(message):
    bot.send_message(message.chat.id, 'راهنمای استفاده از ربات')

# ثبت پردازش‌کننده‌ها برای دستورات مختلف
bot.register_message_handler(start_command, ['start'])
bot.register_message_handler(help_command, ['help', 'راهنما'])

پردازش پیام‌های متنی

def echo_all(message):
    # تکرار پیام دریافتی
    bot.send_message(message.chat.id, f'شما گفتید: {message.text}')

# ثبت پردازش‌کننده برای تمام پیام‌های متنی
bot.register_message_handler(echo_all, content_types=['text'])

پردازش محتوای خاص

def process_photo(message):
    # دریافت عکس
    bot.send_message(message.chat.id, 'عکس زیبایی بود!')

def process_document(message):
    # دریافت فایل
    bot.send_message(message.chat.id, 'فایل دریافت شد.')

# ثبت پردازش‌کننده‌ها برای انواع محتوا
bot.register_content_type_handler(process_photo, ['photo'])
bot.register_content_type_handler(process_document, ['document'])

پردازش کلیک‌های دکمه‌های اینلاین

def process_callback_query(callback_query):
    # استخراج اطلاعات از callback_data
    data = callback_query.data
    
    # پاسخ به کاربر
    bot.answer_callback_query(
        callback_query.id,
        'درخواست شما در حال پردازش است...'
    )
    
    if data.startswith('add_to_cart_'):
        product_id = data.split('_')[-1]
        bot.send_message(
            callback_query.message.chat.id,
            f'محصول با شناسه {product_id} به سبد خرید شما اضافه شد.'
        )
    elif data.startswith('add_to_wishlist_'):
        product_id = data.split('_')[-1]
        bot.send_message(
            callback_query.message.chat.id,
            f'محصول با شناسه {product_id} به لیست علاقه‌مندی‌های شما اضافه شد.'
        )
    
# ثبت پردازش‌کننده برای تمام callback query ها
bot.register_callback_query_handler(process_callback_query)

# یا ثبت برای الگوی خاص
bot.register_callback_query_handler(process_callback_query, 'add_to_cart')

مدیریت فایل‌ها و رسانه‌ها

ارسال تصویر

# ارسال تصویر با آدرس فایل
bot.send_photo(
    chat_id,
    'path/to/image.jpg',
    caption='تصویر محصول'
)

# ارسال تصویر با فایل باینری
with open('path/to/image.jpg', 'rb') as photo:
    bot.send_photo(
        chat_id,
        photo,
        caption='تصویر محصول'
    )

ارسال ویدیو

# ارسال ویدیو
with open('path/to/video.mp4', 'rb') as video:
    bot.send_video(
        chat_id,
        video,
        caption='ویدیوی محصول',
        width=640,
        height=480,
        duration=15
    )

ارسال فایل (سند)

# ارسال فایل
with open('path/to/document.pdf', 'rb') as document:
    bot.send_document(
        chat_id,
        document,
        caption='راهنمای محصول'
    )

ارسال فایل صوتی

# ارسال فایل صوتی
with open('path/to/audio.mp3', 'rb') as audio:
    bot.send_audio(
        chat_id,
        audio,
        caption='فایل صوتی',
        performer='نام خواننده',
        title='عنوان آهنگ',
        duration=180
    )

ارسال استیکر

# ارسال استیکر
bot.send_sticker(
    chat_id,
    'sticker_file_id'
)

ارسال موقعیت جغرافیایی

# ارسال موقعیت جغرافیایی
bot.send_location(
    chat_id,
    latitude=35.7219,
    longitude=51.3347
)

دریافت فایل‌های کاربر

def handle_photo(message):
    # دریافت لیست تصاویر با سایزهای مختلف
    photos = message.photo
    
    # انتخاب بزرگترین سایز
    largest_photo = photos[-1]
    
    # دریافت شناسه فایل
    file_id = largest_photo.file_id
    
    # دریافت اطلاعات فایل
    file_info = bot.get_file(file_id)
    
    # دانلود فایل
    downloaded_file = bot.download_file(file_info.file_path)
    
    # ذخیره فایل
    with open(f"downloaded_photo_{file_id}.jpg", 'wb') as new_file:
        new_file.write(downloaded_file)
    
    bot.reply_to(message, 'تصویر شما با موفقیت دریافت و ذخیره شد.')

# ثبت پردازش‌کننده برای دریافت تصاویر
bot.register_content_type_handler(handle_photo, ['photo'])

مدیریت گروه‌ها و کانال‌ها

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

def get_chat_info(message):
    chat_id = message.chat.id
    
    # دریافت اطلاعات چت
    chat_info = bot.get_chat(chat_id)
    
    # نمایش اطلاعات
    info_text = f"شناسه چت: {chat_info.id}\n"
    info_text += f"نوع: {chat_info.type}\n"
    info_text += f"عنوان: {chat_info.title}\n"
    
    if chat_info.username:
        info_text += f"نام کاربری: @{chat_info.username}\n"
    
    if chat_info.description:
        info_text += f"توضیحات: {chat_info.description}\n"
    
    bot.send_message(chat_id, info_text)

دریافت اطلاعات اعضای گروه

def get_chat_member_info(message):
    chat_id = message.chat.id
    user_id = message.from_user.id
    
    # دریافت اطلاعات کاربر در گروه
    member = bot.get_chat_member(chat_id, user_id)
    
    # نمایش اطلاعات
    info_text = f"نام: {member.user.first_name}\n"
    if member.user.last_name:
        info_text += f"نام خانوادگی: {member.user.last_name}\n"
    
    info_text += f"شناسه: {member.user.id}\n"
    info_text += f"وضعیت: {member.status}\n"
    
    bot.send_message(chat_id, info_text)