Add chapter on messaging bots, including API concepts and message handling
This commit is contained in:
@@ -48,4 +48,7 @@
|
||||
{"lesson9.md": {"created": "2025-12-18T15:34:58+03:30"}}
|
||||
{"linux-course.md": {"created": "2026-04-28T13:23:07.682468+03:30"}}
|
||||
{"linux-intro.md": {"created": "2026-04-28T15:51:08.382135+03:30"}}
|
||||
{"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.md": {"created": "2026-04-28T13:17:04.811052+03:30"}}
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
# زیرفصل ۲-۱: مفاهیم پایهٔ رباتها و API
|
||||
|
||||
در این زیرفصل یاد میگیریم ربات چیست، چرا برای ارتباط با پیامرسانها به API نیاز داریم، توکن چه نقشی دارد و پیامهای کاربران با چه ساختاری به برنامهٔ ربات میرسند.
|
||||
|
||||
## ربات چیست؟
|
||||
|
||||
ربات یک برنامه است که به جای انسان با کاربر گفتگو میکند. وقتی کاربر به ربات پیام میدهد، پیامرسان آن پیام را به شکل داده برای برنامهٔ ما میفرستد. برنامه پیام را بررسی میکند و اگر لازم باشد پاسخ میدهد.
|
||||
|
||||
برای مثال:
|
||||
|
||||
- کاربر مینویسد: `/start`
|
||||
- پیامرسان این پیام را به برنامهٔ ربات میرساند
|
||||
- برنامه تشخیص میدهد که دستور شروع دریافت شده است
|
||||
- برنامه پاسخ میدهد: `سلام! خوش آمدی.`
|
||||
|
||||
پس ربات جادو نمیکند؛ فقط یک برنامه است که ورودی میگیرد، پردازش میکند و خروجی میدهد.
|
||||
|
||||
## API چیست؟
|
||||
|
||||
API یعنی راه ارتباطی استاندارد بین دو نرمافزار. وقتی برنامهٔ ما میخواهد از تلگرام یا بله استفاده کند، مستقیم وارد نرمافزار موبایل نمیشود. به جای آن، درخواست HTTP به سرور پیامرسان میفرستد.
|
||||
|
||||
برای نمونه، در تلگرام آدرس درخواستها معمولاً این شکل را دارد:
|
||||
|
||||
```text
|
||||
https://api.telegram.org/bot<TOKEN>/METHOD_NAME
|
||||
```
|
||||
|
||||
در بله نیز ساختار رایج درخواستهای Bot API به این شکل است:
|
||||
|
||||
```text
|
||||
https://tapi.bale.ai/bot<TOKEN>/METHOD_NAME
|
||||
```
|
||||
|
||||
در این آدرسها:
|
||||
|
||||
- `TOKEN` شناسهٔ محرمانهٔ ربات است.
|
||||
- `METHOD_NAME` کاری است که میخواهیم انجام دهیم؛ مثل `getUpdates` یا `sendMessage`.
|
||||
|
||||
!!! warning "نکتهٔ امنیتی"
|
||||
توکن ربات مثل رمز عبور است. اگر کسی توکن را داشته باشد، میتواند از طرف ربات شما پیام بفرستد یا تنظیمات آن را تغییر دهد. هیچوقت توکن را داخل مخزن عمومی، عکس، گزارش تمرین یا گروه کلاسی منتشر نکنید.
|
||||
|
||||
## جریان کلی کار ربات
|
||||
|
||||
هر ربات معمولاً این چرخه را طی میکند:
|
||||
|
||||
1. کاربر در پیامرسان پیامی برای ربات میفرستد.
|
||||
2. سرور پیامرسان پیام را به عنوان یک `Update` ثبت میکند.
|
||||
3. برنامهٔ ما `Update` را دریافت میکند.
|
||||
4. برنامه متن پیام، شناسهٔ کاربر و شناسهٔ گفتگو را میخواند.
|
||||
5. برنامه تصمیم میگیرد چه پاسخی مناسب است.
|
||||
6. برنامه با متدی مثل `sendMessage` پاسخ را به پیامرسان میفرستد.
|
||||
7. پیامرسان پاسخ را به کاربر نمایش میدهد.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as کاربر
|
||||
participant M as پیامرسان
|
||||
participant B as برنامهٔ ربات
|
||||
|
||||
U->>M: ارسال پیام
|
||||
M->>M: ساخت Update
|
||||
B->>M: دریافت Update
|
||||
B->>B: بررسی پیام
|
||||
B->>M: ارسال پاسخ با API
|
||||
M->>U: نمایش پاسخ
|
||||
```
|
||||
|
||||
## Update چیست؟
|
||||
|
||||
هر اتفاق جدیدی که به ربات مربوط باشد، یک `Update` حساب میشود. سادهترین نمونهٔ آن پیام متنی کاربر است، اما Update میتواند چیزهای دیگری هم باشد؛ مثل کلیک روی دکمه، ویرایش پیام، ارسال عکس یا عضویت در گروه.
|
||||
|
||||
یک نمونهٔ ساده از Update شبیه این است:
|
||||
|
||||
```json
|
||||
{
|
||||
"update_id": 12345,
|
||||
"message": {
|
||||
"message_id": 10,
|
||||
"from": {
|
||||
"id": 987654321,
|
||||
"first_name": "Ali"
|
||||
},
|
||||
"chat": {
|
||||
"id": 987654321,
|
||||
"type": "private"
|
||||
},
|
||||
"text": "/start"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
چند بخش مهم:
|
||||
|
||||
- `update_id`: شمارهٔ یکتای این رویداد
|
||||
- `message.text`: متن پیام کاربر
|
||||
- `message.chat.id`: شناسهٔ گفتگو؛ برای پاسخ دادن به همین مقدار نیاز داریم
|
||||
- `message.from.id`: شناسهٔ کاربری که پیام را فرستاده است
|
||||
|
||||
## ربات از نگاه مفاهیم زبانهای برنامهنویسی
|
||||
|
||||
رباتها چند مفهوم مهم برنامهنویسی را در یک پروژهٔ کوچک کنار هم میآورند:
|
||||
|
||||
- ورودی و خروجی: پیام کاربر ورودی است و پاسخ ربات خروجی.
|
||||
- شرطها: برنامه بر اساس متن پیام تصمیم میگیرد.
|
||||
- حلقهها: در روش Polling، برنامه مرتباً پیامهای جدید را بررسی میکند.
|
||||
- تابعها: هر کار مثل ارسال پیام یا پردازش دستور میتواند در یک تابع جدا باشد.
|
||||
- دادهٔ ساختیافته: پیامها به شکل JSON دریافت میشوند.
|
||||
- برنامهنویسی رویدادمحور: برنامه به اتفاقهایی مثل پیام جدید یا کلیک روی دکمه واکنش نشان میدهد.
|
||||
|
||||
## تمرین کوتاه
|
||||
|
||||
1. با زبان خودتان توضیح دهید ربات چه تفاوتی با کاربر انسانی دارد.
|
||||
2. توضیح دهید چرا توکن ربات نباید در اختیار دیگران قرار بگیرد.
|
||||
3. تفاوت `chat.id` و `from.id` را با یک مثال توضیح دهید.
|
||||
@@ -0,0 +1,185 @@
|
||||
# زیرفصل ۲-۲: دریافت و ارسال پیام در تلگرام و بله
|
||||
|
||||
در این زیرفصل با روشهای عملی ارتباط برنامهٔ ربات با پیامرسان آشنا میشویم. دو روش اصلی برای دریافت پیام وجود دارد: `getUpdates` و Webhook. برای پاسخ دادن هم معمولاً از متدی مثل `sendMessage` استفاده میکنیم.
|
||||
|
||||
## روش اول: دریافت پیام با getUpdates
|
||||
|
||||
در روش `getUpdates`، برنامهٔ ربات هر چند ثانیه یک بار از پیامرسان میپرسد: «پیام جدیدی برای من آمده؟»
|
||||
|
||||
در تلگرام:
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<TOKEN>/getUpdates"
|
||||
```
|
||||
|
||||
در بله:
|
||||
|
||||
```bash
|
||||
curl "https://tapi.bale.ai/bot<TOKEN>/getUpdates"
|
||||
```
|
||||
|
||||
این روش را Polling میگویند. اگر برنامه این پرسوجو را با فاصلهٔ مناسب تکرار کند، به آن Long Polling هم میگویند.
|
||||
|
||||
### مزیتهای getUpdates
|
||||
|
||||
- برای شروع یادگیری سادهتر است.
|
||||
- برای تمرینهای دانشجویی و اجرای محلی مناسب است.
|
||||
- به دامنه و HTTPS نیاز ندارد.
|
||||
- میتوان خروجی JSON را راحت دید و بررسی کرد.
|
||||
|
||||
### محدودیتهای getUpdates
|
||||
|
||||
- برنامه باید مرتباً درخواست بفرستد.
|
||||
- برای پروژههای بزرگ و پرترافیک انتخاب ایدهآل نیست.
|
||||
- اگر چند نسخه از برنامه همزمان `getUpdates` بزنند، مدیریت پیامها سخت میشود.
|
||||
|
||||
## روش دوم: دریافت پیام با Webhook
|
||||
|
||||
در روش Webhook، برنامه دیگر مرتباً سؤال نمیپرسد. به جای آن، ما یک آدرس اینترنتی HTTPS به پیامرسان معرفی میکنیم. هر وقت پیام جدیدی برسد، خود پیامرسان به آدرس برنامهٔ ما درخواست میفرستد.
|
||||
|
||||
نمونهٔ سادهٔ تنظیم Webhook در تلگرام:
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://example.com/my-bot"
|
||||
```
|
||||
|
||||
نمونهٔ سادهٔ تنظیم Webhook در بله:
|
||||
|
||||
```bash
|
||||
curl "https://tapi.bale.ai/bot<TOKEN>/setWebhook?url=https://example.com/my-bot"
|
||||
```
|
||||
|
||||
در این حالت برنامهٔ ما باید یک مسیر وب داشته باشد که درخواستهای پیامرسان را دریافت کند.
|
||||
|
||||
### مزیتهای Webhook
|
||||
|
||||
- سریعتر و مناسبتر برای سرویسهای واقعی است.
|
||||
- درخواست اضافهٔ بیدلیل کمتر تولید میشود.
|
||||
- برای استقرار روی سرور، VPS یا سرویسهای ابری مناسبتر است.
|
||||
|
||||
### محدودیتهای Webhook
|
||||
|
||||
- به آدرس عمومی HTTPS نیاز دارد.
|
||||
- راهاندازی اولیهاش از `getUpdates` سختتر است.
|
||||
- اگر سرور برنامه قطع باشد، دریافت پیامها دچار مشکل میشود.
|
||||
|
||||
## sendMessage چگونه کار میکند؟
|
||||
|
||||
برای پاسخ دادن به کاربر، ربات معمولاً از متدی مثل `sendMessage` استفاده میکند. مهمترین چیزهایی که باید بفرستیم:
|
||||
|
||||
- `chat_id`: شناسهٔ گفتگویی که پیام باید در آن ارسال شود
|
||||
- `text`: متن پیام
|
||||
|
||||
نمونهٔ تلگرام:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
|
||||
-d "chat_id=<CHAT_ID>" \
|
||||
-d "text=سلام! پیام شما دریافت شد."
|
||||
```
|
||||
|
||||
نمونهٔ بله:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://tapi.bale.ai/bot<TOKEN>/sendMessage" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"chat_id": "<CHAT_ID>", "text": "سلام! پیام شما دریافت شد."}'
|
||||
```
|
||||
|
||||
مقدار `CHAT_ID` معمولاً از همان Update دریافت میشود. یعنی اول پیام کاربر را میگیریم، سپس از داخل آن `chat.id` را میخوانیم و جواب را به همان گفتگو میفرستیم.
|
||||
|
||||
## منطق سادهٔ یک ربات
|
||||
|
||||
در زبانهای برنامهنویسی مختلف، ظاهر کد فرق میکند، اما منطق اصلی تقریباً همین است:
|
||||
|
||||
```text
|
||||
پیامهای جدید را بگیر
|
||||
برای هر پیام:
|
||||
متن پیام را بخوان
|
||||
شناسهٔ گفتگو را بخوان
|
||||
اگر متن برابر /start بود:
|
||||
پیام خوشآمد بفرست
|
||||
وگرنه اگر متن برابر /help بود:
|
||||
راهنما بفرست
|
||||
وگرنه:
|
||||
بگو دستور را نمیشناسم
|
||||
```
|
||||
|
||||
همین منطق را میتوان با Python، JavaScript، Java، C# یا هر زبان دیگری پیادهسازی کرد. تفاوت زبانها بیشتر در کتابخانهها و شکل نوشتن کد است، نه در ایدهٔ اصلی.
|
||||
|
||||
## نمونهٔ آموزشی با Python
|
||||
|
||||
این نمونه فقط برای فهمیدن منطق است. در پروژهٔ واقعی بهتر است توکن را از متغیر محیطی بخوانیم، نه اینکه مستقیم داخل کد بنویسیم.
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
TOKEN = "TOKEN را اینجا نگذارید؛ فقط برای نمایش ساختار است"
|
||||
BASE_URL = f"https://api.telegram.org/bot{TOKEN}"
|
||||
|
||||
|
||||
def send_message(chat_id, text):
|
||||
url = f"{BASE_URL}/sendMessage"
|
||||
data = {
|
||||
"chat_id": chat_id,
|
||||
"text": text,
|
||||
}
|
||||
requests.post(url, data=data, timeout=10)
|
||||
|
||||
|
||||
def handle_update(update):
|
||||
message = update.get("message", {})
|
||||
text = message.get("text", "")
|
||||
chat = message.get("chat", {})
|
||||
chat_id = chat.get("id")
|
||||
|
||||
if not chat_id:
|
||||
return
|
||||
|
||||
if text == "/start":
|
||||
send_message(chat_id, "سلام! به ربات خوش آمدی.")
|
||||
elif text == "/help":
|
||||
send_message(chat_id, "دستورهای فعلی: /start و /help")
|
||||
else:
|
||||
send_message(chat_id, "این دستور را نمیشناسم.")
|
||||
```
|
||||
|
||||
این کد هنوز بخش دریافت پیامها را کامل نکرده است، اما بخش پردازش پیام و پاسخ دادن را نشان میدهد. هدف این است که بفهمیم ربات در نهایت یک برنامهٔ شرطی و رویدادمحور است.
|
||||
|
||||
## شباهت تلگرام و بله
|
||||
|
||||
تلگرام و بله از نظر ایدهٔ کلی شبیه هم هستند:
|
||||
|
||||
| موضوع | تلگرام | بله |
|
||||
|---|---|---|
|
||||
| ارتباط با ربات | از طریق Bot API | از طریق Bot API بله |
|
||||
| شناسهٔ محرمانه | Token | Token |
|
||||
| دریافت پیام | `getUpdates` یا `Webhook` | `getUpdates` یا `Webhook` |
|
||||
| ارسال پیام | `sendMessage` | `sendMessage` |
|
||||
| قالب داده | JSON | JSON |
|
||||
| نیاز برنامهنویسی | دارد | دارد |
|
||||
|
||||
## تفاوتهای مهم
|
||||
|
||||
- آدرس پایهٔ API متفاوت است.
|
||||
- کتابخانههای آمادهٔ هر پلتفرم ممکن است متفاوت باشند.
|
||||
- بعضی قابلیتها، محدودیتها یا نوع دکمهها ممکن است دقیقاً یکسان نباشند.
|
||||
- مستندات و نسخههای API ممکن است در طول زمان تغییر کنند.
|
||||
|
||||
پس اگر منطق کلی را یاد بگیرید، جابهجایی بین پیامرسانها خیلی سخت نیست. کافی است آدرس API، نام متدها، ساختار داده و کتابخانهٔ مناسب همان پلتفرم را بررسی کنید.
|
||||
|
||||
## تمرینهای کوتاه
|
||||
|
||||
1. بگویید در چه شرایطی `getUpdates` بهتر است و در چه شرایطی Webhook.
|
||||
2. یک شبهکد بنویسید که اگر کاربر `/time` فرستاد، ربات پیام `زمان فعلی را بعداً اضافه میکنیم` را پاسخ دهد.
|
||||
3. یک جدول کوچک بسازید و سه متد رایج رباتها را همراه با کاربردشان بنویسید.
|
||||
|
||||
## جمعبندی
|
||||
|
||||
ربات تلگرام یا بله یک برنامهٔ مستقل است که با API پیامرسان حرف میزند. پیامرسان پیامهای کاربران را به شکل Update در اختیار برنامه میگذارد و برنامه با متدهایی مثل `sendMessage` پاسخ میدهد. دو راه اصلی دریافت پیام، `getUpdates` و Webhook هستند. اگر این چرخه را بفهمیم، میتوانیم با هر زبان برنامهنویسی یک ربات ساده بسازیم.
|
||||
|
||||
## منابع برای مطالعهٔ بیشتر
|
||||
|
||||
- [Telegram Bot API](https://core.telegram.org/bots/api)
|
||||
- [مستندات بازوی بله](https://docs.bale.ai/)
|
||||
- [صفحهٔ توسعهدهندگان بله](https://bale.ai/dev)
|
||||
@@ -0,0 +1,34 @@
|
||||
# فصل دو: رباتهای پیامرسان
|
||||
|
||||
در این فصل با نحوهٔ کار رباتهای تلگرام و بله آشنا میشویم. ربات در ظاهر شبیه یک کاربر معمولی است، اما پشت آن یک برنامه قرار دارد که پیامها را دریافت میکند، آنها را پردازش میکند و از طریق API پاسخ میدهد.
|
||||
|
||||
این فصل به دو زیرفصل تقسیم شده است:
|
||||
|
||||
## زیرفصلها
|
||||
|
||||
- [زیرفصل ۲-۱: مفاهیم پایهٔ رباتها و API](programming-languages-chapter2-1.md)
|
||||
- [زیرفصل ۲-۲: دریافت و ارسال پیام در تلگرام و بله](programming-languages-chapter2-2.md)
|
||||
|
||||
## اهداف فصل
|
||||
|
||||
- آشنایی با مفهوم Bot و تفاوت آن با کاربر انسانی
|
||||
- شناخت نقش API در ارتباط بین برنامه و پیامرسان
|
||||
- آشنایی با Token و دلیل محرمانه بودن آن
|
||||
- شناخت دو روش اصلی دریافت پیام: `getUpdates` و `Webhook`
|
||||
- درک ساختار کلی پیامها در قالب JSON
|
||||
- مقایسهٔ کلی رباتهای تلگرام و بله
|
||||
- نوشتن نمونهٔ ساده از منطق یک ربات
|
||||
|
||||
## پیشنیازهای پیشنهادی
|
||||
|
||||
برای فهم بهتر این فصل، بهتر است دانشجو با مفهومهای زیر آشنایی مقدماتی داشته باشد:
|
||||
|
||||
- متغیر و مقدار
|
||||
- شرطها
|
||||
- تابعها
|
||||
- درخواست اینترنتی یا HTTP
|
||||
- دادهٔ ساختیافته مثل JSON
|
||||
|
||||
## جمعبندی کوتاه
|
||||
|
||||
ربات تلگرام یا بله یک برنامهٔ مستقل است که با سرور پیامرسان ارتباط برقرار میکند. پیامرسان پیامهای کاربران را به شکل داده در اختیار برنامه میگذارد و برنامه با توجه به منطق خودش پاسخ مناسب را ارسال میکند.
|
||||
@@ -65,6 +65,10 @@ nav:
|
||||
- "تمرین ۱۰: ادغامگرِ گزارشها": exercise10.md
|
||||
- "زبانهای برنامهنویسی":
|
||||
- "معرفی درس": programming-languages.md
|
||||
- "📚 فصل دو ":
|
||||
- "معرفی فصل": programming-languages-chapter2.md
|
||||
- "زیرفصل ۲-۱: مفاهیم پایهٔ رباتها و API": programming-languages-chapter2-1.md
|
||||
- "زیرفصل ۲-۲: دریافت و ارسال پیام در تلگرام و بله": programming-languages-chapter2-2.md
|
||||
- "شیوه ارزشیابی": grading.md
|
||||
|
||||
theme:
|
||||
|
||||
Reference in New Issue
Block a user