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

Enable Telegram alerts by setting enabled: true in 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. 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 and locate the telegram: block (around lines 21–24). Update the following fields:

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 – 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)

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:

• 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)

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:

• 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 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:

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 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 lines 28‑63.

Summary

• Configuration is YAML-based: All Telegram settings live in config/config.yaml under the telegram: block, requiring only bot_token, chat_id, and enabled: true to activate.
• Modular architecture: core/telegram_manager.py handles the bot lifecycle and rate-limiting, while 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 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.

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 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 and restart the application. When enabled is false, 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.

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