XauBot/docs/arsitektur-ai/12-Telegram-Notifications.md

Telegram Notifications — Sistem Notifikasi Real-Time

File: src/telegram_notifier.py Class: TelegramNotifier API: Telegram Bot API (async via aiohttp)

---

Arsitektur Notifikasi

flowchart LR
    A["Event\n(Trade / Alert / Timer)"] --> B["TelegramNotifier\n(async aiohttp)"]
    B --> C["Telegram Bot API\n(/sendMessage\n/sendPhoto\n/sendDocument)"]
    C --> D["User / Grup Telegram"]

    style A fill:#2d2d2d,stroke:#f5a623,color:#fff
    style B fill:#2d2d2d,stroke:#4a9eff,color:#fff
    style C fill:#2d2d2d,stroke:#50c878,color:#fff
    style D fill:#2d2d2d,stroke:#ff6b6b,color:#fff

flowchart TD
    LOOP["Main Loop\n(setiap 1 detik)"] --> NEW_DAY{"New day?"}
    NEW_DAY -- Ya --> DAILY["Daily Summary + Reset"]
    NEW_DAY -- Tidak --> HOURLY{"Hourly timer?"}
    HOURLY -- Ya --> HOUR_MSG["Hourly Analysis"]
    HOURLY -- Tidak --> HALF{"30-min timer?"}
    HALF -- Ya --> MARKET["Market Update"]
    HALF -- Tidak --> TRADE{"Trade executed?"}
    TRADE -- Ya --> OPEN["Trade Open Notification"]
    TRADE -- Tidak --> CLOSE{"Position closed?"}
    CLOSE -- Ya --> CLOSE_MSG["Trade Close Notification"]
    CLOSE -- Tidak --> LIMIT{"Limit hit?"}
    LIMIT -- Ya --> CRIT["Critical Limit Alert"]
    LIMIT -- Tidak --> FLASH{"Flash crash?"}
    FLASH -- Ya --> EMERG["Emergency Close Alert"]
    FLASH -- Tidak --> LOOP

    style LOOP fill:#1a1a2e,stroke:#4a9eff,color:#fff
    style DAILY fill:#1a1a2e,stroke:#50c878,color:#fff
    style HOUR_MSG fill:#1a1a2e,stroke:#50c878,color:#fff
    style MARKET fill:#1a1a2e,stroke:#50c878,color:#fff
    style OPEN fill:#1a1a2e,stroke:#f5a623,color:#fff
    style CLOSE_MSG fill:#1a1a2e,stroke:#f5a623,color:#fff
    style CRIT fill:#1a1a2e,stroke:#ff6b6b,color:#fff
    style EMERG fill:#1a1a2e,stroke:#ff6b6b,color:#fff

---

Apa Itu Telegram Notifications?

Telegram Notifications mengirimkan laporan real-time ke grup Telegram setiap kali terjadi event penting — trade dibuka/ditutup, laporan harian, alert darurat, dan status sistem.

Analogi: Telegram Notifications seperti dashboard pilot di cockpit — menampilkan semua informasi penting secara real-time tanpa harus melihat layar trading.

---

Konfigurasi

Bot Token:  Dari environment variable TELEGRAM_BOT_TOKEN
Chat ID:    Dari environment variable TELEGRAM_CHAT_ID
Format:     HTML (parse_mode)
Transport:  Async HTTP POST via aiohttp
Timezone:   WIB (Asia/Jakarta)

# Inisialisasi
from dotenv import load_dotenv
load_dotenv()

bot_token = os.getenv("TELEGRAM_BOT_TOKEN")
chat_id = os.getenv("TELEGRAM_CHAT_ID")
enabled = bool(bot_token and chat_id)  # Auto-disable jika tidak dikonfigurasi

---

11 Tipe Notifikasi

#	Tipe	Trigger	Frekuensi
1	Trade Open	Order berhasil dieksekusi	Per trade
2	Trade Close	Posisi ditutup	Per trade
3	Market Update	Timer 30 menit	Setiap 30 menit
4	Hourly Analysis	Timer 1 jam	Setiap 1 jam
5	Daily Summary	Pergantian hari	1x per hari
6	Startup	Bot dinyalakan	1x per sesi
7	Shutdown	Bot dimatikan	1x per sesi
8	News Alert	Event ekonomi terdeteksi	Per event
9	Critical Limit	Daily/total loss limit	Per event
10	Emergency Close	Flash crash / darurat	Per event
11	System Status	Status berkala	Per request

---

Format Pesan

1. Trade Open

🟢 LONG #123456
├ XAUUSD
├ Entry: 4950.00
├ Lot: 0.02
├ SL: 4937.00 (-$13)
├ TP: 4976.00 (+$26)
├ R:R: 1:2.0
├ AI: 75% | medium_volatility
└ SMC Bullish BOS + FVG
⏰ 14:35 WIB

Elemen	Arti
🟢/🔴	BUY (hijau) / SELL (merah)
LONG/SHORT	Arah posisi
#123456	Ticket ID dari broker
R:R	Risk to Reward ratio
AI: 75%	ML confidence
medium_volatility	HMM regime

---

2. Trade Close

✅ WIN #123456
├ XAUUSD BUY
├ Entry: 4950.00
├ Exit: 4965.00
├ Lot: 0.02
├ P/L: +$30.00 (+0.49%)
├ Pips: +150.0
├ Duration: 2m
├ Bal Before: $6130.00
└ Bal After: $6160.00
⏰ 14:40 WIB

Emoji	Arti
✅	WIN (profit)
❌	LOSS (rugi)
➖	BREAKEVEN (impas)

---

3. Market Update (Setiap 30 Menit)

📊 XAUUSD $4965.00
├ 🟢 BUY 75%
├ UPTREND
├ medium_volatility
├ London-NY Overlap
└ ✅
⏰ 14:45

---

4. Hourly Analysis (Setiap 1 Jam)

📊 HOURLY 14:00 WIB

Account
├ Bal: $5,094.68
├ Eq: $5,120.50
├ Float: +$25.82
└ Day: +$150.00 (12 trades)

Positions (2)
├ #123456 BUY: +$30.00 M:+45
└ #123457 SELL: -$15.00 M:-20

Market
├ XAUUSD $4,965.00
├ London-NY Overlap
└ medium_volatility | high

AI Signal
├ BUY 75% / thresh 70%
└ Quality: EXCELLENT (score:85) → READY

Risk NORMAL
└ Daily Loss: $0.00 / $148.34

✅ News: SAFE

---

5. Daily Summary

🎉 DAILY REPORT 2025-02-06

Result
├ P/L: +$150.00 (+3.03%)
├ Gross Win: +$500.00
├ Gross Loss: -$350.00
├ Bal Start: $4,944.68
└ Bal End: $5,094.68

Stats
├ Total: 12 trades
├ Wins: 8 | Losses: 4
├ Win Rate: 66.7%
├ Profit Factor: 1.43
└ Avg/Trade: $12.50

Recent Trades
├ ✅ BUY: +$30.00
├ ❌ SELL: -$25.00
├ ✅ BUY: +$45.00
├ ➖ SELL: $0.00
└ ✅ BUY: +$100.00

Emoji Hari	Arti
🎉	Hari profit
📉	Hari loss
➖	Hari breakeven

---

6. Startup

🚀 BOT STARTED

Config
├ Symbol: XAUUSD
├ Mode: small
├ Capital: $5,000.00
├ Balance: $4,944.68
└ ML: Loaded (37 features)

Risk Settings
├ Risk/Trade: 1%
├ Max Daily Loss: 5%
├ Max Total Loss: 10%
└ SL: Smart (ATR-based)

✅ News: SAFE
⏰ 2025-02-06 08:15 WIB

---

7. Shutdown

🔴 BOT STOPPED

Session Summary
├ Balance: $5,094.68
├ Total Trades: 12
├ ✅ P/L: +$150.00
└ Uptime: 8.5h

⏰ 2025-02-06 16:45 WIB

---

8. News Alert

🚨 NEWS DANGER_NEWS
├ NFP (Non-Farm Payroll) - HIGH IMPACT
├ High volatility expected during release
└ Buffer: 60m
⏰ 20:25

Emoji	Kondisi
🚨	DANGER_NEWS
⚠️	CAUTION / DANGER_SENTIMENT
✅	SAFE

---

9. Critical Limit Alert

🚨 DAILY LOSS LIMIT REACHED 🚨

Daily Loss: $250.00
Limit: $250.00 (5%)

⛔ TRADING STOPPED FOR TODAY
Will resume tomorrow automatically.

---

10. Emergency Close

🚨 EMERGENCY CLOSE COMPLETE

Closed 3 positions due to flash crash detection
Total P/L: -$45.00

---

11. Alert (Berbagai Tipe)

Alert Type	Emoji	Contoh
flash_crash	🚨	"Flash crash detected on XAUUSD"
high_volatility	⚡	"Volatility spike detected"
connection_error	📡	"MT5 connection lost"
model_retrain	🔄	"ML model retrained successfully"
market_close	🔔	"Market closing in 30 minutes"
low_balance	💰	"Account balance below threshold"

---

3 Metode Pengiriman

flowchart LR
    N["TelegramNotifier"] --> SM["send_message()\n/sendMessage\nTeks biasa"]
    N --> SP["send_photo()\n/sendPhoto\nChart / grafik"]
    N --> SD["send_document()\n/sendDocument\nFile PDF"]

    style N fill:#2d2d2d,stroke:#4a9eff,color:#fff
    style SM fill:#2d2d2d,stroke:#50c878,color:#fff
    style SP fill:#2d2d2d,stroke:#f5a623,color:#fff
    style SD fill:#2d2d2d,stroke:#ff6b6b,color:#fff

Metode	Endpoint	Kegunaan
send_message()	/sendMessage	Teks biasa (semua notifikasi)
send_photo()	/sendPhoto	Chart/grafik (daily report)
send_document()	/sendDocument	File PDF (laporan detail)

---

Error Handling

flowchart TD
    SEND["send_message() / send_photo()"] --> TRY{"Try-Except"}
    TRY -- Berhasil --> CHECK{"HTTP Status\n== 200?"}
    CHECK -- Ya --> OK["Return True\n(Terkirim)"]
    CHECK -- Tidak --> LOG_ERR["Log Error\nReturn False"]
    TRY -- Exception --> LOG_WARN["Log Warning\nLanjut Trading"]

    DISABLED{"Token / ChatID\nkosong?"} --> AUTO["Auto-disable\nReturn True"]

    EMERG["Emergency Close"] --> CLOSE_POS["Tutup Posisi Dulu"]
    CLOSE_POS --> TRY_NOTIF{"Kirim Notifikasi"}
    TRY_NOTIF -- Gagal --> IGNORE["pass\n(Trading > Notifikasi)"]
    TRY_NOTIF -- Berhasil --> OK2["Notifikasi Terkirim"]

    style SEND fill:#1a1a2e,stroke:#4a9eff,color:#fff
    style OK fill:#1a1a2e,stroke:#50c878,color:#fff
    style OK2 fill:#1a1a2e,stroke:#50c878,color:#fff
    style LOG_ERR fill:#1a1a2e,stroke:#ff6b6b,color:#fff
    style LOG_WARN fill:#1a1a2e,stroke:#f5a623,color:#fff
    style IGNORE fill:#1a1a2e,stroke:#f5a623,color:#fff
    style AUTO fill:#1a1a2e,stroke:#888,color:#fff

Strategi: GRACEFUL DEGRADATION

1. Try-Except di setiap send method
   -> Gagal kirim? Log warning, lanjut trading

2. HTTP status check
   -> Status != 200? Log error, return False

3. Emergency close
   -> Telegram gagal? TETAP tutup posisi
   -> Trading > notifikasi dalam prioritas

4. Disabled mode
   -> Token/ChatID kosong? Auto-disable, return True
   -> Bot tetap berjalan tanpa notifikasi

Strategi ini menerapkan pola graceful degradation — kegagalan notifikasi tidak pernah menghentikan proses trading. Sistem emergency close akan tetap menutup posisi meskipun Telegram tidak responsif, menerapkan prinsip circuit breaker di mana komponen non-kritis diisolasi dari jalur kritis.

# Contoh: Emergency close TIDAK boleh gagal karena Telegram
try:
    await telegram.send_message("Emergency close...")
except:
    pass  # Jangan biarkan Telegram failure menghentikan close

---

Rate Limiting

Notifikasi	Interval
Trade Open/Close	Langsung (per event)
Market Update	30 menit
Hourly Analysis	1 jam
Daily Summary	1x per hari
Startup / Shutdown	1x per sesi
Min message interval	1 detik (variable)

Rate limiting mencegah flooding ke Telegram Bot API yang memiliki batas ~30 pesan/detik per grup. Interval minimum 1 detik antar pesan menjaga bot tetap dalam batas aman.

---

Kapan Notifikasi Dikirim di Main Loop

Main Loop (setiap 1 detik)
    |
    |-- Cek new day? ------> Daily Summary + Reset
    |
    |-- Cek hourly timer? -> Hourly Analysis (setiap 1 jam)
    |
    |-- Cek 30min timer? --> Market Update (setiap 30 menit)
    |
    |-- Trade executed? ---> Trade Open notification
    |
    |-- Position closed? --> Trade Close notification
    |
    |-- Limit hit? --------> Critical Limit Alert
    |
    |-- Flash crash? ------> Emergency Close Alert
    |
    |-- (startup) ---------> Startup message
    |
    |-- (shutdown) --------> Shutdown message

---

Formatting HTML

Semua pesan menggunakan HTML parse mode:

<b>Bold</b>           -> Label penting
<code>Monospace</code> -> Angka, harga, nilai
<i>Italic</i>          -> Info tambahan, alasan signal

Tree structure menggunakan box-drawing characters:

├  -> Item tengah
└  -> Item terakhir