How to Set Up Telegram Alerts for Security Events in LogSentinelAI

To set up Telegram alerts in LogSentinelAI, configure the TELEGRAM_TOKEN, TELEGRAM_CHAT_ID, and TELEGRAM_ALERT_LEVEL environment variables in your .env file, then restart the service to enable real-time notifications when security events meet your severity threshold.

LogSentinelAI (repository: call518/logsentinelai) provides built-in integration with Telegram to push instant notifications when security events exceed a configured severity threshold or when log processing fails. This guide explains how to configure the alerting pipeline using environment variables and describes the internal logic—implemented in core/elasticsearch.py and utils/telegram_alert.py—that determines when alerts fire.

Prerequisites and Configuration

Before enabling Telegram alerts, you must obtain a bot token from @BotFather and identify the numeric chat ID of your target group or channel.

Create or edit a .env file in the repository root (or use /etc/logsentinelai.config for system-wide installations) with the following variables:

# Enable/disable Telegram integration

TELEGRAM_ENABLED=true

# Bot token from @BotFather

TELEGRAM_TOKEN=123456:ABCDEFghIJKlmnoPQRstuVWXyz

# Numeric chat identifier (group/channel)

TELEGRAM_CHAT_ID=-1001234567890

# Minimum severity to trigger alert: CRITICAL, HIGH, MEDIUM, LOW, INFO

TELEGRAM_ALERT_LEVEL=CRITICAL

When LogSentinelAI starts, core/config.py loads these values via apply_config() and caches them as module globals (TELEGRAM_ENABLED, TELEGRAM_TOKEN, TELEGRAM_CHAT_ID, TELEGRAM_ALERT_LEVEL) for use throughout the application.

How Telegram Alerts Work in LogSentinelAI

The alert workflow spans two core components. The utils/telegram_alert.py module provides the low-level async wrapper around the Telegram Bot API, while core/elasticsearch.py contains the decision logic that determines when to trigger an alert after processing each log chunk.

The Alert Decision Logic

After enriching a log chunk in send_to_elasticsearch_raw() (lines 79–103 of core/elasticsearch.py), the system evaluates whether to send a Telegram notification:

1. Check if enabled – The code verifies if TELEGRAM_ENABLED: before proceeding.
2. Map severity priorities – Events are ranked numerically (CRITICAL = 1, HIGH = 2, etc.) using get_severity_priority().
3. Evaluate events – The system collects events from enriched_data.get("events") and identifies any with priority less than or equal to the configured TELEGRAM_ALERT_LEVEL.
4. Check for failures – Alerts also fire if processing_result != "success", ensuring pipeline errors are not silent.
5. Trigger condition – The alert sends if has_alert_events or has_failure is true:

has_alert_events = len(alert_events) > 0
has_failure = processing_result != "success"
if has_alert_events or has_failure:
    # Build and send message

Message Formatting and Delivery

When triggered, the system assembles a human-readable message block in msg_lines (lines 31–78) containing:

• Alert type (e.g., CRITICAL+ EVENTS + PROCESSING FAILURE)
• Highest severity and immediate-attention flag
• Failure details (@error_type, @error_message) when applicable
• Statistics, sample event, and Elasticsearch/Kibana metadata

The message is truncated to 4,000 characters if it exceeds Telegram's limit (lines 78–81), then dispatched via send_telegram_alert(msg) (line 82). If the import of telegram_alert.py fails, the block fails silently to prevent pipeline interruption.

Sending Manual Telegram Alerts

For testing or custom integrations outside the standard log pipeline, import the helper directly from src/logsentinelai/utils/telegram_alert.py:

from logsentinelai.utils.telegram_alert import send_telegram_alert

alert_text = """
🚨 [MANUAL TEST] 🚨
• Highest Severity: CRITICAL
• Description: Unauthorized SSH login attempt detected
"""
send_telegram_alert(alert_text)

The helper automatically handles event loop management, creating an asynchronous Bot instance and managing the "already-running-loop" case (lines 22–55 of telegram_alert.py).

Complete Configuration Example

Here is a complete .env configuration that enables alerts for HIGH and CRITICAL events:

# -------------------------------------------------

# LogSentinelAI – Telegram integration configuration

# -------------------------------------------------

TELEGRAM_ENABLED=true
TELEGRAM_TOKEN=123456:ABCDEFghIJKlmnoPQRstuVWXyz
TELEGRAM_CHAT_ID=-1001234567890
TELEGRAM_ALERT_LEVEL=HIGH

After saving the file, start LogSentinelAI using python -m logsentinelai.cli. The real-time monitor streams log lines, and any processed chunk containing qualifying events automatically triggers a Telegram notification to your configured chat.

Summary

• Configuration: Set TELEGRAM_ENABLED, TELEGRAM_TOKEN, TELEGRAM_CHAT_ID, and TELEGRAM_ALERT_LEVEL in your environment or .env file.
• Trigger logic: Alerts fire when events match or exceed the configured severity level or when processing fails, as implemented in core/elasticsearch.py.
• Delivery: The send_telegram_alert() function in utils/telegram_alert.py handles async message delivery with automatic length capping at 4,000 characters.
• Manual usage: Import send_telegram_alert() directly to send custom notifications from scripts or REPL sessions.

Frequently Asked Questions

How do I find my Telegram chat ID?

Create a group, add your bot, and send a test message. Then visit https://api.telegram.org/bot<YourBOTToken>/getUpdates and look for the "chat":{"id": field. Group IDs typically start with -100 (e.g., -1001234567890).

What severity levels does LogSentinelAI support?

The system recognizes five levels in ascending order of urgency: INFO, LOW, MEDIUM, HIGH, and CRITICAL. Internally, these map to numeric priorities (1–5) in core/elasticsearch.py, where lower numbers indicate higher severity.

Will Telegram alerts work if Elasticsearch is down?

Yes. The alert decision logic in send_to_elasticsearch_raw() evaluates the processing_result variable. If Elasticsearch ingestion fails (processing_result != "success"), the system still attempts to send a Telegram notification containing the failure details before raising the exception.

Can I disable Telegram alerts without restarting the service?

No. The TELEGRAM_ENABLED flag and other configuration variables are loaded once at startup when apply_config() runs in core/config.py. To disable alerts, set TELEGRAM_ENABLED=false in your .env file and restart the LogSentinelAI process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}