بات‌ها
میزبانی بات‌های تلگرام روی TelegramOS: ثبت، فلوهای بصری، وب‌هوک‌ها، broadcastها و محدودیت‌های نرخ به زبان ساده.
پلتفرم به شما اجازه می‌دهد بات‌های تلگرام را مستقیماً میزبانی کنید. هر بات روی زیرساخت پلتفرم اجرا می‌شود و می‌تواند با فلوهای پیام، هندلرهای وب‌هوک و قابلیت‌های broadcast پیکربندی شود.
ثبت بات
- بات خود را در تلگرام با گفتگو با @BotFather بسازید. یک توکن API دریافت می‌کنید.
- در پلتفرم، به بات‌ها > ثبت بات جدید بروید.
- نام کاربری بات، توکن API دریافتی از BotFather و در صورت تمایل یک نام نمایشی را وارد کنید.
- پلتفرم توکن را با Telegram Bot API بررسی می‌کند و در صورت موفقیت، بات را در فضای کاری شما ثبت می‌کند.
| فیلد | الزامی | توضیح |
|---|---|---|
| نام کاربری | بله | @username بات در تلگرام |
| توکن API | بله | توکنی که BotFather صادر کرده است |
| نام نمایشی | نه | یک برچسب دوستانه برای فضای کاری شما (به‌طور پیش‌فرض نام تلگرامی بات) |
| حالت تحویل | نه | polling (پیش‌فرض) یا webhook — پایین‌تر ببینید |
| فلوها | نه | آرایه‌ی JSONB از تعریف‌های فلو |
تعریف فلوها
رفتار بات به‌صورت فلو در ویرایشگر بصری فلو ساخته می‌شود. یک فلو از یک trigger شروع می‌شود و زنجیره‌ای از گره‌ها را اجرا می‌کند: اقدام‌ها، منطق و کنترل جریان.
| تریگر | زمان اجرا |
|---|---|
command | کاربر یک دستور می‌فرستد (مثلاً /start، /help) |
message | پیامی در چت با بات می‌رسد |
callback | کاربر یک دکمه‌ی کیبورد inline را فشار می‌دهد |
member_join | عضو جدیدی به گروهی که بات در آن است می‌پیوندد |
schedule | بر اساس زمان‌بندی |
webhook | یک فراخوانی وب‌هوک ورودی |
| گروه گره | گره‌ها |
|---|---|
| اقدام‌ها (14) | send_message، send_media، edit_message، delete_message، typing، ask، buttons، http، db، ai، poll، dice، location، contact |
| منطق (6) | condition، switch، set_variable، delay، random، loop |
| جریان (3) | end، goto، call |
حالت تحویل: polling یا وب‌هوک
بات به‌روزرسانی‌های تلگرام را به یکی از دو روش دریافت می‌کند:
- Polling — پلتفرم به‌روزرسانی‌ها را با
getUpdatesمی‌کشد. نیازی به URL عمومی نیست. این حالت پیش‌فرض است و پشت NAT هم کار می‌کند. - وب‌هوک — پلتفرم endpoint خودش را برای بات شما با
setWebhookثبت می‌کند، تا تلگرام به‌روزرسانی‌ها را مستقیماً به آن push کند. شما URL نمی‌دهید و به سرور خودتان هم نیاز ندارید.
تحویل‌های وب‌هوک با یک secret تصادفی 32 بایتی احراز هویت می‌شوند که پلتفرم برای هر بات تولید می‌کند و به‌عنوان secret_token به تلگرام می‌دهد. تلگرام آن را در هر به‌روزرسانی در هدر X-Telegram-Bot-Api-Secret-Token برمی‌گرداند و درخواست‌های بدون secret منطبق رد می‌شوند. تغییر به وب‌هوک یک secret جدید می‌سازد؛ بازگشت به polling آن را پاک می‌کند.
اگر برای پلتفرم URL عمومی وب‌هوک پیکربندی نشده باشد، بات‌ها روی polling نگه داشته می‌شوند.
درخواست‌هایی که گره‌ی درخواست HTTP یک فلو می‌فرستد ساده‌اند: فقط هدرهایی را که شما پیکربندی کرده‌اید حمل می‌کنند و امضا نمی‌شوند، پس چنین endpointهایی را با یک مسیر مخفی یا فهرست مجاز IP محافظت کنید. وب‌هوک‌های رویداد که در تنظیمات → کلیدهای API → وب‌هوک‌ها ثبت می‌شوند متفاوت‌اند — هر تحویل با X-TGP-Signature (HMAC-SHA256) امضا می‌شود؛ ببینید API › وب‌هوک‌ها.
محدودیت‌های نرخ
| محدودیت | دامنه | مقدار |
|---|---|---|
| گیرندگان broadcast | به ازای هر broadcast | 100 |
| طول پیام broadcast | به ازای هر broadcast | 1000 نویسه |
| فاصله‌ی ارسال | درون یک broadcast | ~0.05 ثانیه بین پیام‌ها |
| ثبت بات | به ازای هر کاربر | 10 در دقیقه |
نشست‌های فلو
فلوها یک‌باره نیستند. هر بات به ازای هر چت یک نشست فلو نگه می‌دارد و متغیرهایی که فلو تنظیم می‌کند در آن نشست زندگی می‌کنند.
askفلو را متوقف می‌کند؛ پاسخ کاربر در همان چت آن را از سر می‌گیرد.- نشست بعد از 6 ساعت منقضی می‌شود.
برای وضعیتی که باید بیش از یک نشست دوام بیاورد، آن را در سیستم خودتان نگه دارید، مثلاً از طریق گره‌ی http.
نقشه‌ی راه
قابلیت‌های زیر برای بات‌ها در نقشه‌ی راه هستند اما هنوز در دسترس نیستند:
- broadcastهای زمان‌بندی‌شده (یک‌باره و تکرارشونده)
- پشتیبانی از حالت inline
- یکپارچه‌سازی پرداخت از طریق Telegram Stars
- داشبورد تحلیل بات (حجم پیام، رشد کاربران، زمان پاسخ)
ایمنی broadcast
broadcastهای بات‌ها مشمول این محدودیت‌ها هستند:
- حداکثر 100 گیرنده به ازای هر broadcast
- حداکثر 1000 نویسه به ازای هر پیام
- فاصله‌گذاری: ارسال‌ها با فاصله‌ی حدود 0.05 ثانیه انجام می‌شوند
- فیلتر کلمات اسپم: متن‌هایی که شامل کلماتی مانند "airdrop"، "casino" یا "buy now" باشند رد می‌شوند