{"id":50705483,"url":"https://github.com/sudo-py-dev/telegram-bot-template","last_synced_at":"2026-06-09T11:01:52.333Z","repository":{"id":319024997,"uuid":"1077699810","full_name":"sudo-py-dev/telegram-bot-template","owner":"sudo-py-dev","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-16T16:02:48.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-17T06:57:11.156Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sudo-py-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-16T16:00:46.000Z","updated_at":"2025-10-16T16:02:52.000Z","dependencies_parsed_at":"2025-10-17T20:10:50.136Z","dependency_job_id":"3aa9fc73-1877-4209-8e0b-e6873dc84c2d","html_url":"https://github.com/sudo-py-dev/telegram-bot-template","commit_stats":null,"previous_names":["sudo-py-dev/telegram-bot-template"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sudo-py-dev/telegram-bot-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Ftelegram-bot-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Ftelegram-bot-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Ftelegram-bot-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Ftelegram-bot-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sudo-py-dev","download_url":"https://codeload.github.com/sudo-py-dev/telegram-bot-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Ftelegram-bot-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34103357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T11:01:52.264Z","updated_at":"2026-06-09T11:01:52.319Z","avatar_url":"https://github.com/sudo-py-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 תבנית בוט טלגרם\n\nתבנית בוט טלגרם מודרנית ועשירה בתכונות שנבנתה עם Pyrogram ו-Python. תבנית זו מספקת בסיס מוצק לבניית בוטי טלגרם עם תמיכה בריבוי שפות, אינטגרציה עם מסד נתונים, ניהול אדמינים, פאנל ניהול מתקדם ועוד.\n\n[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)\n[![PyroTGFork](https://img.shields.io/badge/PyroTGFork-2.0+-blue)](https://pypi.org/project/pyrotgfork/)\n[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)\n[![Telegram](https://img.shields.io/badge/Telegram-Channel-blue)](https://t.me/termux_il)\n\n## ✨ תכונות עיקריות\n\n- **🌐 תמיכה בריבוי שפות** - תמיכה מובנית בעברית ובאנגלית עם יכולת הרחבה קלה\n- **👥 ניהול משתמשים** - רישום משתמשים מלא ומעקב אחר העדפות\n- **👑 מערכת אדמינים** - בדיקת הרשאות מתקדמת עם בקרות מפורטות\n- **⚙️ פאנל ניהול** - ממשק ניהול מתקדם עם שליטה בהגדרות\n- **🔒 אבטחה** - אימות דו-שלבי למנהלים ובקרת גישה מפורטת\n- **💾 מסד נתונים** - SQLAlchemy ORM עם תמיכה ב-SQLite\n- **📊 לוגים מתקדמים** - מערכת לוגים עם שמירת קבצים ופלט צבעוני\n- **⚡ ביצועים** - אופטימיזציה של שאילתות ופעולות אסינכרוניות\n- **🔔 התראות** - מערכת התראות לאירועים חשובים\n- **🔄 ממשק API** - תמיכה בהרחבות ושילובים\n\n\n### 🏗️ שיפורי ארכיטקטורה\n- ארגון מחדש של הקוד לחבילות לוגיות\n- הפרדת אחריות ברורה בין רכיבי המערכת\n- שיפור ניהול ה-handlers עם מערכת רישום גמישה\n\n### 🛠️ שיפורי קוד\n- שכתוב מערכת ההרשאות למנהלים\n- שיפור בטיפול בשגיאות ורישום אירועים\n- עדכון רמזי סוגים ותיעוד\n- אופטימיזציה של ביצועים\n\n### ✨ תכונות חדשות\n- אשף התקנה אינטראקטיבי\n- ניהול הרשאות מתקדם\n- מערכת לוגים משופרת\n- ממשק ניהול אינטואיטיבי\n\n## 🚀 התחלה מהירה\n\n### דרישות מערכת\n\n- Python 3.8 ומעלה\n- חשבון טלגרם פעיל\n- אסימון בוט מ-[@BotFather](https://t.me/botfather)\n- API ID ו-API Hash מ-[my.telegram.org](https://my.telegram.org)\n\n### 🛠️ התקנה\n\n1. **שכפול המאגר**\n   ```bash\n   git clone https://github.com/sudo-py-dev/telegram-bot-template.git\n   cd telegram-bot-template\n   ```\n\n2. **הגדרת סביבת פיתוח**\n   ```bash\n   # יצירת סביבה וירטואלית\n   python -m venv .venv\n   \n   # הפעלת הסביבה\n   # ל-Linux/macOS:\n   source .venv/bin/activate\n   # ל-Windows:\n   .venv\\Scripts\\activate.bat\n   ```\n\n3. **התקנת תלויות**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **הגדרת משתני סביבה**\n   ```bash\n   cp .env.example .env\n   # ערוך את הקובץ והוסף את הפרטים שלך\n   ```\n\n5. **הרצת הבוט**\n   ```bash\n   python index.py\n   ```\n\n## ⚙️ הגדרת משתני סביבה\n\nהעתק את הקובץ `.env.example` ל-`.env` והגדר את המשתנים הבאים:\n\n```env\n# ===== הגדרות חובה =====\nBOT_TOKEN=your_telegram_bot_token_here  # מאת @BotFather\nAPI_HASH=your_api_hash_here             # מ-https://my.telegram.org\nAPI_ID=your_api_id_here                 # מ-https://my.telegram.org\nBOT_CLIENT_NAME=my_bot                 # שם ייחודי לבוט שלך\nBOT_OWNER_ID=your_telegram_id          # המזהה הטלגרם שלך\n\n# ===== הגדרות מסד נתונים =====\nDATABASE_URL=sqlite+aiosqlite:///my_bot.sqlite  # כתובת מסד הנתונים\n\n# ===== הגדרות לוגים =====\nLOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL\nLOG_FILE=bot.log  # קובץ הלוגים\n```\n\n### 🛠️ קבלת פרטי גישה\n\n1. **יצירת בוט חדש**\n   - שלח הודעה ל-[@BotFather](https://t.me/botfather)\n   - השתמש בפקודה `/newbot` ועקוב אחר ההוראות\n   - שמור את ה-token שהתקבל\n\n2. **קבלת API ID ו-Hash**\n   - היכנס ל-[my.telegram.org](https://my.telegram.org)\n   - התחבר עם פרטי חשבון הטלגרם שלך\n   - עבור ל-API development tools\n   - צור אפליקציה חדשה וקבל את ה-API ID וה-Hash\n\n3. **מזהה משתמש**\n   - שלח הודעה ל- [@userinfobot](https://t.me/userinfobot)\n   - הקבל את המזהה שלך מהתשובה\n\n## 📁 מבנה הפרויקט\n\n```\ntelegram-bot-template/\n├── bot_management/           # כלי ניהול לבעלי הבוט\n│   ├── bot_settings.py       # פקודות והגדרות הבוט\n│   ├── callback_handlers.py  # טיפול בשאילתות חוזרות של לוח הבקרה\n│   └── setup.py              # כלי התקנה ואתחול לבוט\n├── handlers/                 # מנהלי הודעות ושאילתות\n│   ├── callback_handlers.py  # טיפול בשאילתות חוזרות\n│   ├── command_handlers.py   # פקודות הבוט (/start, /help וכו')\n│   ├── join_handlers.py      # טיפול בהצטרפות לקבוצות\n│   └── message_handlers.py   # טיפול בהודעות רגילות\n├── locales/                  # קבצי תרגום\n│   ├── messages.json         # הודעות רב-לשוניות\n│   └── privileges.json       # הגדרות הרשאות\n└── tools/                    # כלי ליבה ושירותים\n    ├── database.py           # מודלים ופעולות מסד נתונים\n    ├── enums.py              # קבועים וניהול הודעות\n    ├── inline_keyboards.py   # יצירת מקלדות מובנות\n    ├── logger.py             # הגדרות רישום\n    └── tools.py              # פונקציות עזר\n├── .env.example              # תבנית הגדרות סביבה\n├── .gitignore               # דפוסי התעלמות מגיט\n├── index.py                 # נקודת כניסה ראשית של הבוט\n├── requirements.txt         # תלויות Python\n├── README.md                # קובץ זה (עברית)\n└── README_EN.md             # גרסה באנגלית\n```\n\n## ⚙️ לוח בקרת מנהלים\n\n### כניסה ללוח הבקרה\nשלח את הפקודה `/admin` בצ'אט פרטי עם הבוט.\n\n### תכונות עיקריות\n\n#### 📊 לוח מחוונים\n- סקירה כללית של סטטיסטיקות הבוט\n- מצב מערכת בזמן אמת\n- התראות ואירועים אחרונים\n\n#### 👥 ניהול משתמשים\n- צפייה ברשימת משתמשים\n- ניהול הרשאות משתמשים\n- חסימת משתמשים\n\n#### ⚙️ הגדרות\n- **הגדרות אבטחה**\n  - הגבלות גישה\n  - יומן אירועים\n- **הגדרות בוט**\n  - שפת ברירת מחדל\n  - עיצוב הודעות\n  - תצוגת תצוגה מקדימה\n\n#### 📝 לוגים\n- צפייה בלוגים בזמן אמת\n- סינון לפי רמת חומרה\n- ייצוא לוגים לניתוח\n\n## 🛠️ פיתוח והרחבה\n\n### הוספת פקודות חדשות\n\n1. צור handler חדש ב-`handlers/command_handlers.py`:\n   ```python\n   from pyrogram import filters\n   from tools.tools import with_language\n   \n   @with_language\n   async def my_command(client, message, language: str):\n       await message.reply(f\"שלום! השפה הנוכחית היא: {language}\")\n   ```\n\n2. הוסף את הפקודה לרשימת ה-handlers:\n   ```python\n   from pyrogram.handlers import MessageHandler\n   \n   commands_handlers = [\n       MessageHandler(my_command, filters.command(\"mycommand\")),\n       # ... שאר הפקודות\n   ]\n   ```\n\n### הוספת שפות חדשות\n\n1. הוסף את התרגומים החדשים לקובץ `locales/messages.json`:\n   ```json\n   {\n     \"en\": {\n       \"welcome\": \"Welcome to the bot!\"\n     },\n     \"he\": {\n       \"welcome\": \"ברוכים הבאים לבוט!\"\n     },\n     \"es\": {\n       \"welcome\": \"¡Bienvenido al bot!\"\n     }\n   }\n   ```\n\n2. השתמש בהודעות עם מערכת התרגום:\n   ```python\n   from tools.enums import Messages\n   \n   @with_language\n   async def welcome(client, message, language: str):\n       messages = Messages(language=language)\n       await message.reply(messages.welcome)\n   ```\n\n## 🛠️ שימוש\n\n### הוספת פקודות חדשות למנהל\n\n#### פקודות למנהל הבוט\n```python\nfrom tools.tools import owner_only\n\n@owner_only\n@with_language\nasync def admin_command(client, message, language: str):\n    # קוד הפקודה למנהל\n    pass\n```\n\n### הוספת פקודות חדשות\n\n1. **צור פונקציית handler** ב- `handlers/commands.py`:\n   ```python\n   from tools.tools import with_language\n   from tools.enums import Messages\n\n   @with_language\n   async def my_command(client, message, language: str):\n       await message.reply(Messages(language=language).my_message)\n   ```\n\n2. **רשום את הפקודה** ברשימת `commands_handlers`:\n   ```python\n   commands_handlers = [\n       MessageHandler(my_command, filters.command(\"mycommand\")),\n       # ... handlers קיימים\n   ]\n   ```\n\n### הוספת שפות חדשות\n\n1. **הוסף הודעות** ל- `tools/messages.json`:\n   ```json\n   {\n     \"fr\": {\n       \"hello\": \"Bonjour {}\",\n       \"goodbye\": \"Au revoir\"\n     }\n   }\n   ```\n\n2. **עדכן שמות תצוגת שפות** ב- `handlers/callback_buttons.py`:\n   ```python\n   language_display_names = {\n       \"he\": \"עברית 🇮🇱\",\n       \"en\": \"English 🇺🇸\",\n       \"fr\": \"Français 🇫🇷\"\n   }\n   ```\n\n### ניהול הגדרות בוט\n\n```python\nfrom database import BotSettings\n\n# קבלת הגדרות\nsettings = BotSettings.get_settings()\n\n# עדכון הגדרות\nBotSettings.update_settings(\n    can_join_group=True,\n    can_join_channel=False,\n    owner_id=123456789\n)\n\n\n### פעולות מסד נתונים\n\n```python\nfrom database import Users, Chats\n\n# צור משתמש\nUsers.create(user_id=123456789, username=\"user\", language=\"en\")\n\n# קבל משתמש\nuser = Users.get(user_id=123456789)\n\n# עדכן משתמש\nUsers.update(user_id=123456789, language=\"he\")\n\n# ספירת משתמשים\nuser_count = Users.count()\nactive_users = Users.count_by(is_active=True)\n\n# ספירת צ'אטים\nchat_count = Chats.count()\nactive_chats = Chats.count_by(is_active=True)\n```\n\n## 🌍 מערכת ריבוי שפות\n\nהבוט תומך במספר שפות עם מערכת ניהול הודעות חכמה:\n\n- **אחסון הודעות**: כל ההודעות מאוחסנות בפורמט JSON\n- **מערכת fallback**: חוזרת לאנגלית אם ההודעה לא נמצאה\n- **טעינה דינמית**: שפות נטענות מ- `messages.json` בזמן ריצה\n- **הרחבה קלה**: הוסף שפות חדשות על ידי עדכון קובץ JSON\n\n## 👑 מערכת אדמינים\n\nבדיקת הרשאות אדמין מתקדמת עם תמיכה ב:\n- **הרשאות מפורטות**: בדיקת זכויות אדמין ספציפיות\n- **סוגי צ'אטים**: עובד עם קבוצות, סופרגרופים וערוצים\n- **מטמון**: רשימות אדמינים במטמון לביצועים\n- **טיפול שגיאות**: טיפול ב- בצ'אטים/הרשאות לא תקינים\n\n```python\nfrom tools.tools import is_admin_message\n\n@is_admin_message(permission_require=\"can_restrict_members\")\nasync def admin_only_command(client, message):\n    await message.reply(\"אתה אדמין!\")\n```\n\n## 📊 מערכת לוגים מתקדמת\n\n### תכונות עיקריות\n- **📝 רישום מקיף** - תמיכה בכל רמות הלוגים (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n- **📁 ניהול קבצים** - רוטציה אוטומטית של קבצי לוג\n- **🎨 פלט צבעוני** - הבחנה ויזואלית בין סוגי הלוגים\n- **⏱️ חותמות זמן** - תיעוד מדויק של זמן האירועים\n- **🔍 מידע מפורט** - מיקום קוד, תהליך, ו-thread\n\n### דוגמאות שימוש\n\n```python\nfrom tools.logger import setup_logger\n\n# אתחול לוגר\nlogger = setup_logger(__name__)\n\n# דוגמאות לוגים\nlogger.debug(\"הודעת דיבאג מפורטת\")\nlogger.info(\"מידע כללי\")\nlogger.warning(\"אזהרה חשובה\")\nlogger.error(\"שגיאה קריטית\")\nlogger.critical(\"שגיאה חמורה\")\n\n# הודעת הצלחה מותאמת אישית\nlogger.success(\"הפעולה בוצעה בהצלחה!\")\n\n# מדידת ביצועים\nimport time\nstart_time = time.time()\n# קוד למדידת ביצועים\nlogger.info(f\"זמן ביצוע: {time.time() - start_time:.2f} שניות\")\n```\n\n### הגדרת רמת לוגים\n\nניתן לקבוע את רמת הלוגים באמצעות משתנה הסביבה `LOG_LEVEL` בקובץ `.env`:\n\n```env\nLOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL\nLOG_FILE=bot.log  # קובץ הלוגים\n```\n\n### פלט לדוגמה\n\n```\n2023-10-09 15:42:18.123 | DEBUG    | module.name:12 - הודעת דיבאג מפורטת\n2023-10-09 15:42:19.456 | INFO     | module.name:15 - מידע כללי\n2023-10-09 15:42:20.789 | WARNING  | module.name:18 - אזהרה חשובה\n2023-10-09 15:42:21.012 | ERROR    | module.name:21 - שגיאה קריטית\n2023-10-09 15:42:21.345 | SUCCESS  | module.name:24 - הפעולה בוצעה בהצלחה!\n2023-10-09 15:42:22.678 | CRITICAL | module.name:27 - שגיאה חמורה\n```\n\n### התאמה אישית\n\nניתן להתאים את מערכת הלוגים על ידי עריכת הקובץ `tools/logger.py`:\n- הוספת/הסרת emojis\n- שינוי צבעים\n- שינוי פורמט ההודעה\n- הוספת שדות מידע נוספים\n\n## 🔧 תכונות מתקדמות\n\n### מערכת מטמון\n- **מטמון מתמיד**: נתונים נשמרים לאחר הפעלה מחדש של הבוט\n- **תמיכה ב-TTL**: תפוגה אוטומטית של נתוני מטמון\n- **סילוק LRU**: ניקוי אוטומטי של רשומות ישנות\n- **עמיד בפני threads**: בטוח לגישה מקבילית\n\n### מודלי מסד נתונים\n- **משתמשים**: ניהול משתמשים עם העדפות\n- **צ'אטים**: מידע על צ'אטים והגדרות\n- **ניתן להרחבה**: קל להוסיף מודלים חדשים\n\n### טיפול שגיאות\n- **שמירת זמינות**: הבוט ממשיך לפעול למרות שגיאות\n- **משוב למשתמש**: הודעות שגיאה ברורות למשתמשים\n- **תמיכה בדיבוג**: לוג שגיאות מפורט\n\n## 🤝 תרומה\n\n1. Fork את המאגר\n2. צור ענף תכונה: `git checkout -b feature/amazing-feature`\n3. commit את השינויים שלך: `git commit -m 'Add amazing feature'`\n4. Push לענף: `git push origin feature/amazing-feature`\n5. פתח Pull Request\n\n## 📝 רישיון\n\nפרויקט זה הוא קוד פתוח וזמין תחת [רישיון MIT](LICENSE).\n\n## 🙏 תודות\n\n- [Pyrogram](https://github.com/TelegramPlayGround/Pyrogram) - לקוח טלגרם מודרני ב-Python\n- [SQLAlchemy](https://www.sqlalchemy.org/) - toolkit למסדי נתונים\n- [python-dotenv](https://github.com/theskumar/python-dotenv) - ניהול משתני סביבה\n\n## 📞 תמיכה\n\nאם יש לך שאלות או צריך עזרה:\n- צור issue ב-GitHub\n- בדוק את [תיעוד Pyrogram](https://telegramplayground.github.io/pyrogram)\n\n## 🌍 גרסאות שפה\n\n- [עברית README](README.md) - גרסה בעברית (זו)\n- [English README](README_EN.md) - גרסה באנגלית\n\n---\n\n⭐ **תן כוכב למאגר אם הוא עזר לך!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudo-py-dev%2Ftelegram-bot-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsudo-py-dev%2Ftelegram-bot-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudo-py-dev%2Ftelegram-bot-template/lists"}