Messaging Channels: Telegram and Bale Bots

Build a channel-agnostic bot that processes each update once, keeps its token safe, respects platform limits and treats user text as data.

بعد از این درس می‌توانی

  • بین دریافت به‌روزرسانی با Polling و Webhook برای یک ربات انتخاب کند و شرط‌های هرکدام (HTTPS، درگاه، نگهداری ۲۴ ساعته) را بگوید.
  • با شناسه به‌روزرسانی و offset، هر پیام را دقیقاً یک بار پردازش کند.
  • ربات را طوری طراحی کند که تعویض پلتفرم (مثلاً بله و تلگرام) فقط با پیکربندی انجام شود.
  • توکن، داده کاربر و متن ورودی را با قواعد امنیت و حریم خصوصی مدیریت کند.

چرا این درس مهم است

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

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

مفاهیم کلیدی

یادآوری: Webhook، Polling، تحویل تکراری و کلید API را در دوره AUT-201 دیدی؛ اینجا همان‌ها را روی ربات پیام‌رسان به کار می‌بری.

  • Bot Token (توکن ربات): کلیدی که پلتفرم هنگام ساخت ربات می‌دهد و هر کس آن را داشته باشد، به جای ربات عمل می‌کند.
  • Update (به‌روزرسانی): هر رویدادی که پلتفرم برای ربات می‌فرستد، مثل پیام تازه، با یک شناسه عددی.
  • Long Polling (پرسیدن طولانی): درخواستی که سرور تا رسیدن به‌روزرسانی تازه یا پایان مهلت باز نگه می‌دارد.
  • Offset (نقطه شروع): شناسه‌ای که به پلتفرم می‌گوید به‌روزرسانی‌های قبل از آن را دیگر نفرستد.
  • Channel-agnostic Design (طراحی مستقل از کانال): جدا کردن منطق ربات از جزئیات پلتفرم تا تعویض کانال فقط با پیکربندی باشد.

مدل ذهنی

ربات را مثل صندوق پستی با شماره‌گذاری نامه‌ها ببین. هر نامه شماره دارد. تو آخرین شماره‌ای را که خوانده‌ای یادداشت می‌کنی و هر بار از اداره پست می‌خواهی «از شماره بعد به من بده». اگر وسط خواندن خوابت برد، فردا از همان شماره ادامه می‌دهی؛ نه نامه‌ای جا می‌افتد، نه دو بار جواب می‌دهی.

پردازش یک‌باره به‌روزرسانی‌ها با offset: ربات آخرین offset ذخیره‌شده را می‌خواند و getUpdates را با آن صدا می‌زند؛ برای هر به‌روزرسانی، پیام بدون متن رد می‌شود و پیام متنی پاسخ می‌گیرد؛ پس از پردازش هر به‌روزرسانی offset برابر شناسه به‌علاوه یک ذخیره می‌شود؛ دور بعد فقط به‌روزرسانی‌های تازه می‌آیند.

پردازش یک‌باره به‌روزرسانی‌ها با offset

این تشبیه کجا غلط است؟ اداره پست نامه‌ها را تا ابد نگه نمی‌دارد. تلگرام به‌روزرسانی‌های دریافت‌نشده را بیش از ۲۴ ساعت نگه نمی‌داردsrc-telegram-bot-api، و طبق مستندات بله، ۲۰۰۰ پیام آخر فقط ۲۴ ساعت نگهداری می‌شوندsrc-bale-bot-docs. رباتی که بیش از یک روز خاموش بماند، پیام‌ها را برای همیشه از دست می‌دهد؛ پس پایش «ربات زنده است؟» لازم است.

گام‌به‌گام

گام ۱: شکل مشترک API ربات

API تلگرام درخواست‌ها را به‌شکل https://api.telegram.org/bot<token>/METHOD و فقط با HTTPS می‌پذیردsrc-telegram-bot-api. مستندات بازوی بله همین شکل را با نشانی https://tapi.bale.ai/bot<token>/METHOD_NAME دارد و بازو با «بازوی پدر» (@botfather) در خود بله ساخته می‌شودsrc-bale-bot-docs. نام متدها (مثل getUpdates، setWebhook، sendMessage) و شکل پیام در مستندات بله بسیار شبیه تلگرام است؛ این شباهت از مقایسه دو مستندات است، نه ادعای خود بله. پس اگر نشانی پایه و توکن را پیکربندی کنی، بیشتر منطق ربات مشترک می‌ماند؛ ولی هر تفاوت (محدودیت فایل، امکانات Webhook) را از مستندات همان پلتفرم بخوان.

گام ۲: Polling یا Webhook

در تلگرام این دو روش «دو راه ناسازگار» برای دریافت به‌روزرسانی‌اند: تا Webhook تنظیم است، getUpdates کار نمی‌کندsrc-telegram-bot-api.

Polling (getUpdates)Webhook (setWebhook)
نیازفقط دسترسی بیرونی به APIنشانی عمومی HTTPS؛ تلگرام: درگاه 443، 80، 88 یا 8443src-telegram-bot-api؛ بله: 443 یا 88src-bale-bot-docs
مناسبتمرین، کامپیوتر بدون نشانی عمومی، حجم کمتولید روی سرور با دامنه و TLS
اعتبارسنجی فرستندهپاسخ از خود API می‌آیدتلگرام: secret_token در هدر X-Telegram-Bot-Api-Secret-Tokensrc-telegram-bot-api؛ برای بله در مستنداتی که خواندیم معادلش ندیدیم

برای Webhook همه قاعده‌های درس پنجم دوره AUT-201 برقرار است: بررسی فرستنده، تحویل تکراری، پاسخ سریع. اگر پلتفرم سازوکار امضا یا رمز ندارد، نشانی Webhook را طولانی و تصادفی بگیر، و برای هر اقدام مهم، داده را از API خود پلتفرم یا سامانه‌ات دوباره بخوان.

گام ۳: هر به‌روزرسانی، یک بار

هر به‌روزرسانی شناسه دارد؛ تلگرام می‌گوید با آن می‌توانی به‌روزرسانی‌های تکراری را نادیده بگیری و ترتیب را بازسازی کنیsrc-telegram-bot-api. در Polling:

  • offset را پس از پردازش ذخیره کن، نه پیش از آن. اگر ربات وسط کار بیفتد، آن به‌روزرسانی دوباره می‌آید (بهتر از اینکه جا بیفتد)؛ پس پاسخ‌دادن را هم ایدمپوتنت کن (ثبت شناسه‌های پاسخ‌داده‌شده).
  • offset را جایی ماندگار نگه دار (فایل یا جدول)، نه در حافظه؛ داستان آغاز درس همین بود.
  • در Webhook، شناسه به‌روزرسانی را مثل شناسه رویداد درس Webhook ثبت کن.

گام ۴: محدودیت‌های پلتفرم

  • طول پیام متنی: در بله حداکثر ۴۰۹۶ نویسهsrc-bale-bot-docs؛ ربات نمونه پاسخ را در ۴۰۰۰ نویسه می‌بُرد. پاسخ بلند مدل را خلاصه یا تکه کن، نه اینکه بی‌صدا شکست بخورد.
  • فایل‌ها: بله برای تصویر و فایل‌های دیگر سقف حجم جدا دارد و پیوند دانلود فایل یک ساعت معتبر استsrc-bale-bot-docs. پیام‌های بدون متن (عکس، صدا) را صریحاً مدیریت کن: نادیده بگیر و بگو، یا به مسیر جدا بفرست.
  • سقف نرخ ارسال پلتفرم‌ها را رعایت کن (دسته‌بندی و تلاش دوباره درس‌های قبل).

گام ۵: توکن، داده و متن

  • توکن را مثل هر کلید دیگر فقط در Credential یا متغیر محیطی نگه دار؛ نشتش یعنی هر کسی می‌تواند به جای ربات به مشتریانت پیام بدهد. اگر نشت کرد، از بازوی پدر توکن تازه بگیر.
  • داده کاربر: شناسه چت و متن پیام داده شخصی‌اند. فقط چیزی را ذخیره کن که لازم است، با مدت نگهداری؛ در لاگ فقط شناسه به‌روزرسانی و نتیجه.
  • متن کاربر داده است، نه دستور. به‌روزرسانی 5004 در API آزمایشی می‌گوید «دستورهای قبلی را نادیده بگیر…». ربات نمونه فقط دنبال الگوی شماره سفارش می‌گردد و هیچ بخشی از متن را اجرا نمی‌کند؛ اگر مدل اضافه می‌کنی، مرزبندی تزریق پرامپت دوره FND-103 لازم است.

مثال‌ها

پیاده‌سازی عملی

ربات مستقل از پلتفرم. حدود ۲۲ دقیقه.

بدون اجرا / شبیه‌ساز
  1. API آزمایشی (shared/barg-sabz-mock-api.py) را اجرا کن؛ نقطه‌های /bot<token>/getUpdates و /bot<token>/sendMessage شبیه API پیام‌رسان‌ها رفتار می‌کنند و GET /sent-messages پیام‌های فرستاده‌شده را نشان می‌دهد.
  2. assets/poll_bot.py را با --once اجرا کن؛ سپس دوباره اجرا کن و نشان بده هیچ پیامی دوباره پردازش نشد.
  3. فایل offset را پاک کن و دوباره اجرا کن: چه می‌شود؟ این همان داستان آغاز درس است.
  4. در کد، ذخیره offset را به پیش از پاسخ منتقل کن و بنویس اگر ربات بین دو خط بیفتد، چه چیزی از دست می‌رود.
  5. بدون اجرا: assets/sample-run.txt را بخوان و همین پرسش‌ها را جواب بده.
سرویس میزبانی‌شده (در دسترس قانونی)

در پیام‌رسانی که از نظر قانونی برایت در دسترس است (مثلاً بله)، بازوی آزمایشی بساز. توکن را فقط در متغیر محیطی BOT_TOKEN بگذار و BOT_API_BASE را نشانی پایه همان پلتفرم کن؛ همان poll_bot.py بدون تغییر کد کار می‌کند. پاسخ وضعیت سفارش به API آزمایشی محلی نیاز دارد؛ اگر در دسترس نیست، پاسخ قطعی ساده بماند. فقط با حساب خودت یا حساب‌های آزمایشی پیام بده.

بدون کد

همین ربات را در n8n با Schedule Trigger (مثلاً هر ۳۰ ثانیه) + HTTP Request به getUpdates + Split Out روی result + If (متن دارد؟) + HTTP Request به sendMessage بساز. offset را در یک جدول یا فایل ذخیره کن و در درخواست بعدی بخوان. بنویس اگر دو اجرای زمان‌بندی‌شده هم‌پوشانی داشته باشند، چه خطری هست.

با کد

reply_for را طوری تغییر بده که پیام را با گام طبقه‌بندی درس اول (مدل آزمایشی یا محلی) دسته‌بندی کند و فقط برای order_shipping وضعیت سفارش بخواند. خروجی مدل را با بررسی enum اعتبارسنجی کن.

اشتباه‌های رایج

اشتباهنتیجهکار درست
offset در حافظهپس از راه‌اندازی دوباره، پاسخ تکراری به همهoffset ماندگار
ذخیره offset پیش از پردازشپیام بی‌پاسخ در خرابیپس از پردازش + پاسخ ایدمپوتنت
توکن در کد یا تصویر صفحهجعل پیام از طرف رباتCredential یا متغیر محیطی؛ تعویض پس از نشت
نام متد و نشانی پایه پخش در کدتعویض پلتفرم سختپیکربندی یک‌جا
نادیده‌گرفتن پیام بدون متنخطا یا سکوت گیج‌کنندهمسیر صریح
پاسخ بلند بدون سقفارسال شکست می‌خوردسقف و خلاصه یا تکه
ربات خاموش بیش از یک روزپیام‌ها برای همیشه از دست می‌روندپایش و هشدار زنده‌بودن

اشکال‌زدایی

پس از هر راه‌اندازی دوباره، ربات به پیام‌های قدیمی دوباره جواب می‌دهد.

offset ذخیره نمی‌شود یا در جای موقت است.

فایل یا جدول offset را پیش و پس از اجرا ببین.

offset ماندگار پس از پردازش هر به‌روزرسانی.

همه درخواست‌ها به API پیام‌رسان با 401 یا 404 برمی‌گردند.

توکن نامعتبر یا باطل شده، یا نشانی پایه پلتفرم دیگری است.

نشانی پایه را با مستندات پلتفرم و توکن را با بازوی پدر بررسی کن (بدون چاپ توکن).

توکن درست در محیط؛ ربات نمونه در این حالت متوقف می‌شود، نه اینکه بی‌پایان تلاش کند.

پس از تنظیم Webhook، Polling دیگر به‌روزرسانی نمی‌گیرد.

در تلگرام دو روش ناسازگارند؛ تا Webhook تنظیم است، getUpdates کار نمی‌کند.

وضعیت Webhook را با متد اطلاعات Webhook همان پلتفرم ببین.

یکی را انتخاب کن؛ برای برگشت به Polling، Webhook را حذف کن.

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

تمرین کوتاه

تمرین · 10 دقیقه

هدف: انتخاب روش دریافت.

گام‌ها: برای هر موقعیت Polling یا Webhook را با دلیل انتخاب کن.

  1. ربات آزمایشی روی لپ‌تاپ برای کلاس.
  2. ربات پشتیبانی روی سرور با دامنه و گواهی TLS، با صدها پیام در روز.
  3. n8n محلی بدون نشانی عمومی.
  4. رباتی که باید تشخیص بدهد درخواست از خود پلتفرم آمده، روی پلتفرمی که secret token ندارد.

معیار پذیرش: ۱ و ۳ Polling؛ ۲ Webhook با بررسی فرستنده؛ ۴ Polling یا Webhook با نشانی تصادفی و دوباره‌خوانی داده مهم از API.

راه‌حل نمونه

۱: Polling؛ نشانی عمومی لازم ندارد. ۲: Webhook با HTTPS روی درگاه مجاز، secret_token اگر پلتفرم دارد، ثبت شناسه به‌روزرسانی و پاسخ سریع. ۳: Polling با Schedule Trigger؛ Webhook به نشانی عمومی نیاز دارد. ۴: Polling ساده‌ترین است چون پاسخ از خود API می‌آید؛ اگر Webhook لازم است، نشانی طولانی و تصادفی و برای اقدام مهم، دوباره‌خوانی از API.

چالش

تمرین · 30 دقیقه

موقعیت: برای یک کاربرد پیام‌رسانی در کار خودت (اطلاع‌رسانی، پاسخ به پرسش رایج، ثبت درخواست)، ربات مستقل از پلتفرم طراحی و نمونه‌سازی کن. با API آزمایشی یا حساب آزمایشی در پلتفرمی که از نظر قانونی در دسترس است کار کن؛ داده‌ها ساختگی باشند.

  1. پیکربندی: نشانی پایه، توکن (فقط در محیط)، روش دریافت با دلیل.
  2. جدول پیام‌ها: هر نوع پیام ورودی (متن، عکس، دستور شروع) و رفتار ربات.
  3. سازوکار یک‌بار پردازش و آزمون آن (اجرای دوباره، پاک‌کردن offset).
  4. سیاست داده: چه چیزی ذخیره می‌شود، تا کی، و چه چیزی در لاگ نمی‌آید.

خروجی مورد انتظار: پیکربندی، جدول پیام‌ها، نتیجه آزمون یک‌بار پردازش و سیاست داده یک‌صفحه‌ای.

معیار پذیرش:

  • تعویض پلتفرم فقط با پیکربندی ممکن است.
  • هیچ پیامی دوباره پاسخ نمی‌گیرد و هیچ پیامی جا نمی‌افتد (آزموده).
  • توکن در کد و لاگ نیست.
  • پلتفرم انتخابی از نظر قانونی در دسترس است و داده‌ها ساختگی یا ناشناس‌اند.

پرسش‌های سنجش

جمع‌بندی

  • API ربات‌های تلگرام و بله شکل نزدیکی دارند؛ نشانی پایه و توکن را پیکربندی کن و تفاوت‌ها را از مستندات هر پلتفرم بخوان.
  • Polling برای تمرین و بدون نشانی عمومی؛ Webhook برای تولید با HTTPS و بررسی فرستنده.
  • offset را ماندگار و پس از پردازش ذخیره کن؛ هر به‌روزرسانی یک بار.
  • محدودیت طول، فایل و نرخ پلتفرم را رعایت کن؛ پیام بدون متن مسیر صریح دارد.
  • توکن راز است؛ متن کاربر داده است، نه دستور؛ شناسه چت هویت تأییدشده نیست.
  • ربات خاموش بیش از یک روز یعنی پیام‌های از دست‌رفته؛ زنده‌بودنش را پایش کن.

پرسش‌های سنجش

برگ سبز ربات بله‌اش را روی n8n داخل سازمان اجرا می‌کند که نشانی عمومی ندارد. همکارت می‌خواهد برای «فوری بودن پاسخ» Webhook راه بیندازد. موازنه Polling و Webhook را برای این موقعیت بنویس و پیشنهادت را بده.

پاسخ نمونه و معیار ارزیابی

Webhook پاسخ فوری‌تر و درخواست کمتر دارد، ولی نشانی عمومی HTTPS روی درگاه مجاز (در بله 443 یا 88) لازم است؛ یعنی باز کردن n8n یا یک گیرنده به اینترنت با امنیت تولید، و چون در مستندات بله سازوکار secret token دیده نشد، اعتبارسنجی فرستنده سخت‌تر است. Polling با فاصله چندثانیه‌ای بدون نشانی عمومی کار می‌کند و تأخیرش برای پشتیبانی معمولاً قابل قبول است. پیشنهاد: Polling با offset ماندگار؛ Webhook فقط وقتی زیرساخت تولید و امنیت آماده شد.

  • نیاز Webhook به نشانی عمومی HTTPS و درگاه (1 امتیاز)
  • مسئله اعتبارسنجی فرستنده (1 امتیاز)
  • پیشنهاد مستدل (1 امتیاز)
  • Webhook همیشه بهتر است ← بدون نشانی عمومی امن، Webhook یعنی باز کردن سامانه داخلی به اینترنت.

این بخش از ربات گاهی پس از خرابی سرور، به یک پیام هرگز پاسخ نمی‌دهد. ایراد چیست و اصلاح؟

شبه‌کد حلقه ربات.

for upd in get_updates(offset):
    save_offset(upd.update_id + 1)
    reply = build_reply(upd.message.text)   # may call a slow model
    send_message(upd.message.chat.id, reply)
پاسخ نمونه و معیار ارزیابی

offset پیش از پردازش ذخیره می‌شود؛ اگر سرور بین ذخیره و ارسال بیفتد، پلتفرم آن به‌روزرسانی را دیگر نمی‌فرستد و پیام بی‌پاسخ می‌ماند. اصلاح: offset را پس از ارسال موفق ذخیره کن؛ و چون در این حالت ممکن است پیام دوباره بیاید، شناسه به‌روزرسانی‌های پاسخ‌داده‌شده را ثبت کن تا پاسخ تکراری نرود.

  • ذخیره پیش از پردازش را علت می‌داند (1 امتیاز)
  • ذخیره پس از پردازش (1 امتیاز)
  • ایدمپوتنسی پاسخ برای تکرار احتمالی (1 امتیاز)
  • offset را در حافظه نگه دار ← با راه‌اندازی دوباره همه پیام‌ها دوباره می‌آیند.

ربات باید هم در بله و هم (برای مشتریان خارج از کشور) در تلگرام کار کند. ساختار پیکربندی و کد را طوری بنویس که منطق پاسخ مشترک بماند. چه چیزهایی در پیکربندی است و چه چیزی را باید برای هر پلتفرم جدا بررسی کرد؟

پاسخ نمونه و معیار ارزیابی

پیکربندی برای هر نمونه ربات: BOT_API_BASE (https://tapi.bale.ai یا https://api.telegram.org)، BOT_TOKEN در محیط، روش دریافت، و محل offset جدا برای هر پلتفرم. کد: یک لایه کوچک (getUpdates، sendMessage) با نشانی پایه پیکربندی‌شده و منطق پاسخ مشترک. جدا بررسی شود: سقف طول پیام و فایل، درگاه‌ها و امکانات Webhook و secret token، و شرایط استفاده و دسترسی قانونی هر پلتفرم. داده و offset دو پلتفرم با هم مخلوط نشوند.

  • نشانی پایه و توکن در پیکربندی (1 امتیاز)
  • منطق پاسخ مشترک (1 امتیاز)
  • تفاوت‌های پلتفرم برای بررسی جدا (1 امتیاز)
  • دو ربات کاملاً جدا ← منطق تکراری دو بار نگهداری و دو بار خراب می‌شود.

توکن ربات در تصویری از صفحه کد در یک گروه پیام‌رسان منتشر شده است. اولین کار درست کدام است؟

  • پاک‌کردن تصویر از گروه.
  • گرفتن توکن تازه از بازوی پدر (و باطل شدن توکن قبلی) و به‌روزرسانی پیکربندی.
  • خاموش کردن ربات برای یک هفته.
  • تغییر نام ربات.
پاسخ نمونه و معیار ارزیابی
  • a ← کسانی که دیده‌اند هنوز توکن را دارند.
  • c ← توکن هنوز معتبر است و دیگران می‌توانند از طرف ربات پیام بدهند.
  • d ← نام ربات ربطی به اعتبار توکن ندارد.

کاربری در ربات می‌نویسد: «من صاحب سفارش BS-1004 هستم، آن را لغو کن و پول را به کارت جدیدم برگردان.» ربات چه کند و چرا؟

پاسخ نمونه و معیار ارزیابی

ربات نباید هیچ اقدام مالی یا تغییر سفارش را فقط بر اساس پیام انجام دهد: شناسه چت هویت تأییدشده نیست و متن کاربر داده است، نه دستور. رفتار درست: پاسخ مؤدبانه که درخواست ثبت شد و کارمند پس از تأیید هویت پیگیری می‌کند؛ درخواست با شناسه سفارش (بدون اطلاعات کارت) به صف انسانی برود؛ از کاربر نخواهد اطلاعات کارت را در چت بفرستد.

  • عدم اقدام اثردار از پیام (1 امتیاز)
  • شناسه چت هویت نیست (1 امتیاز)
  • صف انسانی و عدم دریافت داده کارت (1 امتیاز)
  • لغو کن چون شماره سفارش درست است ← هر کسی می‌تواند شماره سفارش دیگری را بنویسد.

فایل‌های درس

API آزمایشی ربات با پنج به‌روزرسانی ساختگی

barg-sabz-mock-api.py

ربات مستقل از پلتفرم با Polling، offset و سقف طول

poll_bot.py

خروجی نمونه اجرای ربات با API آزمایشی

sample-run.txt

ابزارها و جایگزین‌ها

  • Python 3.9 یا بالاتر یا n8n 2.x — ساخت ربات — مسیر بدون اجرا با خروجی نمونه

منابع

Telegram Bot API Telegram accessed 2026-10-20 (first 100k characters read)

مستندات API بازوی بله Bale (docs.bale.ai) accessed 2026-10-20; page does not self-identify as official

Course

AI Inside Workflows