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

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

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

## telebot چیست؟

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

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

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

## نصب کتابخانه

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

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

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

```bash
.venv\Scripts\activate
```

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

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

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

مراحل کلی:

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

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

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

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

```python
import telebot

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

bot = telebot.TeleBot(TOKEN)


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


bot.infinity_polling()
```

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

```bash
python bot.py
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

قبل از اجرا:

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

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

```python
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` را بررسی می‌کند:

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

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

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

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

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

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

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

## تفاوت reply_to و send_message

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

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

و:

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

تفاوت ساده:

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

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

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

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

```python
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` تغییر بدهیم:

```python
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](https://pytba.readthedocs.io/en/latest/)
- [صفحهٔ pyTelegramBotAPI در PyPI](https://pypi.org/project/pyTelegramBotAPI/)
- [Telegram Bot API](https://core.telegram.org/bots/api)