Files

T

nearology bfa68b829c Add chapter on messaging bots, including API concepts and message handling

2026-05-06 10:46:13 +03:30

8.8 KiB

Raw Blame History

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

در این زیر‌فصل با روش‌های عملی ارتباط برنامهٔ ربات با پیام‌رسان آشنا می‌شویم. دو روش اصلی برای دریافت پیام وجود دارد: getUpdates و Webhook. برای پاسخ دادن هم معمولاً از متدی مثل sendMessage استفاده می‌کنیم.

روش اول: دریافت پیام با getUpdates

در روش getUpdates، برنامهٔ ربات هر چند ثانیه یک بار از پیام‌رسان می‌پرسد: «پیام جدیدی برای من آمده؟»

در تلگرام:

curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

در بله:

curl "https://tapi.bale.ai/bot<TOKEN>/getUpdates"

این روش را Polling می‌گویند. اگر برنامه این پرس‌وجو را با فاصلهٔ مناسب تکرار کند، به آن Long Polling هم می‌گویند.

مزیت‌های getUpdates

برای شروع یادگیری ساده‌تر است.
برای تمرین‌های دانشجویی و اجرای محلی مناسب است.
به دامنه و HTTPS نیاز ندارد.
می‌توان خروجی JSON را راحت دید و بررسی کرد.

محدودیت‌های getUpdates

برنامه باید مرتباً درخواست بفرستد.
برای پروژه‌های بزرگ و پرترافیک انتخاب ایده‌آل نیست.
اگر چند نسخه از برنامه هم‌زمان getUpdates بزنند، مدیریت پیام‌ها سخت می‌شود.

روش دوم: دریافت پیام با Webhook

در روش Webhook، برنامه دیگر مرتباً سؤال نمی‌پرسد. به جای آن، ما یک آدرس اینترنتی HTTPS به پیام‌رسان معرفی می‌کنیم. هر وقت پیام جدیدی برسد، خود پیام‌رسان به آدرس برنامهٔ ما درخواست می‌فرستد.

نمونهٔ سادهٔ تنظیم Webhook در تلگرام:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://example.com/my-bot"

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

curl "https://tapi.bale.ai/bot<TOKEN>/setWebhook?url=https://example.com/my-bot"

در این حالت برنامهٔ ما باید یک مسیر وب داشته باشد که درخواست‌های پیام‌رسان را دریافت کند.

مزیت‌های Webhook

سریع‌تر و مناسب‌تر برای سرویس‌های واقعی است.
درخواست اضافهٔ بی‌دلیل کمتر تولید می‌شود.
برای استقرار روی سرور، VPS یا سرویس‌های ابری مناسب‌تر است.

محدودیت‌های Webhook

به آدرس عمومی HTTPS نیاز دارد.
راه‌اندازی اولیه‌اش از getUpdates سخت‌تر است.
اگر سرور برنامه قطع باشد، دریافت پیام‌ها دچار مشکل می‌شود.

sendMessage چگونه کار می‌کند؟

برای پاسخ دادن به کاربر، ربات معمولاً از متدی مثل sendMessage استفاده می‌کند. مهم‌ترین چیزهایی که باید بفرستیم:

chat_id: شناسهٔ گفتگویی که پیام باید در آن ارسال شود
text: متن پیام

نمونهٔ تلگرام:

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d "chat_id=<CHAT_ID>" \
  -d "text=سلام! پیام شما دریافت شد."

نمونهٔ بله:

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 را می‌خوانیم و جواب را به همان گفتگو می‌فرستیم.

منطق سادهٔ یک ربات

در زبان‌های برنامه‌نویسی مختلف، ظاهر کد فرق می‌کند، اما منطق اصلی تقریباً همین است:

پیام‌های جدید را بگیر
برای هر پیام:
    متن پیام را بخوان
    شناسهٔ گفتگو را بخوان
    اگر متن برابر /start بود:
        پیام خوش‌آمد بفرست
    وگرنه اگر متن برابر /help بود:
        راهنما بفرست
    وگرنه:
        بگو دستور را نمی‌شناسم

همین منطق را می‌توان با Python، JavaScript، Java، C# یا هر زبان دیگری پیاده‌سازی کرد. تفاوت زبان‌ها بیشتر در کتابخانه‌ها و شکل نوشتن کد است، نه در ایدهٔ اصلی.

نمونهٔ آموزشی با 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، نام متدها، ساختار داده و کتابخانهٔ مناسب همان پلتفرم را بررسی کنید.

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

بگویید در چه شرایطی getUpdates بهتر است و در چه شرایطی Webhook.
یک شبه‌کد بنویسید که اگر کاربر /time فرستاد، ربات پیام زمان فعلی را بعداً اضافه می‌کنیم را پاسخ دهد.
یک جدول کوچک بسازید و سه متد رایج ربات‌ها را همراه با کاربردشان بنویسید.

جمع‌بندی

ربات تلگرام یا بله یک برنامهٔ مستقل است که با API پیام‌رسان حرف می‌زند. پیام‌رسان پیام‌های کاربران را به شکل Update در اختیار برنامه می‌گذارد و برنامه با متدهایی مثل sendMessage پاسخ می‌دهد. دو راه اصلی دریافت پیام، getUpdates و Webhook هستند. اگر این چرخه را بفهمیم، می‌توانیم با هر زبان برنامه‌نویسی یک ربات ساده بسازیم.

8.8 KiB Raw Blame History