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

زیر‌فصل ۲-۱: مفاهیم پایهٔ ربات‌ها و API

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

ربات چیست؟

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

برای مثال:

• کاربر می‌نویسد: /start
• پیام‌رسان این پیام را به برنامهٔ ربات می‌رساند
• برنامه تشخیص می‌دهد که دستور شروع دریافت شده است
• برنامه پاسخ می‌دهد: سلام! خوش آمدی.

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

API چیست؟

API یعنی راه ارتباطی استاندارد بین دو نرم‌افزار. وقتی برنامهٔ ما می‌خواهد از تلگرام یا بله استفاده کند، مستقیم وارد نرم‌افزار موبایل نمی‌شود. به جای آن، درخواست HTTP به سرور پیام‌رسان می‌فرستد.

برای نمونه، در تلگرام آدرس درخواست‌ها معمولاً این شکل را دارد:

https://api.telegram.org/bot<TOKEN>/METHOD_NAME

در بله نیز ساختار رایج درخواست‌های Bot API به این شکل است:

https://tapi.bale.ai/bot<TOKEN>/METHOD_NAME

در این آدرس‌ها:

• TOKEN شناسهٔ محرمانهٔ ربات است.
• METHOD_NAME کاری است که می‌خواهیم انجام دهیم؛ مثل getUpdates یا sendMessage.

!!! warning "نکتهٔ امنیتی" توکن ربات مثل رمز عبور است. اگر کسی توکن را داشته باشد، می‌تواند از طرف ربات شما پیام بفرستد یا تنظیمات آن را تغییر دهد. هیچ‌وقت توکن را داخل مخزن عمومی، عکس، گزارش تمرین یا گروه کلاسی منتشر نکنید.

جریان کلی کار ربات

هر ربات معمولاً این چرخه را طی می‌کند:

1. کاربر در پیام‌رسان پیامی برای ربات می‌فرستد.
2. سرور پیام‌رسان پیام را به عنوان یک Update ثبت می‌کند.
3. برنامهٔ ما Update را دریافت می‌کند.
4. برنامه متن پیام، شناسهٔ کاربر و شناسهٔ گفتگو را می‌خواند.
5. برنامه تصمیم می‌گیرد چه پاسخی مناسب است.
6. برنامه با متدی مثل sendMessage پاسخ را به پیام‌رسان می‌فرستد.
7. پیام‌رسان پاسخ را به کاربر نمایش می‌دهد.

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 شبیه این است:

{
  "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 را با یک مثال توضیح دهید.