khorasan-doc/docs/programming-languages-chapter2-2.md

# زیر‌فصل ۲-۲: دریافت و ارسال پیام در تلگرام و بله

در این زیر‌فصل با روش‌های عملی ارتباط برنامهٔ ربات با پیام‌رسان آشنا می‌شویم. دو روش اصلی برای دریافت پیام وجود دارد: `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)