Skip to content

About

Bot Pilot — Telegram bot manager for Android (Kotlin + Jetpack Compose + Material3)

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🤖 TelegramBotManager — مدیریت کامل ربات‌های تلگرام در جیب شما

اپلیکیشن بومی اندروید (Kotlin + Jetpack Compose) برای مدیریت چندین ربات تلگرام از یک جا: موتور پاسخ‌گویی خودکار ۲۴ ساعته (دستورها، کلمات کلیدی و خوش‌آمد)، ارسال پیام و مدیا با کیبورد شیشه‌ای، زمان‌بندی با تقویم شمسی، دستیار هوشمند کسب‌وکار، آمار، بکاپ رمزنگاری‌شده، آپدیت درون‌برنامه‌ای و رابط دوزبانه (فارسی/English) با تم روشن/تیره.

Build APK


✨ امکانات

ابزار توضیح
🔐 مدیریت چندربات افزودن نامحدود ربات؛ توکن‌ها با AES (Android Keystore) رمزنگاری و فقط روی گوشی ذخیره می‌شوند
✅ اعتبارسنجی خودکار هنگام افزودن، توکن با getMe بررسی و مشخصات ربات نمایش داده می‌شود
💬 ارسال پیام متن با فرمت Markdown / HTML، ارسال بی‌صدا، و سازنده کیبورد شیشه‌ای (Inline Keyboard) با ردیف‌بندی دلخواه
🖼 ارسال مدیا عکس و فایل (از لینک مستقیم یا از حافظه گوشی) + ارسال موقعیت مکانی
⌨️ دستورات ربات ساخت/ویرایش/حذف منوی /commands با اعتبارسنجی قالب دستور
🪝 وب‌هوک setWebhook / deleteWebhook / getWebhookInfo با نمایش وضعیت و خطاهای اخیر
📥 پیام‌های دریافتی دریافت زنده آپدیت‌ها با getUpdates هر ۳ ثانیه + کپی سریع chat_id
💬 چت‌ها مشاهده و پاسخ گفت‌وگوهای ربات با حباب پیام، شمارندهٔ نخوانده و همگام‌سازی خودکار
📢 پیام همگانی ارسال به چند chat_id با تأخیر ۶۰ms (ضد لیمیت)، نوار پیشرفت و لغو
📝 قالب پیام ذخیرهٔ متن‌های پرتکرار و جایگزینی متغیرهای {first_name} و {username}
👥 مدیریت اعضا بن/آنبن، ارتقا به ادمین، پین پیام در گروه و کانال
📊 نظرسنجی ساخت نظرسنجی و کوییز با نمایش زندهٔ نتایج و پایان دادن
🛰 پاسخگویی خودکار ۲۴ ساعته سرویس پیش‌زمینه‌ای که همیشه getUpdates را گوش می‌دهد و به /start، دستورهای اختصاصی، کلمات کلیدی و پیام‌های ناشناخته خودکار جواب می‌دهد — با وب‌هوک‌زدایی خودکار، Long Polling و ادامه کار پس از بسته شدن اپ
⚡ ربات ابری ۲۴/۷ روی گیت‌هاب (حتی با گوشی خاموش) پاسخ‌گویی ۲۴ ساعته از GitHub Actions — رایگان، بدون کارت، بدون کلادفلر: فعال‌سازی یک‌ضربه‌ای داخل اپ، توکن رمزنگاری‌شده با sealed box، فوروارد پیام‌ها به چت مدیر و پاسخ با ریپلای
🧰 بررسی سلامت ربات یک لمس: سالم بودن توکن، وب‌هوک مزاحم (حذف خودکار) و فعال بودن گوش‌دهی زنده
🤖 دستیار هوشمند کافی است کسب‌وکارت را معرفی کنی؛ دستیار هویت ربات، منوی دستورات، پیام خوش‌آمد، قالب‌ها، نظرسنجی و برنامهٔ هفتگی را می‌سازد و با یک لمس روی ربات اعمال می‌کند (کاملاً آفلاین، بدون سرویس خارجی)
⏰ زمان‌بندی پیام ارسال خودکار پیام در تاریخ و ساعت مشخص با تقویم شمسی کامل (انتخابگر ماه/سال/روز فارسی) با تکرار روزانه/هفتگی و لغو — حتی وقتی اپ بسته است (WorkManager)
📈 آمار ربات نمودار فعالیت ۷ روز اخیر، تفکیک پیام‌ها و چت‌ها، وضعیت وب‌هوک و پرگفت‌وگوترین مخاطبان
👤 پروفایل ربات تغییر نام، توضیحات و توضیح کوتاه ربات با setMyName / setMyDescription / setMyShortDescription
🎨 تم روشن/تیره/سیستمی دو پالت کامل «تلگرام پرمیوم» (تیره و روشن) با انتخاب دستی یا خودکار و ذخیره ماندگار
🌐 دوزبانه (فا/EN) زبان فارسی و انگلیسی برای چارچوب اپ، تنظیمات و بخش‌های جدید از بخش تنظیمات قابل تغییر است
💾 بکاپ رمزنگاری‌شده خروجی/بازیابی همه‌چیز (ربات‌ها + توکن‌ها، پاسخ‌گویی، زمان‌بندی، قالب‌ها، چت‌ها و تنظیمات) در یک فایل با AES-256-GCM و کلید برگرفته از رمز عبور شما (PBKDF2)
🔄 آپدیت درون‌برنامه‌ای چک خودکار Releaseهای گیت‌هاب، دانلود APK با DownloadManager و اجرای نصب بدون خروج از برنامه

حداقل نسخه پشتیبانی‌شده: اندروید ۷ (API 24) — هدف: اندروید ۱۴ (API 34)


🧠 چرا ربات من به دستورها جواب نمی‌داد؟ (و حالا چطور جواب می‌دهد)

ربات تلگرام «برنامه‌ای» نیست که خودش اجرا شود؛ فقط یک API است. تا قبل از نسخه ۲ این اپ فقط وقتی صفحه «چت‌ها» یا «پیام‌های دریافتی» باز بود پیام‌ها را می‌دید و هیچ‌وقت خودکار پاسخ نمی‌داد. از v2.0.0 موتور پاسخ‌گویی به‌صورت سرویس پیش‌زمینه ۲۴ ساعته فعال می‌شود:

  1. وارد ربات شوید → ابزار پاسخگویی خودکار.
  2. کلید گوش‌دهی ۲۴ ساعته را روشن کنید (اجازه اعلان و در صورت پرسیدن، استثنا از بهینه‌سازی باتری را بدهید).
  3. دستورها + پاسخ‌شان را اضافه کنید و «ذخیره» بزنید؛ دکمه «همگام‌سازی منوی تلگرام» همان فهرست را در منوی ربات هم ثبت می‌کند.
  4. دستورهای /start، /help، /id و /about به‌صورت خودکار ساخته می‌شوند؛ متن خوش‌آمد و پاسخ دستور ناشناخته هم قابل تنظیم است.
  5. ابزار بررسی سلامت در همان صفحه سالم بودن توکن، وب‌هوک مزاحم و فعال بودن گوش‌دهی را چک می‌کند.

نکته: برای پاسخ‌گویی پایدار، اپ را از «بهینه‌سازی باتری» مستثنا کنید (تنظیمات گوشی → باتری). اگر گوشی‌تان اپ را بکشد، با باز کردن دوباره اپ سرویس خودکار برمی‌گردد.

☁️ ربات ابری ۲۴/۷ روی گیت‌هاب — حتی با گوشی خاموش

مغز هر ربات تلگرام باید روی یک دستگاه همیشه‌روشن اجرا شود. این اپ آن دستگاه را GitHub Actions می‌کند: رایگان نامحدود برای مخزن عمومی، بدون کارت، و — برخلاف کلادفلر — در ایران باز (همان گیت‌هابی که آپدیت‌های اپ از آن می‌آید). فعال‌سازی:

  1. وارد ربات شوید → ابزار ربات ابری ۲۴/۷.
  2. گام ۱: در مرورگر یک توکن گیت‌هاب بسازید (تیک‌های public_repo + workflow) و داخل اپ بچسبانید — اپ آن را با Keystore رمزنگاری می‌کند.
  3. گام ۲: دکمه فعال‌سازی ربات ابری ۲۴/۷ را بزنید؛ اپ خودش یک مخزن عمومی کوچک می‌سازد، موتور پاسخ‌گو، زمان‌بند و قوانین را آپلود می‌کند، توکن ربات را با libsodium sealed box به‌صورت Secret ذخیره می‌کند و اولین اجرا را چک می‌کند.
  4. از این لحظه هر دقیقه گیت‌هاب موتور را اجرا می‌کند و ربات حتی با گوشی خاموش به /start، دستورها، کلیدواژه‌ها و… جواب می‌دهد.
  5. پیام کاربران به «صندوق پیام» (چت مدیر) فوروارد می‌شود؛ ریپلای روی هر پیام، همان متن را به آن کاربر می‌فرستد.

امنیت: مخزن فقط موتور و قوانین را دارد؛ توکن ربات Secret رمزنگاری‌شده است و هیچ‌وقت در کد یا لاگ ظاهر نمی‌شود. قوانین را از «پاسخگویی خودکار» تغییر دهید و با دکمه «همگام‌سازی قوانین با ابر» پخش کنید. خاموش‌کردن = حذف کامل مخزن.

⚡ ربات همیشه فعال ۲۴/۷ — روی خود گوشی (جایگزین)

ربات مستقیم روی خودِ گوشی اجرا می‌شود؛ یعنی هر کسی که اپ را نصب کند، همان لحظه بدون ساخت هیچ حسابی (بدون سرور، بدون توکن اضافه) صاحب یک ربات ۲۴ ساعته است. سرویس پیش‌زمینه‌ای اپ با چهار لایه پایداری محافظت می‌شود:

  1. سرویس پیش‌زمینه چسبنده (START_STICKY) — اگر اندروید اپ را بکشد، خودش دوباره بالا می‌آید.
  2. راه‌اندازی خودکار پس از ری‌استارت — گوشی را خاموش/روشن کنید؛ سرویس خودش برمی‌گردد.
  3. نگه‌بان داخلی هر ۱۵ دقیقه — اگر کشنده‌های سخت‌گیر (MIUI و…) سرویس را خواباندند، احیا می‌شود.
  4. معافیت از بهینه‌سازی باتری + شروع خودکار سازندهٔ گوشی — با یک لمس از صفحه «ربات همیشه فعال».

مسیر: وارد ربات شوید → ابزار ربات همیشه فعال → کلید وضعیت را روشن کنید و چک‌لیست همان صفحه را سبز کنید (معافیت باتری، اجازه اعلان و تنظیم شروع خودکار گوشی). قوانین پاسخ‌ها (دستورها، کلمات کلیدی، خوش‌آمد) از ابزار «پاسخگویی خودکار» ویرایش می‌شود.

نکته: در این روش ربات به گوشی روشن و اینترنت نیاز دارد. از داخل اعلان دائمی هم می‌توانید سرویس را با دکمه «توقف» موقتاً pause کنید (تا وقتی دوباره داخل اپ روشنش کنید، هیچ نگه‌بانی آن را روشن نمی‌کند).

🚀 شروع سریع

۱) گرفتن توکن ربات

  1. در تلگرام به @BotFather پیام بدهید.
  2. دستور /newbot را بفرستید و مراحل ساخت را کامل کنید.
  3. توکن (به شکل 123456789:AAHfiqksKZ8WbR5P...) را کپی کنید.
  4. در اپ، دکمه + را بزنید و توکن را وارد کنید؛ اپ آن را اعتبارسنجی و ربات را ذخیره می‌کند.

۲) پیدا کردن chat_id مخاطب

  • به ربات خود پیام بدهید (یا /start بفرستید).
  • در اپ، وارد ربات شوید → ابزار پیام‌های دریافتی → دکمه پخش (▶) → chat_id پیام‌رسان را کپی کنید.

۳) ساختن اپ (Build)

راه اول — Android Studio (پیشنهادی):

  1. پروژه را در Android Studio (نسخه Hedgehog یا جدیدتر) باز کنید.
  2. صبر کنید تا Gradle Sync تمام شود.
  3. دکمه Run ▶ یا منوی Build → Build Bundle(s) / APK(s) → Build APK(s).

راه دوم — خط فرمان:

./gradlew assembleDebug      # APK دیباگ
./gradlew assembleRelease    # APK ریلیز (فقط با تنظیمات امضای امن؛ بدون آن ساخت با خطا متوقف می‌شود)

خروجی: app/build/outputs/apk/

🔐 نسخه Release فقط با کلید امضای امن (خارج از مخزن) ساخته می‌شود؛ fallback به کلید debug عمداً غیرممکن است. راهنمای کامل: DEPLOYMENT.md.


📤 انتشار روی گیت‌هاب

روش گرافیکی (ساده‌ترین)

  1. در github.com/new یک ریپوی جدید با نام TelegramBotManager بسازید (بدون README یا لایسنس).
  2. در پوشه پروژه این دستورات را بزنید:
git init
git add .
git commit -m "Initial commit: Telegram Bot Manager"
git branch -M main
git remote add origin https://github.com/YOUR-USERNAME/TelegramBotManager.git
git push -u origin main

گرفتن APK بدون نصب Android Studio

بعد از هر push، اکشن Build APK اجرا می‌شود:

  • تب Actions در ریپو → آخرین اجرا → بخش Artifacts → دانلود TelegramBotManager-debug یا TelegramBotManager-release.

انتشار خودکار در Releases

کافیست یک تگ بزنید و push کنید:

git tag v1.0.0
git push origin v1.0.0

اکشن Release به‌طور خودکار APK را build کرده و در بخش Releases ریپو منتشر می‌کند. ✅


🗂 ساختار پروژه

TelegramBotManager/
├── .github/workflows/          ← ساخت خودکار APK و انتشار Release
├── app/src/main/
│   ├── java/com/telegrambot/manager/
│   │   ├── MainActivity.kt
│   │   ├── data/
│   │   │   ├── api/            ← TelegramApi (Retrofit) + TelegramRepo
│   │   │   ├── engine/         ← BotEngine: موتور پاسخ‌گویی ۲۴ ساعته
│   │   │   ├── update/         ← آپدیت درون‌برنامه‌ای (GitHub Releases)
│   │   │   ├── backup/         ← بکاپ رمزنگاری‌شده AES-GCM
│   │   │   ├── model/          ← مدل‌های Bot API (Gson)
│   │   │   └── store/          ← BotStore: ذخیره رمزنگاری‌شده توکن‌ها
│   │   ├── ui/
│   │   │   ├── components/     ← کامپوننت‌های مشترک
│   │   │   ├── screens/        ← ۲۰ صفحه اپ
│   │   │   └── theme/          ← تم رنگ پویا + فالبک تلگرامی
│   │   └── vm/                 ← ViewModelها
│   └── res/                    ← آیکون، تم، رشته‌ها
├── build.gradle.kts
└── settings.gradle.kts

🔒 امنیت

  • توکن‌ها با EncryptedSharedPreferences + کلید داخل Android Keystore رمزنگاری می‌شوند و هیچ‌جا (لاگ، سرور، حافظه ابری) ارسال یا ذخیره نمی‌شوند.
  • هر درخواست فقط مستقیماً به https://api.telegram.org زده می‌شود (ترافیک HTTP مسدود است) — هیچ سرور واسطی در بین نیست و توکن‌ها فقط بین گوشی شما و تلگرام جابه‌جا می‌شوند.
  • مجوزهای حداقلی: INTERNET (API تلگرام و گیت‌هاب)، POST_NOTIFICATIONS (اعلان سرویس پاسخ‌گویی)، FOREGROUND_SERVICE(_DATA_SYNC/_SPECIAL_USE) (موتور ۲۴ ساعته)، RECEIVE_BOOT_COMPLETED (اجرای خودکار پس از ری‌استارت)، REQUEST_INSTALL_PACKAGES (آپدیت درون‌برنامه‌ای) و REQUEST_IGNORE_BATTERY_OPTIMIZATIONS (فقط با تأیید خود کاربر، برای پایداری سرویس). بدون دسترسی به مخاطب، موقعیت یا فایل‌ها (بکاپ از طریق فایل‌پیکر سیستمی است).
  • allowBackup=false است تا توکن‌ها وارد بکاپ سیستمی نشوند؛ بکاپِ برنامه‌ای کاملاً رمزنگاری‌شده و فقط با رمز عبور خودتان قابل بازیابی است.
  • هرگز فایل local.properties یا APK منتشرشده خود را حاوی توکن واقعی قرار ندهید — توکن‌ها فقط داخل اپ وارد می‌شوند.

🗝️ امضای نسخه‌های Release

همه APKهای ریلیز با یک کلید ثابت امضا می‌شوند تا آپدیت‌ها بدون حذف نسخه قبلی نصب شوند. از اکتبر ۲۰۲۶، پس از افشای کلید قدیمی در تاریخچه این مخزن عمومی (از v1.2.0 تا v2.4.0)، کلید امضا چرخانده شده و دیگر به‌هیچ‌وجه داخل مخزن نگهداری نمی‌شود:

  • کلید فقط در دو جای امن زندگی می‌کند: GitHub Secrets (برای ساخت خودکار در Actions) و نسخه محلی git-ignored روی دستگاه توسعه (keystore/keystore.properties).
  • چهار secret موردنیاز: KEYSTORE_BASE64، KEYSTORE_PASSWORD، KEYSTORE_ALIAS و KEY_PASSWORD — بدون آن‌ها workflow انتشار عمداً شکست می‌خورد و هرگز APK با کلید debug منتشر نمی‌شود.
  • جزئیات و نحوه چرخش کلید: SECURITY.md و DEPLOYMENT.md.
  • ⚠️ چون کلید عوض شده، نصب نسخه جدید روی نسخه‌های قدیمی مستقیماً ممکن نیست: اول از داخل اپ بکاپ رمزنگاری‌شده بگیرید، نسخه قبلی را حذف و APK جدید را نصب کنید و سپس بازیابی کنید. مراحل کامل در DEPLOYMENT.md.

❓ عیب‌یابی

مشکل راه‌حل
خطای 401 Unauthorized هنگام افزودن ربات توکن اشتباه است؛ از BotFather با /mybots دوباره کپی کنید
در «پیام‌های دریافتی» چیزی نمی‌آید وب‌هوک فعال است؛ از ابزار وب‌هوک آن را حذف کنید
خطای chat not found chat_id را با «پیام‌های دریافتی» بررسی کنید؛ برای کانال، اپ را ادمین کانال کنید
خطای وب‌هوک در تنظیم آدرس باید https و روی پورت 443/80/88/8443 باشد
ربات بعد از چند ساعت ساکت می‌شود از صفحه «ربات همیشه فعال» معافیت باتری را فعال و طبق راهنمای همان صفحه «شروع خودکار» گوشی را تنظیم کنید
ربات ابری بی‌خبر شد در صفحه «ربات ابری ۲۴/۷» دکمه «بررسی دوباره» را بزنید؛ گیت‌هاب زیر بار گاهی چند دقیقه دیرتر اجرا می‌کند و خودش جبران می‌کند
بعد از ری‌استارت گوشی ربات جواب نمی‌دهد اپ را یک‌بار باز کنید؛ از این به بعد Boot Receiver خودش سرویس را بالا می‌آورد
دکمه «توقف» در اعلان زدم و ربات جواب نمی‌دهد طبیعی است؛ سرویس pause شده — داخل اپ کلید «ربات همیشه فعال» را دوباره روشن کنید
دستورات ذخیره نمی‌شوند فرمان فقط حروف کوچک a-z، عدد و _ (تا ۳۲ کاراکتر) باشد

🧱 تکنولوژی‌ها

Kotlin 1.9 · Jetpack Compose (BOM 2024.06) · Material 3 + Dynamic Color · Retrofit + OkHttp · Coroutines & StateFlow · EncryptedSharedPreferences · Navigation Compose

📄 لایسنس

این پروژه بدون لایسنس منتشر شده است. برای انتشار عمومی پیشنهاد می‌شود یک فایل LICENSE (مثلاً MIT) اضافه کنید.

About

Bot Pilot — Telegram bot manager for Android (Kotlin + Jetpack Compose + Material3)

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages