[FEATURE] Alerting: Push notifications via email, Telegram & webhooks

[farcomiot]

🔔 Alerting: Push Notifications via Email, Telegram & Webhooks

Problem

Currently, environmental alerts are only visible on the web dashboard. If the user is away from the dashboard, critical events (high PM2.5, noise violations, temperature spikes) go unnoticed until manually checked.

Goal

Implement a multi-channel notification system that pushes real-time alerts when sensor readings exceed configurable thresholds.

Proposed Notification Channels

1. Telegram Bot (Priority — free, instant, mobile)

• Create Telegram bot via @Botfather
• Bot token management — store in .env file (see [SECURITY] Pi hardening: firewall, fail2ban, SSH keys #3)
• Chat ID registration — /start command stores user chat ID
• Alert messages with sensor emoji, value, threshold, and timestamp
• Daily digest — summary of all alerts at configurable time
• Command interface — /status, /silence 1h, /thresholds

2. Email Alerts (SMTP)

• SMTP configuration — Gmail app password or SendGrid free tier
• HTML email templates — styled alert cards with sensor data
• Digest mode — batch alerts into hourly/daily summaries to avoid spam
• Configurable recipients — multiple email addresses

3. Webhook Integration

• Generic webhook POST — JSON payload to configurable URL
• IFTTT integration — trigger applets for smart home actions
• Slack webhook — post to channel (future team monitoring)
• Home Assistant — REST API integration for automation triggers

Alert Logic (Pi-Side)

# Alert configuration structure
ALERT_CONFIG = {
    'pm25': {'warn': 35.5, 'critical': 55.5, 'cooldown': 300},
    'pm10': {'warn': 155, 'critical': 255, 'cooldown': 300},
    'temperature': {'warn': 35, 'critical': 40, 'cooldown': 600},
    'humidity': {'warn': 70, 'critical': 85, 'cooldown': 600},
    'noise': {'warn': 85, 'critical': 100, 'cooldown': 60},
    'oxidised': {'warn': 20, 'critical': 30, 'cooldown': 300},
}

# Cooldown tracking — prevent alert floods
last_alert = {}  # {sensor: timestamp}

Implementation Phases

Phase 1: Telegram bot (simplest, most useful)

• Pi script sends alerts directly via requests.post() to Telegram Bot API
• No server infrastructure needed
• Instant mobile notifications

Phase 2: Email alerts

• Add SMTP module to Pi script
• HTML templates with inline CSS
• Configurable digest intervals

Phase 3: Webhook system

• Generic webhook dispatcher
• Plugin architecture for different services
• Dashboard webhook configuration UI

Architecture

Pi Script → Threshold Check → Alert Queue → Dispatcher
                                              ├── Telegram Bot API
                                              ├── SMTP (Gmail/SendGrid)
                                              └── Webhook POST

Configuration File (.env)

TELEGRAM_BOT_TOKEN=<token>
TELEGRAM_CHAT_IDS=<id1>,<id2>
SMTP_HOST=smtp.gmail.com
SMTP_USER=alerts@farcomindustrial.com
SMTP_PASS=<app-password>
ALERT_EMAIL_TO=aaron@farcomindustrial.com
WEBHOOK_URL=https://hooks.slack.com/...

Dependencies

• python-telegram-bot or raw requests for Telegram API
• smtplib (built-in Python) for email
• requests for webhooks
• .env file parser (python-dotenv)

Security Considerations

• All tokens/passwords in .env file, never in code
• Rate limiting on alert dispatch (cooldown per sensor)
• Telegram bot restricted to registered chat IDs only
• SMTP credentials via app passwords, not main account password

---

Ref: #1 Roadmap — Alerting & Notifications