Telegram Notifications Bot
Relevant source files
The following files were used as context for generating this wiki page:
The Telegram Notifications Bot module provides a high-level interface for integrating Telegram-based messaging into trading workflows. It acts as a wrapper around the python-telegram-bot library, enabling automated alerts, command-based interaction, and GIPHY integration. The module is designed to handle different versions of the underlying Telegram library (v13.x and v20+), providing both blocking and asynchronous execution patterns.
The bot serves as a bridge between the vectorbt analysis engine and the user, allowing for real-time notifications of strategy executions or portfolio status updates. It supports features like message persistence, chat migration handling, and broadcasting messages to all known users who have interacted with the bot.
Sources: vectorbt/messaging/telegram.py:1-13, vectorbt/messaging/init.py:1-18, README.md:25-27
Architecture and Versions
The module implements a dual-logic system to support both legacy and modern versions of python-telegram-bot. If version 20.0 or higher is detected, it uses the ApplicationBuilder and asynchronous event loops. For older versions, it utilizes the Updater and Dispatcher architecture.
Logic Flow for Bot Initialization
The following diagram illustrates the initialization process for the modern (v20+) implementation:
Component Breakdown
TelegramBot Class
The TelegramBot class is the primary interface. It inherits from Configured to allow for easy configuration and parameter serialization.
- Persistence: Automatically handles session persistence using
PicklePersistenceif a filepath is provided in the configuration. - Message Handling: Manages a registry of
chat_idsthat have interacted with the bot via the/startcommand. - GIPHY Integration: Integrates with the GIPHY API to convert text queries into GIF animations.
Key Messaging Methods
| Method | Description | Kind |
|---|---|---|
send | General purpose method to send any supported Telegram media/message. | Dynamic |
send_message | Sends a standard text message to a specific chat_id. | text |
send_to_all | Broadcasts a message/media of a specific kind to all registered chat_ids. | Dynamic |
send_giphy | Uses text_to_giphy_url to find and send a GIF based on text. | animation |
Sources: vectorbt/messaging/telegram.py:273-333
Handler System
The bot includes several built-in handlers to manage lifecycle and interaction:
- LogHandler: Intercepts updates to log user messages and activity to the standard logger.
- Start Callback: Triggered by
/start, it adds the user'schat_idto the internal registry and sends a greeting. - Migration Handler: Automatically detects when a group chat migrates to a supergroup, updating stored
chat_idsto prevent delivery failure.
Sources: vectorbt/messaging/telegram.py:61-81, vectorbt/messaging/telegram.py:355-364
Configuration and Settings
The bot is configured through the global vectorbt.settings object, specifically under the messaging.telegram and messaging.giphy keys.
# Default settings structure in vectorbt/_settings.py
messaging=dict(
telegram=Config(
dict(
token=None,
use_context=True,
persistence="telegram_bot.pickle",
defaults=Config(),
drop_pending_updates=True,
)
),
giphy=dict(api_key=None, weirdness=5),
)
Sources: vectorbt/_settings.py:440-452
Bot Execution Patterns
The bot can be started in two modes:
- Foreground (Blocking): The bot occupies the main thread and idles (in v13) or runs its event loop until interrupted.
- Background (Non-blocking): The bot runs in a separate
daemonthread, allowing the main program to continue executing strategy analysis while the bot handles alerts.
Integration with Global Settings
The bot leverages vectorbt.utils.config.merge_dicts to combine user-provided keyword arguments with project-wide defaults. It specifically resolves giphy_kwargs for the GIPHY translation endpoint and init_kwargs for the Telegram ApplicationBuilder or Updater.
| Parameter | Source | Description |
|---|---|---|
token | telegram_cfg | API token provided by BotFather. |
persistence | telegram_cfg | String path or Object for data persistence. |
weirdness | giphy_cfg | Value between 0-10 for GIPHY search results. |
Sources: vectorbt/messaging/telegram.py:91-118, vectorbt/_settings.py:452
Summary
The Telegram Notifications Bot is a robust wrapper that simplifies the complexity of the python-telegram-bot library for use within financial backtesting environments. By handling thread management, persistence, and version compatibility internally, it allows developers to focus on defining alerting logic rather than infrastructure. Its integration with GIPHY and automated chat migration handling makes it a flexible tool for both individual and community-driven trading dashboards.
Sources: vectorbt/messaging/telegram.py:388-392, vectorbt/messaging/init.py:13-16