“`html

چگونه با پایتون یک ربات تلگرام بسازیم؟

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

1. پیش‌نیازها و مقدمات

قبل از شروع به کدنویسی، اطمینان حاصل کنید که پیش‌نیازهای زیر را آماده کرده‌اید:

• پایتون نصب شده باشد: مطمئن شوید که پایتون 3.6 یا بالاتر بر روی سیستم شما نصب شده است. می‌توانید از طریق وب‌سایت رسمی پایتون (python.org) آخرین نسخه را دانلود و نصب کنید.
• یک ویرایشگر کد (IDE) یا ویرایشگر متن: از یک ویرایشگر کد مانند VS Code، PyCharm، Sublime Text یا هر ویرایشگر متن دیگری که با آن راحت هستید، استفاده کنید.
• آشنایی اولیه با پایتون: داشتن دانش پایه در مورد متغیرها، توابع، حلقه‌ها و ساختارهای داده در پایتون ضروری است.
• دسترسی به اینترنت: برای ارتباط با API تلگرام، به اتصال اینترنت نیاز دارید.

1.1. ایجاد یک ربات تلگرام و دریافت Token

برای اینکه بتوانید با API تلگرام کار کنید، ابتدا باید یک ربات جدید در تلگرام ایجاد کنید و یک Token (توکن) دریافت کنید. Token یک رشته منحصر به فرد است که به ربات شما اجازه می‌دهد تا با سرورهای تلگرام ارتباط برقرار کند.

مراحل زیر را دنبال کنید:

1. به ربات Father@ در تلگرام پیام دهید: در تلگرام، ربات Father@ را جستجو کنید و Start را بزنید.
2. دستور /newbot را ارسال کنید: با این دستور، فرآیند ایجاد یک ربات جدید آغاز می‌شود.
3. یک نام برای ربات خود انتخاب کنید: یک نام جذاب و مرتبط با کارکرد ربات انتخاب کنید. این نام برای نمایش به کاربران استفاده می‌شود.
4. یک نام کاربری (Username) برای ربات انتخاب کنید: نام کاربری باید منحصر به فرد باشد و با کلمه “bot” به پایان برسد (به عنوان مثال: MyAwesomeBot).
5. Token را دریافت کنید: پس از انتخاب نام کاربری، ربات Father@ یک Token به شما ارائه می‌دهد. این Token را در جای امنی ذخیره کنید، زیرا برای کنترل ربات خود به آن نیاز دارید.

نکته مهم: Token خود را با هیچ کس به اشتراک نگذارید. Token مانند رمز عبور ربات شما است و هر کسی که به آن دسترسی داشته باشد، می‌تواند ربات شما را کنترل کند.

2. نصب کتابخانه‌های مورد نیاز

برای ارتباط با API تلگرام در پایتون، به یک کتابخانه نیاز دارید. دو کتابخانه محبوب برای این کار عبارتند از:

• PyTelegramBotAPI: یک کتابخانه ساده و آسان برای استفاده که توابع مختلف API تلگرام را به صورت شیءگرا ارائه می‌دهد.
• Telethon: یک کتابخانه قدرتمند و ناهمزمان (Asynchronous) که برای ساخت ربات‌های پیچیده و با کارایی بالا مناسب است.

در این آموزش، از کتابخانه PyTelegramBotAPI استفاده خواهیم کرد، زیرا برای شروع کار مناسب‌تر است. برای نصب این کتابخانه، از pip استفاده کنید:

pip install pyTelegramBotAPI

اگر از virtual environment استفاده می‌کنید، ابتدا آن را فعال کنید و سپس دستور بالا را اجرا کنید.

3. ایجاد یک ربات ساده با PyTelegramBotAPI

اکنون که کتابخانه PyTelegramBotAPI را نصب کرده‌اید، می‌توانید شروع به کدنویسی کنید. در اینجا یک مثال ساده از یک ربات تلگرام که به دستور “/start” پاسخ می‌دهد، آورده شده است:

 import telebot

 # جایگزین کنید با Token خود
 BOT_TOKEN = 'YOUR_TELEGRAM_BOT_TOKEN'

 bot = telebot.TeleBot(BOT_TOKEN)

 @bot.message_handler(commands=['start', 'hello'])
 def send_welcome(message):
  bot.reply_to(message, "سلام! من یک ربات تلگرام هستم.")

 print("ربات در حال اجرا است...")
 bot.infinity_polling()
 

توضیحات کد:

• import telebot: کتابخانه PyTelegramBotAPI را وارد می‌کند.
• BOT_TOKEN = 'YOUR_TELEGRAM_BOT_TOKEN': Token ربات خود را در این متغیر قرار دهید.
• bot = telebot.TeleBot(BOT_TOKEN): یک شیء از کلاس TeleBot ایجاد می‌کند و Token را به آن پاس می‌دهد.
• @bot.message_handler(commands=['start', 'hello']): یک دکوراتور است که تابعی را به عنوان یک هندلر برای پیام‌هایی با دستورات “/start” و “/hello” ثبت می‌کند.
• def send_welcome(message):: تابعی است که وقتی یک پیام با دستورات مشخص شده دریافت شود، اجرا می‌شود. این تابع یک شیء message را به عنوان ورودی دریافت می‌کند که شامل اطلاعات مربوط به پیام است.
• bot.reply_to(message, "سلام! من یک ربات تلگرام هستم."): به پیام دریافتی با متن “سلام! من یک ربات تلگرام هستم.” پاسخ می‌دهد.
• bot.infinity_polling(): ربات را در حالت polling قرار می‌دهد. این به این معنی است که ربات به طور مداوم سرورهای تلگرام را بررسی می‌کند تا پیام‌های جدید را دریافت کند.

برای اجرای این کد، آن را در یک فایل پایتون (به عنوان مثال: bot.py) ذخیره کنید و سپس از طریق ترمینال اجرا کنید:

python bot.py

اکنون می‌توانید به ربات خود در تلگرام پیام دهید و دستور “/start” یا “/hello” را ارسال کنید. ربات باید با پیام “سلام! من یک ربات تلگرام هستم.” پاسخ دهد.

4. مدیریت پیام‌ها و دستورات

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

4.1. دریافت اطلاعات پیام

شیء message که به تابع هندلر پاس داده می‌شود، شامل اطلاعات مختلفی در مورد پیام است، از جمله:

• message.chat.id: شناسه چت (Chat ID) که پیام در آن ارسال شده است.
• message.text: متن پیام.
• message.from_user.id: شناسه کاربر (User ID) که پیام را ارسال کرده است.
• message.from_user.username: نام کاربری کاربر.
• message.date: تاریخ و زمان ارسال پیام.

برای مثال، می‌توانید کد زیر را برای چاپ اطلاعات پیام در کنسول استفاده کنید:

 @bot.message_handler(func=lambda message: True)
 def echo_all(message):
  print(f"Chat ID: {message.chat.id}")
  print(f"Text: {message.text}")
  print(f"User ID: {message.from_user.id}")
  print(f"Username: {message.from_user.username}")
  print(f"Date: {message.date}")
  bot.reply_to(message, message.text)
 

این کد هر پیامی که به ربات ارسال شود را دریافت می‌کند و اطلاعات آن را در کنسول چاپ می‌کند. همچنین، ربات متن پیام را به عنوان پاسخ ارسال می‌کند.

4.2. مدیریت دستورات مختلف

می‌توانید از دکوراتور @bot.message_handler برای ثبت هندلرهای مختلف برای دستورات مختلف استفاده کنید. برای مثال، کد زیر نحوه مدیریت دستورات “/help” و “/info” را نشان می‌دهد:

 @bot.message_handler(commands=['help'])
 def send_help(message):
  help_text = """
  لیست دستورات:
  /start - شروع ربات
  /help - نمایش راهنما
  /info - نمایش اطلاعات
  """
  bot.reply_to(message, help_text)

 @bot.message_handler(commands=['info'])
 def send_info(message):
  info_text = f"""
  اطلاعات کاربر:
  User ID: {message.from_user.id}
  Username: {message.from_user.username}
  """
  bot.reply_to(message, info_text)
 

در این کد، دستور “/help” یک متن راهنما را نمایش می‌دهد و دستور “/info” اطلاعات کاربر را نشان می‌دهد.

4.3. مدیریت متن‌های خاص

علاوه بر دستورات، می‌توانید هندلرهایی را برای متن‌های خاص نیز ثبت کنید. برای مثال، کد زیر نحوه پاسخ دادن به پیام‌های حاوی کلمه “سلام” را نشان می‌دهد:

 @bot.message_handler(func=lambda message: 'سلام' in message.text)
 def send_hello(message):
  bot.reply_to(message, "سلام بر شما!")
 

این کد هر پیامی که حاوی کلمه “سلام” باشد را دریافت می‌کند و با پیام “سلام بر شما!” پاسخ می‌دهد.

5. ارسال پیام‌های پیشرفته

PyTelegramBotAPI امکانات گسترده‌ای برای ارسال پیام‌های پیشرفته فراهم کرده است، از جمله:

• ارسال عکس، فیلم، صدا و فایل: می‌توانید از توابع send_photo، send_video، send_audio و send_document برای ارسال انواع مختلف فایل استفاده کنید.
• ارسال موقعیت مکانی: می‌توانید از تابع send_location برای ارسال موقعیت مکانی کاربر استفاده کنید.
• ارسال نظرسنجی (Poll): می‌توانید از تابع send_poll برای ایجاد و ارسال نظرسنجی استفاده کنید.
• استفاده از کیبوردهای سفارشی (Custom Keyboards): می‌توانید از کیبوردهای سفارشی برای ارائه گزینه‌های انتخاب به کاربران استفاده کنید.
• ویرایش پیام‌ها: می‌توانید از تابع edit_message_text برای ویرایش پیام‌های ارسالی استفاده کنید.

5.1. ارسال عکس

برای ارسال یک عکس، می‌توانید از تابع send_photo استفاده کنید. کد زیر یک مثال از ارسال یک عکس از یک URL را نشان می‌دهد:

 @bot.message_handler(commands=['photo'])
 def send_photo(message):
  photo_url = 'https://www.easygifanimator.net/images/samples/video-to-gif-sample.gif'
  bot.send_photo(message.chat.id, photo_url)
 

این کد یک عکس از URL مشخص شده را به چت ارسال می‌کند.

5.2. استفاده از کیبورد سفارشی

برای ایجاد یک کیبورد سفارشی، می‌توانید از کلاس ReplyKeyboardMarkup استفاده کنید. کد زیر یک مثال از ایجاد یک کیبورد با دو دکمه “بله” و “خیر” را نشان می‌دهد:

 from telebot import types

 @bot.message_handler(commands=['keyboard'])
 def send_keyboard(message):
  keyboard = types.ReplyKeyboardMarkup(row_width=2)
  itembtn1 = types.KeyboardButton('بله')
  itembtn2 = types.KeyboardButton('خیر')
  keyboard.add(itembtn1, itembtn2)
  bot.send_message(message.chat.id, "آیا موافق هستید؟", reply_markup=keyboard)
 

این کد یک کیبورد با دو دکمه “بله” و “خیر” را به چت ارسال می‌کند. وقتی کاربر یکی از دکمه‌ها را فشار دهد، متن دکمه به عنوان یک پیام به ربات ارسال می‌شود.

6. استفاده از Inline Keyboards

علاوه بر کیبوردهای سفارشی (Reply Keyboards)، تلگرام از Inline Keyboards نیز پشتیبانی می‌کند. Inline Keyboards به جای جایگزینی کیبورد کاربر، به صورت یک ردیف دکمه در زیر پیام نمایش داده می‌شوند. این نوع کیبوردها برای ارائه گزینه‌های تعاملی و اجرای دستورات بدون نیاز به ارسال پیام مناسب هستند.

 from telebot import types

 @bot.message_handler(commands=['inline'])
 def send_inline_keyboard(message):
  markup = types.InlineKeyboardMarkup()
  itembtn1 = types.InlineKeyboardButton('وبسایت', url='http://www.example.com')
  itembtn2 = types.InlineKeyboardButton('تماس با ما', callback_data='contact')
  markup.add(itembtn1, itembtn2)
  bot.send_message(message.chat.id, "به وبسایت ما خوش آمدید!", reply_markup=markup)

 @bot.callback_query_handler(func=lambda call: True)
 def callback_query(call):
  if call.data == 'contact':
   bot.answer_callback_query(call.id, "اطلاعات تماس: ...")
   bot.send_message(call.message.chat.id, "اطلاعات تماس: ...")
 

توضیحات کد:

• types.InlineKeyboardMarkup(): یک شیء از کلاس InlineKeyboardMarkup ایجاد می‌کند.
• types.InlineKeyboardButton('متن دکمه', url='آدرس'): یک دکمه Inline ایجاد می‌کند که وقتی کاربر روی آن کلیک می‌کند، به آدرس مشخص شده هدایت می‌شود.
• types.InlineKeyboardButton('متن دکمه', callback_data='داده'): یک دکمه Inline ایجاد می‌کند که وقتی کاربر روی آن کلیک می‌کند، یک Callback Query به ربات ارسال می‌شود.
• markup.add(itembtn1, itembtn2): دکمه‌ها را به کیبورد اضافه می‌کند.
• @bot.callback_query_handler(func=lambda call: True): یک دکوراتور است که تابعی را به عنوان یک هندلر برای Callback Queryها ثبت می‌کند.
• bot.answer_callback_query(call.id, "متن"): یک اعلان (Alert) کوچک را به کاربر نشان می‌دهد. این اعلان معمولاً برای تأیید دریافت Callback Query استفاده می‌شود.
• call.data: داده‌ای است که به همراه Callback Query ارسال شده است.

7. نکات پیشرفته و بهترین روش‌ها

برای ساخت ربات‌های تلگرامی حرفه‌ای و کارآمد، رعایت نکات زیر ضروری است:

• استفاده از وب‌هوک (Webhook): به جای polling، از وب‌هوک برای دریافت پیام‌ها استفاده کنید. وب‌هوک به ربات شما اجازه می‌دهد تا به طور آنی از پیام‌های جدید مطلع شود، که باعث افزایش سرعت و کارایی ربات می‌شود.
• مدیریت خطاها: خطاهای احتمالی را به درستی مدیریت کنید و به کاربران پیام‌های خطا مناسب را نمایش دهید.
• استفاده از پایگاه داده: اگر ربات شما نیاز به ذخیره اطلاعات دارد، از یک پایگاه داده مناسب (مانند SQLite، MySQL یا PostgreSQL) استفاده کنید.
• رعایت امنیت: از Token ربات خود محافظت کنید و از ارسال اطلاعات حساس در پیام‌ها خودداری کنید.
• بهینه‌سازی کد: کد خود را بهینه کنید تا ربات شما با سرعت و کارایی بالاتری اجرا شود.
• مستندسازی کد: کد خود را به طور کامل مستند کنید تا نگهداری و توسعه آن در آینده آسان‌تر باشد.

7.1. استفاده از Webhook

برای استفاده از Webhook، ابتدا باید یک سرور HTTPS داشته باشید. سپس، باید یک Endpoint در سرور خود ایجاد کنید که پیام‌های تلگرام را دریافت کند. در نهایت، باید از طریق API تلگرام، آدرس این Endpoint را به ربات خود معرفی کنید.

کد زیر یک مثال ساده از نحوه استفاده از Webhook در Flask را نشان می‌دهد:

 from flask import Flask, request
 import telebot

 BOT_TOKEN = 'YOUR_TELEGRAM_BOT_TOKEN'
 HEROKU_URL = 'YOUR_HEROKU_APP_URL'  # Replace with your Heroku app URL

 bot = telebot.TeleBot(BOT_TOKEN)
 app = Flask(__name__)

 @app.route('/' + BOT_TOKEN, methods=['POST'])
 def getMessage():
  bot.process_new_updates([telebot.types.Update.de_json(request.stream.read().decode('utf-8'))])
  return "!", 200

 @app.route("/")
 def webhook():
  bot.remove_webhook()
  bot.set_webhook(url=HEROKU_URL + BOT_TOKEN)
  return "!", 200

 @bot.message_handler(commands=['start'])
 def start_message(message):
  bot.send_message(message.chat.id, "سلام! من یک ربات تلگرام هستم.")

 if __name__ == "__main__":
  app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 5000)))
 

نکته: این کد فقط یک مثال ساده است و برای استفاده در محیط عملیاتی، نیاز به تغییرات و بهینه‌سازی دارد.

7.2. مدیریت خطاها

برای مدیریت خطاها، می‌توانید از بلوک‌های try...except استفاده کنید. کد زیر یک مثال از نحوه مدیریت خطای احتمالی هنگام ارسال عکس را نشان می‌دهد:

 @bot.message_handler(commands=['photo'])
 def send_photo(message):
  try:
   photo_url = 'https://www.example.com/invalid_image.jpg'
   bot.send_photo(message.chat.id, photo_url)
  except Exception as e:
   bot.reply_to(message, f"متاسفم، خطایی رخ داد: {e}")
 

این کد سعی می‌کند یک عکس از URL مشخص شده را ارسال کند. اگر خطایی رخ دهد (به عنوان مثال، اگر URL نامعتبر باشد)، یک پیام خطا به کاربر نمایش داده می‌شود.

نتیجه‌گیری

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

“`