# How to Configure Telegram Notifications for Alerts in Multi-Cam Face Tracker

> Configure Telegram notifications for multi-cam face tracker alerts. Enable real-time detection alerts with your bot token and chat ID in config yaml. Learn how now.

- Repository: [AarambhDevHub/multi-cam-face-tracker](https://github.com/aarambhdevhub/multi-cam-face-tracker)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Enable Telegram alerts by setting `enabled: true` in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) with your bot token and chat ID, then restart the application to receive real-time detection alerts.**

The Multi-Cam Face Tracker includes a built-in alert system that integrates with Telegram to deliver instant notifications when faces are detected across multiple camera feeds. By configuring the Telegram settings in the YAML configuration file, you can receive text alerts and image snapshots directly on your mobile device without modifying any Python code.

## Configuration File Setup

All Telegram notification settings are centralized in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml). The `telegram:` block controls whether alerts are enabled, authenticates your bot, and sets rate-limiting behavior to prevent spam.

### Required Configuration Values

Open [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) and locate the `telegram:` block (around lines 21–24). Update the following fields:

```yaml
telegram:
  enabled: true                # set to false to disable Telegram alerts

  bot_token: "YOUR_BOT_TOKEN"  # token obtained from @BotFather

  chat_id: "YOUR_CHAT_ID"      # your Telegram chat ID (obtain via @getidsbot)

  rate_limit: 10               # minimum seconds between consecutive messages

```

*Source:* [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) – see the `telegram:` block around lines 21‑24.

## Core Components

The Telegram integration relies on two Python modules that handle the bot lifecycle and alert triggering.

### Telegram Manager ([`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py))

The `TelegramManager` class wraps the `python-telegram-bot` API to handle asynchronous initialization, rate-limiting, and graceful shutdown.

Key implementation details from [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py):

- **Initialization** (lines 10–16): Stores `self.token`, `self.chat_id`, and `self.min_interval` (derived from the `rate_limit` config value).
- **Rate Limiting**: The `send_alert` method checks the timestamp of the last message to enforce the minimum interval between alerts.
- **Message Delivery** (lines 28–63): The `send_alert(message, image_path)` method sends a photo using `bot.send_photo` if an image path is provided; otherwise, it sends a plain text message via `bot.send_message`. Errors are logged and optionally persisted to `failed_alerts.log`.
- **Shutdown**: The `shutdown()` method cleans up the event loop and pending tasks.

*Source:* Class definition starts at line 9; initialization code at lines 10‑16 and the `send_alert` implementation at lines 28‑63.

### Alert System Integration ([`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py))

The `AlertSystem` class decides when an alert should be emitted and forwards it to `TelegramManager` if Telegram alerts are enabled.

Important flow from [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py):

- **Conditional Initialization** (lines 38–42): During construction, the system reads `config['telegram']`. If `enabled` is true, it creates a `TelegramManager` instance with the token, chat ID, and rate-limit values.
- **Alert Triggering** (line 92): When a detection event occurs, `self.telegram.send_alert(...)` is called with the alert message and optional image path.
- **Graceful Shutdown** (lines 156–162): On shutdown, `self.telegram.shutdown()` cleans up the event loop and pending tasks.

*Source:* `AlertSystem` class definition begins at line 29; the conditional creation of `TelegramManager` and use of `send_alert` are highlighted in the grep output.

## Step-by-Step Configuration Guide

Follow these steps to configure Telegram notifications for alerts:

1. **Create a Telegram Bot**
   - Open Telegram and message `@BotFather`.
   - Use the `/newbot` command and follow the prompts.
   - Copy the **HTTP API token** provided (it looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`).

2. **Obtain Your Chat ID**
   - Message `@getidsbot` or `@userinfobot` in Telegram.
   - Copy the numeric **Chat ID** (usually a positive number for private chats, or a negative number for groups).

3. **Update the Configuration File**
   - Open [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) in your editor.
   - Set `telegram.enabled` to `true`.
   - Paste your bot token into `bot_token`.
   - Paste your chat ID into `chat_id`.
   - Adjust `rate_limit` to control message frequency (default is 10 seconds).

4. **Restart the Application**
   - Stop the Multi-Cam Face Tracker if it is running.
   - Start the application again to load the new configuration.
   - The `AlertSystem` will automatically instantiate `TelegramManager` and begin monitoring for detection events.

## Advanced Usage and Testing

### Standalone Testing

You can test the Telegram integration without running the full face tracker by invoking `TelegramManager` directly:

```python
from pathlib import Path
from core.telegram_manager import TelegramManager

# Initialise with credentials from config.yaml

tg = TelegramManager(
    token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    chat_id="987654321",
    rate_limit=5,
)

# Send a simple text alert

tg.send_alert("Test alert from Multi‑Cam Face Tracker")

# Send an alert with a photo (optional)

photo_path = Path("snapshot.jpg")
tg.send_alert("Alert with snapshot", image_path=photo_path)

# Clean up when the application exits

tg.shutdown()

```

### Understanding Rate Limiting

The `rate_limit` parameter in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) maps to `self.min_interval` in `TelegramManager`. This prevents notification spam when multiple faces are detected simultaneously. If an alert is triggered within the rate limit window, the system skips the message or queues it depending on the implementation in [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py) lines 28‑63.

## Summary

- **Configuration is YAML-based**: All Telegram settings live in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) under the `telegram:` block, requiring only `bot_token`, `chat_id`, and `enabled: true` to activate.
- **Modular architecture**: [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py) handles the bot lifecycle and rate-limiting, while [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) orchestrates when alerts are fired.
- **No code changes required**: Once the YAML file is updated and the application is restarted, the `AlertSystem` automatically instantiates the `TelegramManager` and begins pushing notifications.
- **Supports rich media**: Alerts can include text and optional image snapshots captured from camera feeds.
- **Rate limiting built-in**: The `rate_limit` parameter prevents spam by enforcing a minimum interval between consecutive messages.

## Frequently Asked Questions

### How do I find my Telegram chat ID?

Message `@getidsbot` or `@userinfobot` in Telegram and start a conversation. The bot will reply with your numeric Chat ID. For group chats, add the bot to the group first, then check the update payload or use a bot like `@RawDataBot` to reveal the negative group ID.

### Can I send alerts to multiple Telegram chats simultaneously?

The current implementation in [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py) stores a single `chat_id` during initialization. To support multiple chats, you would need to modify the `TelegramManager` class to accept a list of chat IDs and iterate through them in the `send_alert` method, or instantiate multiple `TelegramManager` instances in [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py).

### What happens if the Telegram API is unavailable?

If the Telegram API is unreachable when `send_alert` is called, the error is caught and logged. According to the implementation in [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py) lines 28‑63, failed alerts may be optionally persisted to `failed_alerts.log` for later review. The application continues running; the alert is simply dropped or logged depending on the specific exception handling in that file.

### How do I disable Telegram notifications temporarily?

Set `enabled: false` in the `telegram:` block of [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) and restart the application. When `enabled` is false, [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) skips the instantiation of `TelegramManager` (lines 38‑42), effectively disabling all Telegram notifications without removing your token or chat ID from the configuration file.