khorasan-doc/docs/programming-languages-chapter3.md

فصل سه: شروع کار با کتابخانهٔ telebot

در فصل قبل فهمیدیم ربات‌های تلگرام و بله چطور با API کار می‌کنند. در این فصل می‌خواهیم یک قدم عملی‌تر برداریم و با کتابخانهٔ telebot در پایتون یک ربات ساده بسازیم.

نام اصلی پکیجی که نصب می‌کنیم pyTelegramBotAPI است، اما در کد با نام telebot از آن استفاده می‌کنیم.

telebot چیست؟

telebot یک کتابخانهٔ پایتونی است که کار با Bot API را ساده‌تر می‌کند. بدون کتابخانه باید خودمان با requests درخواست‌های HTTP بسازیم، آدرس‌ها را بنویسیم و پاسخ‌های JSON را پردازش کنیم. اما با telebot می‌توانیم ساده‌تر بنویسیم:

@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام!")

یعنی به جای اینکه همهٔ جزئیات HTTP را خودمان مدیریت کنیم، بیشتر روی منطق ربات تمرکز می‌کنیم.

نصب کتابخانه

برای نصب، بهتر است از محیط مجازی پایتون استفاده کنیم:

python -m venv .venv
source .venv/bin/activate
pip install pyTelegramBotAPI

در ویندوز فعال‌سازی محیط مجازی معمولاً این شکل است:

.venv\Scripts\activate

!!! warning "اشتباه رایج" پکیج درست pyTelegramBotAPI است. ممکن است پکیج‌هایی با نام‌های شبیه telebot هم وجود داشته باشند، اما برای این درس همین پکیج را نصب می‌کنیم و در کد import telebot می‌نویسیم.

گرفتن توکن ربات

برای شروع به یک توکن نیاز داریم. توکن مثل کلید ورود ربات است.

مراحل کلی:

1. در پیام‌رسان مورد نظر یک ربات یا بازو بسازید.
2. توکن ربات را دریافت کنید.
3. توکن را در کد یا بهتر از آن در متغیر محیطی قرار دهید.
4. برنامهٔ ربات را اجرا کنید.

برای پروژهٔ واقعی، بهتر است توکن را مستقیم داخل کد ننویسیم. اما برای تمرین‌های سادهٔ کلاسی، ممکن است اول کار توکن را موقتاً داخل کد بگذاریم تا مفهوم روشن شود.

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

یک فایل به نام bot.py بسازید:

import telebot

TOKEN = "توکن ربات را اینجا قرار دهید"

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام! ربات شروع به کار کرد.")


bot.infinity_polling()

حالا برنامه را اجرا کنید:

python bot.py

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

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

کتابخانهٔ telebot در اصل برای Bot API تلگرام نوشته شده است. چون ساختار Bot API بله شبیه تلگرام است، می‌توانیم آدرس API را تغییر بدهیم تا درخواست‌ها به سرور بله ارسال شوند.

برای بله باید این خط را اضافه کنیم:

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

این خط باید قبل از ساختن شیء TeleBot نوشته شود.

نمونهٔ ساده برای بله:

import telebot
from telebot import apihelper

TOKEN = "توکن ربات بله را اینجا قرار دهید"

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام! ربات بله آماده است.")


bot.infinity_polling()

اگر از تلگرام استفاده می‌کنید، این خط را لازم ندارید:

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

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

برنامهٔ بهتر با متغیر محیطی

نوشتن توکن داخل کد امن نیست. روش بهتر این است که توکن را از متغیر محیطی بخوانیم.

import os
import telebot

TOKEN = os.getenv("BOT_TOKEN")

if not TOKEN:
    raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام! ربات آماده است.")


bot.infinity_polling()

قبل از اجرا:

export BOT_TOKEN="توکن ربات"
python bot.py

برای بله، نسخهٔ متغیر محیطی این شکل می‌شود:

import os
import telebot
from telebot import apihelper

TOKEN = os.getenv("BOT_TOKEN")

if not TOKEN:
    raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام! ربات بله آماده است.")


bot.infinity_polling()

handler چیست؟

در telebot هر تابعی که قرار است به یک نوع پیام جواب بدهد، یک handler است. بالای تابع از دکوراتور @bot.message_handler استفاده می‌کنیم تا مشخص کنیم این تابع چه پیام‌هایی را بررسی کند.

مثلاً این handler فقط دستور /start را بررسی می‌کند:

@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام!")

این handler فقط دستور /help را بررسی می‌کند:

@bot.message_handler(commands=["help"])
def help_message(message):
    bot.reply_to(message, "دستورهای ربات: /start و /help")

پاسخ دادن به پیام معمولی

اگر بخواهیم ربات به همهٔ پیام‌های متنی جواب بدهد، می‌توانیم از content_types استفاده کنیم:

@bot.message_handler(content_types=["text"])
def echo(message):
    bot.reply_to(message, "پیام شما دریافت شد: " + message.text)

این ربات هر متنی را که کاربر بفرستد، با یک جملهٔ ساده پاسخ می‌دهد.

تفاوت reply_to و send_message

دو روش رایج برای پاسخ دادن:

bot.reply_to(message, "پاسخ به همان پیام")

و:

bot.send_message(message.chat.id, "ارسال پیام به همین گفتگو")

تفاوت ساده:

• reply_to پاسخ را به همان پیام کاربر وصل می‌کند.
• send_message فقط یک پیام جدید در همان گفتگو می‌فرستد.

برای شروع، reply_to ساده‌تر است. وقتی با chat.id آشنا شدید، send_message هم خیلی کاربردی می‌شود.

یک ربات کامل‌تر برای شروع

این نمونه چند دستور ابتدایی دارد:

import os
import telebot

TOKEN = os.getenv("BOT_TOKEN")

if not TOKEN:
    raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")

bot = telebot.TeleBot(TOKEN)


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "سلام! به ربات آموزشی خوش آمدی.")


@bot.message_handler(commands=["help"])
def help_message(message):
    text = "دستورهای ربات:\n/start شروع\n/help راهنما"
    bot.reply_to(message, text)


@bot.message_handler(content_types=["text"])
def answer_text(message):
    if message.text == "سلام":
        bot.reply_to(message, "سلام! خوش آمدی.")
    else:
        bot.reply_to(message, "پیام شما را گرفتم.")


bot.infinity_polling()

برای تبدیل همین نمونه به نسخهٔ بله، فقط کافی است apihelper را اضافه کنیم و آدرس API را قبل از ساختن bot تغییر بدهیم:

import os
import telebot
from telebot import apihelper

TOKEN = os.getenv("BOT_TOKEN")

if not TOKEN:
    raise RuntimeError("متغیر BOT_TOKEN تنظیم نشده است.")

apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}"

bot = telebot.TeleBot(TOKEN)

بقیهٔ handlerها معمولاً مثل قبل می‌مانند.

اقدامات ابتدایی برای هر ربات

برای شروع هر ربات، این کارها را انجام دهید:

1. هدف ربات را خیلی ساده مشخص کنید. مثلاً «پاسخ به سلام» یا «نمایش راهنما».
2. توکن ربات را بگیرید و آن را امن نگه دارید.
3. کتابخانهٔ pyTelegramBotAPI را نصب کنید.
4. یک فایل مثل bot.py بسازید.
5. شیء TeleBot را با توکن بسازید.
6. حداقل یک handler برای /start بنویسید.
7. یک handler برای /help اضافه کنید.
8. اگر لازم است به پیام‌های عادی هم پاسخ بدهید.
9. برنامه را با bot.infinity_polling() اجرا کنید.
10. ربات را در پیام‌رسان تست کنید.

خطاهای رایج

• نصب پکیج اشتباه به جای pyTelegramBotAPI
• فراموش کردن import telebot
• اشتباه نوشتن توکن
• گذاشتن توکن داخل مخزن عمومی
• اضافه نکردن apihelper.API_URL برای بله
• نوشتن apihelper.API_URL بعد از ساختن bot
• بستن ترمینال و انتظار پاسخ‌گویی ربات

تمرین‌های کوتاه

1. رباتی بسازید که با دستور /start پیام خوش‌آمد نمایش دهد.
2. دستور /help را اضافه کنید و دو دستور ربات را در آن توضیح دهید.
3. کاری کنید اگر کاربر کلمهٔ سلام را فرستاد، ربات جواب سلام، خوبی؟ بدهد.
4. نسخهٔ بلهٔ کد را با اضافه کردن apihelper.API_URL آماده کنید.
5. توضیح دهید چرا خط apihelper.API_URL باید قبل از telebot.TeleBot(TOKEN) نوشته شود.

جمع‌بندی

کتابخانهٔ telebot کار ساخت ربات را ساده می‌کند. با چند خط کد می‌توانیم دستورهای ساده مثل /start و /help را مدیریت کنیم و به پیام‌های متنی پاسخ بدهیم. برای تلگرام از تنظیمات پیش‌فرض کتابخانه استفاده می‌کنیم، اما برای بله باید آدرس API را با apihelper.API_URL = "https://tapi.bale.ai/bot{0}/{1}" تغییر بدهیم.

منابع برای مطالعهٔ بیشتر

• مستندات pyTelegramBotAPI
• صفحهٔ pyTelegramBotAPI در PyPI
• Telegram Bot API