From 31dc02855eab297747bf8fe764396124fdff9cde Mon Sep 17 00:00:00 2001
From: Nearology <hi@aminx.me>
Date: Wed, 6 May 2026 12:51:13 +0330
Subject: [PATCH] Add chapter three on telebot library and update navigation in
 mkdocs

---
 docs/.dates_cache.jsonl                |   1 +
 docs/programming-languages-chapter3.md | 327 +++++++++++++++++++++++++
 mkdocs.yml                             |   1 +
 3 files changed, 329 insertions(+)
 create mode 100644 docs/programming-languages-chapter3.md

diff --git a/docs/.dates_cache.jsonl b/docs/.dates_cache.jsonl
index c0a791c..db1730e 100644
--- a/docs/.dates_cache.jsonl
+++ b/docs/.dates_cache.jsonl
@@ -51,4 +51,5 @@
 {"programming-languages-chapter2-1.md": {"created": "2026-05-06T10:36:46.397576+03:30"}}
 {"programming-languages-chapter2-2.md": {"created": "2026-05-06T10:36:46.397576+03:30"}}
 {"programming-languages-chapter2.md": {"created": "2026-05-06T10:36:46.397576+03:30"}}
+{"programming-languages-chapter3.md": {"created": "2026-05-06T10:52:56.641622+03:30"}}
 {"programming-languages.md": {"created": "2026-04-28T13:17:04.811052+03:30"}}
diff --git a/docs/programming-languages-chapter3.md b/docs/programming-languages-chapter3.md
new file mode 100644
index 0000000..1962d72
--- /dev/null
+++ b/docs/programming-languages-chapter3.md
@@ -0,0 +1,327 @@
+# فصل سه: شروع کار با کتابخانهٔ 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)
diff --git a/mkdocs.yml b/mkdocs.yml
index e8bce5e..cd63df2 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -69,6 +69,7 @@ nav:
               - "معرفی فصل": programming-languages-chapter2.md
               - "زیر‌فصل ۲-۱: مفاهیم پایهٔ ربات‌ها و API": programming-languages-chapter2-1.md
               - "زیر‌فصل ۲-۲: دریافت و ارسال پیام در تلگرام و بله": programming-languages-chapter2-2.md
+          - "📚 فصل سه": programming-languages-chapter3.md
   - "شیوه ارزشیابی": grading.md
 
 theme: