Skip to content

TELEGRAM_BOT_GUIDE.he.md

Latest commit

 

History

History
350 lines (258 loc) · 11.8 KB

TELEGRAM_BOT_GUIDE.he.md

File metadata and controls

350 lines (258 loc) · 11.8 KB
Raw

מדריך אינטגרציה של בוט טלגרם

סקירה

מבט כלכלי כולל בוט טלגרם מלא שמאפשר:

  • 📬 קבלת התראות על סורקי עסקאות
  • 💬 שיחה עם AI על עסקאות פיננסיות
  • 🏦 הפעלת סורקים ישירות מטלגרם
  • ⚙️ ניהול הגדרות דרך פקודות בצ'אט

התחלה מהירה

1. יצירת בוט בטלגרם

  1. פתחו את טלגרם וחפשו @BotFather
  2. שלחו את הפקודה /newbot
  3. עקבו אחר ההנחיות לתת שם לבוט
  4. BotFather יספק את טוקן הבוט (למשל 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. הגדרת טוקן הבוט

אפשרות א׳: משתני סביבה (.env)

הוסיפו לקובץ .env:

TELEGRAM_BOT_TOKEN=your_bot_token_here

אפשרות ב׳: דרך הממשק

  1. עברו ל־הגדרות → לשונית Telegram
  2. הדביקו את טוקן הבוט בשדה "Bot Token"
  3. לחצו שמור
  4. לחצו התחל כדי להפעיל את הבוט

3. קבלת מזהה צ'אט (Chat ID)

כדי לקבל התראות או להשתמש בבוט, נדרש מזהה הצ'אט בטלגרם:

בצ'אט פרטי:

  1. התחילו צ'אט עם הבוט (חיפוש בשם הבוט)
  2. שלחו כל הודעה לבוט (למשל /start)
  3. בצ'אט פרטי, מזהה הצ'אט הוא אותו מספר כמו מזהה המשתמש בטלגרם.

אם עדיין אין הרשאה (השרת משתמש ברשימת allowedUsers והחשבון שלכם לא ברשימה): שלחו בכל זאת הודעה לבוט. תקבלו תשובה בסגנון "גישה נדחית" שעדיין כוללת את מזהה המשתמש שלכם כמספר להעתקה — שלחו אותו למנהל כדי שיוסיף אתכם ל־allowedUsers ולצ'אטי התראות לפי הצורך.

חלופה — API getUpdates:

  1. אחרי שליחת הודעה לבוט, פתחו: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  2. חפשו "chat": {"id": <YOUR_CHAT_ID>} או "from": {"id": ...} עבור השולח
  3. העתיקו את מספר מזהה הצ'אט

בקבוצות:

  1. הוסיפו את הבוט לקבוצת טלגרם
  2. שלחו הודעה שמזכירה את הבוט: @your_bot_name שלום
  3. באותה שיטה מזהים את מזהה הצ'אט של הקבוצה (מתחיל ב־-)

תכונות ופקודות

פקודות זמינות

פקודה תיאור שימוש
/start אתחול הבוט והודעת פתיחה בצ'אט פרטי עם הבוט
/help הצגת כל הפקודות בכל צ'אט
/scrape בחירה והרצת סורק בחירת פרופיל מכפתורים
/chat מצב שיחה עם AI שאלות על עסקאות
/settings ניהול העדפות התראות תפריט אינטראקטיבי
/subscribe הפעלת התראות על עסקאות התראות לסריקות חדשות
/unsubscribe כיבוי התראות בלי התראות
/status בדיקת סטטוס הבוט והמערכת האם הבוט פעיל

שימוש בצ'אט AI

אתה: /chat
בוט: 💬 מצב צ'אט AI הופעל!

אתה: מה ההוצאות הגדולות שלי?
בוט: לפי העסקאות שלך, קטגוריות ההוצאה הגדולות ביותר הן...

אתה: הצג מגמות הוצאה
בוט: [ניתוח מפורט של דפוסי הוצאה]

הרצת סורקים

אתה: /scrape
בוט: 🏦 בחר פרופיל לסריקה:
     [בנק לאומי] [בנק הפועלים] [אחר]

אתה: לחיצה על הבנק הרצוי
בוט: ⏳ מריץ סורק, נא להמתין...
     ✅ הסריקה הושלמה בהצלחה
     
     📊 תוצאות:
     • חשבונות: 3
     • עסקאות: 487
     • משך: 2350ms

הגדרת צ'אטים להתראות

הוספת צ'אט להתראות

  1. עברו ל־הגדרות → Telegram → צ'אטים להתראות
  2. הזינו את מזהה הצ'אט שאמור לקבל התראות
  3. לחצו הוסף

אירועי התראות

הבוט שולח התראות כאשר:

  • סריקה הסתיימה בהצלחה ✅
  • סריקה נכשלה ❌
  • נותחו עסקאות עם תובנות AI
  • צינור (pipeline) הסתיים
  • התרעות מערכת

רמות פירוט התראות

ניתן להגדיר כמה מפורטות ההתראות:

  • מינימלי: סטטוס ומשך בלבד
  • רגיל: סטטוס, משך, שלבים, מספר עסקאות, תובנות
  • מפורט: מידע מלא כולל פרטי חשבון ויתרה
  • מפורט מאוד: JSON מלא למשתמשים מתקדמים

לוח הגדרות Telegram

גישה להגדרות מהממשק:

  1. עברו ל־הגדרות → לשונית Telegram
  2. ניתן להגדיר:
    • טוקן בוט (מוסתר לחלקית)
    • צ'אטים להתראות (הוספה/הסרה של מזהי צ'אט)
    • בדיקת חיבור
    • הגדרות מתקדמות

בדיקת חיבור

לאימות ההגדרות:

  1. הזינו את טוקן הבוט
  2. הזינו את מזהה הצ'אט
  3. לחצו בדיקה
  4. אמורה להגיע הודעת אישור בטלגרם

נקודות קצה API (REST)

התכונה חושפת את נקודות ה־API הבאות (נתיבים כפי שמופיעים בשרת):

הגדרות

# קבלת הגדרות טלגרם
GET /api/telegram/config

# עדכון הגדרות
POST /api/telegram/config
{
  "botToken": "...",
  "adminChatIds": ["123456"],
  "notificationChatIds": ["123456", "-789012"]
}

בקרת בוט

# הפעלת הבוט
POST /api/telegram/start
{
  "botToken": "optional_token_to_override_config"
}

# עצירת הבוט
POST /api/telegram/stop

# סטטוס הבוט
GET /api/telegram/status

# בדיקת חיבור
POST /api/telegram/test
{
  "botToken": "...",
  "chatId": "..."
}

צ'אטים להתראות

# רשימת כל צ'אטי ההתראות
GET /api/telegram/notification-chats

# הוספת צ'אט להתראות
POST /api/telegram/notification-chat/add
{
  "chatId": "123456"
}

# הסרת צ'אט מהתראות
POST /api/telegram/notification-chat/remove
{
  "chatId": "123456"
}

תכונות מתקדמות

ריבוי שפות

ממשק הבוט מזהה את שפת הממשק באינטרנט:

  • 🇺🇸 אנגלית
  • 🇮🇱 עברית

כפתורים מובנים (Inline)

הבוט משתמש בכפתורי טלגרם:

  • בחירת פרופיל לסריקה
  • מתגי הגדרות
  • ניווט בתפריטים

הודעות ארוכות

אם תשובות AI חורגות ממגבלת 4096 תווים של טלגרם, הן מפוצלות אוטומטית.

תבניות הודעות

התראות משתמשות ב־HTML:

  • טקסט מודגש לכותרות
  • קוד למזהים
  • אימוג'י ✅/❌ לסטטוס

פתרון בעיות

הבוט לא מגיב

  1. ודאו שטוקן הבוט נכון
  2. ודאו שהבוט הופעל: הגדרות → Telegram → כפתור התחל
  3. ודאו ששלחתם /start לבוט בטלגרם
  4. בדקו יומני שרת: הגדרות → תחזוקה → יומנים

לא מתקבלות התראות

  1. ודאו שמזהה הצ'אט נכון
  2. בדקו שהצ'אט ברשימת ההתראות: הגדרות → Telegram → צ'אטים להתראות
  3. הריצו בדיקת חיבור עם מזהה הצ'אט
  4. ודאו שסטטוס הבוט "פעיל" (אינדיקטור ירוק)

לא מצליחים למצוא Chat ID

  1. שלחו הודעה לבוט, ואז: https://api.telegram.org/bot<TOKEN>/getUpdates
  2. בקבוצות: הוסיפו את הבוט וציינו אותו — @botname שלום
  3. חפשו "chat": {"id": <מספר>}

שגיאות בממשק

  • "Bot token not provided": הוסיפו טוקן ושמרו
  • "Telegram API error": ייתכן שהטוקן שגוי — אמתו עם @BotFather
  • "Failed to add chat": ייתכן שפורמט מזהה הצ'אט שגוי (מספרים לפרטי, קידומת - לקבוצות)

אבטחה

  1. הגנת טוקן הבוט:

    • אל תשתפו את הטוקן בפומבי
    • בממשק הטוקן מוסתר (***...10 תווים אחרונים)
    • אם דלף — צרו טוקן חדש ב־@BotFather

  2. פרטיות מזהה צ'אט:

    • שמרו כמו סיסמאות
    • הוסיפו רק צ'אטים מהימנים
    • הסירו מזהים ישנים

  3. צ'אטי מנהל:

    • הרשאות ברמת מנהל
    • רק מנהלים מריצים פקודות רגישות
    • שקלו קבוצה פרטית להתראות מנהלים

  4. הצפנה (מה זה לא):

    • טוקן הבוט והגדרות Telegram נשמרים כמו שאר הקונפיגורציה (JSON תחת תיקיית הנתונים). הם לא עטופים באותה שכבת AES-256-GCM כמו פרטי התחברות לבנק בפרופילים שמורים (אלה מוצפנים במפתח שמופק מסיסמת נעילת האפליקציה).
    • התייחסו לטוקן כסוד: הגבילו גישה ל-DATA_DIR, הרשאות מערכת הפעלה והצפנת דיסק לפי הצורך — כמו למפתחות API ול-runtime-settings.json.

דוגמאות

דוגמה 1: סיכום הוצאות שבועי

אתה: /chat
אתה: תוכל לסכם את ההוצאות השבוע לפי קטגוריה?
בוט: 📊 סיכום הוצאות שבועי:
     💰 סה"כ: ₪4,250
     - מכולת: ₪800
     - תחבורה: ₪300
     - בילויים: ₪450
     - חשבונות: ₪200
     ... פירוט ...

דוגמה 2: הרצת סורק מתוזמנת

1. הגדרת סורק חודשי בהגדרות צינור (Pipeline)
2. הוספת צ'אט התראות בהגדרות טלגרם
3. כשהצינור רץ:
   - הבוט שולח: "📬 הצינור התחיל"
   - אחרי סיום: "✅ סריקה הושלמה - 487 עסקאות"
   - תובנות AI נכללות אוטומטית

דוגמה 3: ניתוח פיננסי

אתה: /chat
אתה: האם ההוצאות שלי עלו החודש?
בוט: 📈 כן, ההוצאה עלתה בכ־12% לעומת החודש הקודם
     
     גורמים עיקריים:
     • נסיעות: +₪450
     • מסעדות: +₪280
     • קניות: +₪150
     
     בתוך תקציב:
     ✅ מכולת
     ✅ חשבונות

מגבלות ונושאים ידועים

  1. מגבלת קצב הודעות: לטלגרם יש הגבלות (הימנעו מ־25+ הודעות/שנייה)
  2. העלאת קבצים: כרגע אין תמיכה בהעלאת קבצים לבוט
  3. מדיה: עסקאות מוצגות כטקסט בלבד (אין גרפים בתוך טלגרם עדיין)
  4. הרשאות בקבוצות: ודאו שלבוט יש הרשאות מתאימות

שיפורים עתידיים

תכנון לגרסאות עתידיות:

  • 📊 גרפי עסקאות אינטראקטיביים
  • 📝 ייצוא נתונים לקבצים
  • 🔔 התראות חכמות (שינויים מהותיים בלבד)
  • 🌙 דוחות מתוזמנים
  • 👥 תמיכה בריבוי משתמשים עם תפקידים
  • 🔄 סנכרון Google Sheets דרך טלגרם

תמיכה

לבעיות או בקשות לתכונות:

  1. עברו על סעיף פתרון הבעיות למעלה
  2. בדקו יומני שרת ב־הגדרות → יומנים
  3. השתמשו ב־בדיקת חיבור
  4. דווחו עם הודעות שגיאה מפורטות