ساخت ربات تلگرام با پایتون و Kurigram (Pyrogram)

مرحله 1 : نصب پایتون

برای شروع توسعه ربات تلگرام با پایتون، ابتدا باید پایتون را نصب کنید.

نصب پایتون روی ویندوز

• به سایت رسمی پایتون بروید: https://www.python.org/downloads/
• آخرین نسخه پایدار پایتون را دانلود و نصب کنید.
• تیک Add Python to PATH را در ابتدای نصب فعال کنید.

برای اطمینان از نصب، ترمینال (Command Prompt) را باز کرده و دستور زیر را اجرا کنید:

python --version

نصب پایتون روی اوبونتو

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

sudo apt update

پایتون و pip را نصب کنید:

sudo apt install python3 python3-pip -y

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

python3 --version

مرحله 2 : نصب محیط مجازی (virtualenv)

برای مدیریت پروژه‌ها و جلوگیری از تداخل پکیج‌ها، استفاده از محیط مجازی توصیه می‌شود.

نصب virtualenv با pip:

pip install virtualenv

بعد از نصب باید پوشه جدا برای فایل های پروژه ایجاد کنیم :

mkdir bot
cd bot

ایجاد محیط مجازی در مسیر پروژه:

virtualenv venv

فعال‌سازی محیط مجازی:

ویندوز:

venv\Scripts\activate

لینوکس / اوبونتو:

source venv/bin/activate

بعد از فعال‌سازی، باید ببینید که ابتدای ترمینال عبارت (venv) نمایش داده می‌شود.

مرحله 3 : نصب Kurigram

حال می‌توانیم فورک Pyrogram یعنی Kurigram را نصب کنیم:

دستور نصب Kurigram:

pip install kurigram

نصب tgcrypto و دلیل استفاده از آن

در آموزش نصب ربات تلگرام با Pyrogram یا فورک آن Kurigram، بهتر است tgcrypto نیز نصب شود. دلیل این کار این است که:

• tgcrypto یک کتابخانه اختیاری برای Pyrogram است که عملیات رمزنگاری (Encryption/Decryption) پیام‌ها را بسیار سریع‌تر انجام می‌دهد.
• بدون tgcrypto، Pyrogram از پیاده‌سازی پایتونی خودش استفاده می‌کند که کندتر است، مخصوصا وقتی ربات شما پیام‌های زیادی ارسال یا دریافت می‌کند.
• با نصب tgcrypto، سرعت رمزگشایی پیام‌ها، دانلود فایل‌ها و عملکرد کلی ربات به شکل قابل توجهی افزایش پیدا می‌کند.

دستور نصب:

pip install tgcrypto

بعد از نصب، Pyrogram به صورت خودکار از tgcrypto استفاده می‌کند و نیازی به تغییر کد نیست.

دریافت توکن ربات و API ID/Hash برای Kurigram

قبل از اینکه ربات خود را بسازید، باید چند مقدار مهم را از تلگرام دریافت کنید:

1. توکن ربات:
   • وارد BotFather در تلگرام شوید.
   • دستور /newbot را بفرستید.
   • نام و نام کاربری ربات خود را انتخاب کنید.
   • BotFather یک توکن شبیه به 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 به شما می‌دهد. این توکن برای شناسایی ربات شما استفاده می‌شود.
2. API ID و API Hash:
   • به my.telegram.org بروید و وارد حساب تلگرام خود شوید.
   • روی API Development Tools کلیک کنید.
   • یک اپلیکیشن جدید بسازید و نام و توضیحات وارد کنید.
   • سپس یک API ID و API Hash دریافت خواهید کرد.
   • این مقادیر برای اتصال Kurigram (یا Pyrogram) به تلگرام لازم هستند.

چرا این موارد لازم هستند ؟

• توکن ربات: به تلگرام می‌گوید که شما مالک ربات هستید و اجازه دارید با API آن کار کنید.
• API ID و Hash: برای احراز هویت و ایجاد نشست امن بین ربات و سرور تلگرام استفاده می‌شوند.
• بدون این مقادیر، ربات نمی‌تواند پیام‌ها را دریافت یا ارسال کند.

توجه داشته باشید که جدیدا تلگرام روی گرفتن api id محدودیت زیادی گذاشته که باید با آیپی ها خاص وارد سایتش بشید از جمله ترکیه تا بنوانید api id دریافت کنید و اگر نتوانستید دریافت کنید اشکالی نداره و میتونید از api id که داخل کد گذاشتیم استفاده کنید.

ساخت ربات Echo با Kurigram

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

کد و توضیح خط به خط:

# ایمپورت کلاس‌ها از Pyrogram
from pyrogram import Client, filters
from pyrogram.types import Message

# مقادیر واقعی توکن و API
API_ID = 15517774
API_HASH = "efb49ae0b3c7323342f31d26a4c99ec3"
BOT_TOKEN = "8478391174:AAE0WztfhKwrWK9PjZRZZhHZ00KWvN1Wqjo"

# ساخت کلاینت ربات
# "my_bot" اسم سشن ربات هست
app = Client("my_bot", api_id=API_ID, api_hash=API_HASH, bot_token=BOT_TOKEN)

# تعریف هندلر برای پیام‌های متنی
@app.on_message(filters.text)
def echo(client, message: Message):
    # هر پیامی که دریافت شد، همان را به کاربر برمی‌گرداند
    message.reply_text(message.text)

# اجرای ربات
print("bot started !")
app.run()

توضیح عملکرد:

• وقتی کاربر پیامی می‌فرستد، دکوریتور @app.on_message(filters.text) فعال می‌شود و تابع echo اجرا می‌شود.
• داخل تابع echo، message.reply_text(message.text) همان متن دریافتی را دوباره برای کاربر می‌فرستد.
• در واقع، ربات ما یک Echo Bot ساده است که همه پیام‌های متنی را برمی‌گرداند.
• این ساختار پایه برای ربات‌های پیچیده‌تر است و می‌توان بعداً انواع فیلترها و دستورات مختلف اضافه کرد.

خب حالا کافیه کد بالا رو داخل یک فایل پایتونی بزارید به اسم bot.py و ذخیره کنید و با دستور زیر فایل رو اجرا کنید البته توجه داشته باشید که فایل رو داخل پوشه bot ذخیره کنید و محیط مجازی فعال باشه.

python bot.py

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

روش‌های اجرای ربات تلگرام

1) Polling (روش پرس‌وجو)

در این روش، ربات به طور مداوم از سرور تلگرام می‌پرسد که آیا پیام جدیدی برای آن آمده است یا نه. ربات به صورت مرتب (مثلاً هر چند ثانیه) درخواست دریافت پیام‌ها می‌فرستد و پاسخ می‌دهد.

• مزایا:
  • ساده و راحت برای شروع؛ نیاز به سرور همیشه روشن ندارد.
  • مناسب ربات‌های کوچک و تست اولیه.
  • پیاده‌سازی و دیباگ آسان است.
• معایب:
  • اگر تعداد کاربرها زیاد باشد، درخواست‌های متناوب باعث بار زیاد روی سرور تلگرام و ربات می‌شود.
  • سرعت پاسخ‌دهی کمی کندتر است.
  • مصرف اینترنت و منابع بیشتر نسبت به webhook دارد.

2) Webhook (روش وبهوک)

در این روش، سرور تلگرام وقتی پیامی برای ربات می‌آید، به طور مستقیم یک درخواست HTTP به URL مشخص شده (سرور شما) می‌فرستد و ربات همان لحظه پاسخ می‌دهد. یعنی ربات منتظر پیام نمی‌ماند بلکه تلگرام خودش پیام را ارسال می‌کند.

• مزایا:
  • سریع‌تر و بهینه‌تر است، چون هر پیام مستقیم به ربات می‌رسد.
  • مصرف منابع و اینترنت بسیار کمتر از polling است.
  • مناسب ربات‌های حرفه‌ای، پرکاربر یا تجاری است.
• معایب:
  • نیاز به سرور دائماً روشن و با SSL معتبر (HTTPS) دارد.
  • پیاده‌سازی پیچیده‌تر است و نیاز به پیکربندی سرور دارد.
  • برای شروع و آموزش ساده کمی دشوارتر از polling است.

مقایسه سریع Polling و Webhook

نکته آموزشی: اگر تازه‌کار هستید یا می‌خواهید ربات ساده تست کنید، از Polling استفاده کنید. اما برای ربات واقعی و با کاربران زیاد، Webhook مناسب‌تر و بهینه‌تر است.

جمع‌بندی

در این آموزش، یاد گرفتیم چطور یک ربات ساده تلگرام با Python و Pyrogram (Kurigram) بسازیم که پیام‌های دریافتی را Echo کند.

مراحل اصلی شامل موارد زیر بود:

1. دریافت توکن و API ID از Telegram BotFather و my.telegram.org که برای اتصال ربات به تلگرام ضروری هستند.
2. ساخت محیط مجازی برای مدیریت بسته‌ها و جلوگیری از تداخل با سیستم.
3. نصب کتابخانه‌ها مثل Pyrogram و tgcrypto که باعث می‌شوند ارتباط ربات با تلگرام سریع و پایدار باشد.
4. نوشتن کد ربات در فایل bot.py، با توضیح کامل هر خط کد تا بتوانید عملکردش را درک کنید.
5. اجرای ربات با دستور python bot.py و تست آن در تلگرام.

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