telegrampx 1.3.0
یک کتابخانه فوق سریع برای ربات تلگرام
Requires Python: >=3.6

```markdown
# داکیومنت

لینک داکیومنت ("https://iliya8989.github.io/telegrampx/")
```
# TelegramPX
## کتابخانه قدرتمند و ساده پایتون برای ساخت ربات‌های تلگرام

![TelegramPX Logo](https://via.placeholder.com/150)

## فهرست مطالب
- [معرفی](#معرفی)
- [ویژگی‌های اصلی](#ویژگی‌های-اصلی)
- [نصب و راه‌اندازی](#نصب-و-راه‌اندازی)
- [ساخت اولین ربات](#ساخت-اولین-ربات)
- [کلاس TelegramBot](#کلاس-telegrambot)
- [ارسال پیام‌ها](#ارسال-پیام‌ها)
- [کار با کیبوردها](#کار-با-کیبوردها)
- [پردازش پیام‌های دریافتی](#پردازش-پیام‌های-دریافتی)
- [مدیریت فایل‌ها و رسانه‌ها](#مدیریت-فایل‌ها-و-رسانه‌ها)
- [مدیریت گروه‌ها و کانال‌ها](#مدیریت-گروه‌ها-و-کانال‌ها)
- [مدیریت وضعیت کاربر](#مدیریت-وضعیت-کاربر)
- [وبهوک و پولینگ](#وبهوک-و-پولینگ)
- [ذخیره‌سازی داده‌ها](#ذخیره‌سازی-داده‌ها)
- [نمونه‌های کاربردی](#نمونه‌های-کاربردی)
- [مباحث پیشرفته](#مباحث-پیشرفته)
- [عیب‌یابی و رفع خطاها](#عیب‌یابی-و-رفع-خطاها)
- [سوالات متداول](#سوالات-متداول)

## معرفی

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

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

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

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

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

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

```bash
pip install telegrampx
```

### نیازمندی‌ها

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

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

برای ایجاد اولین ربات، ابتدا باید یک توکن از [BotFather](https://t.me/BotFather) دریافت کنید. سپس می‌توانید با کد زیر یک ربات ساده ایجاد کنید:

```python
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 تلگرام است. تمام عملیات ربات از طریق این کلاس انجام می‌شود.

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

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

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

```python
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)` | سنجاق کردن یک پیام در چت. |

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

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

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

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

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

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

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

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

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

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

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

```python
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
)
```

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

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

### حذف پیام‌ها

```python
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)

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

```python
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
    )
```

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

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

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

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

```python
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
    )
```

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

```python
# دکمه با 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}
```

### حذف کیبورد

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

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

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

```python
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', 'راهنما'])
```

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

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

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

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

```python
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'])
```

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

```python
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')
```

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

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

```python
# ارسال تصویر با آدرس فایل
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='تصویر محصول'
    )
```

### ارسال ویدیو

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

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

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

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

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

### ارسال استیکر

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

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

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

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

```python
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'])
```

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

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

```python
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)
```

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

```python
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)
```