# How to Set Up Telegram Alerts for Security Events in LogSentinelAI

> Learn how to set up Telegram alerts for security events in LogSentinelAI quickly. Configure environment variables and receive real-time notifications for critical events. Improve your security monitoring now.

- Repository: [JungJungIn/logsentinelai](https://github.com/call518/logsentinelai)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/call518/logsentinelai/blob/main/core/elasticsearch.py) and [`utils/telegram_alert.py`](https://github.com/call518/logsentinelai/blob/main/utils/telegram_alert.py)—that determines when alerts fire.

## Prerequisites and Configuration

Before enabling Telegram alerts, you must obtain a bot token from [@BotFather](https://t.me/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:

```dotenv

# 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`](https://github.com/call518/logsentinelai/blob/main/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`](https://github.com/call518/logsentinelai/blob/main/utils/telegram_alert.py)** module provides the low-level async wrapper around the Telegram Bot API, while **[`core/elasticsearch.py`](https://github.com/call518/logsentinelai/blob/main/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`](https://github.com/call518/logsentinelai/blob/main/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:

```python
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`](https://github.com/call518/logsentinelai/blob/main/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`](https://github.com/call518/logsentinelai/blob/main/src/logsentinelai/utils/telegram_alert.py):

```python
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`](https://github.com/call518/logsentinelai/blob/main/telegram_alert.py)).

## Complete Configuration Example

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

```dotenv

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

# 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`](https://github.com/call518/logsentinelai/blob/main/core/elasticsearch.py).
- **Delivery**: The `send_telegram_alert()` function in [`utils/telegram_alert.py`](https://github.com/call518/logsentinelai/blob/main/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`](https://github.com/call518/logsentinelai/blob/main/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`](https://github.com/call518/logsentinelai/blob/main/core/config.py). To disable alerts, set `TELEGRAM_ENABLED=false` in your `.env` file and restart the LogSentinelAI process.