A modern, well-organized Python package for sending Telegram notifications with enhanced performance, better error handling, and beautiful user interfaces.
- 🚀 High Performance: Connection pooling and automatic retry strategies
- 🎨 Beautiful CLI: Rich terminal output with colors, progress bars, and tables
- 🔒 Type Safety: Full Pydantic validation for all configurations
- 📱 Multi-format Support: Send text messages, photos, and documents
- ⚙️ Flexible Configuration: Environment variables, JSON files, or interactive setup
- 🛡️ Robust Error Handling: Comprehensive error handling with clear messages
- 🧪 Comprehensive Testing: Full test suite with 90%+ coverage
- 📚 Modern Python: Type hints, async support, and context managers
# Install from source
python3 setup.py install# Interactive setup wizard
notify2 setup
# Or manually create config file
mkdir -p ~/.notify2
cat > ~/.notify2/config.json << EOF
{
"telegram": {
"bot_token": "YOUR_BOT_TOKEN",
"chat_id": "YOUR_CHAT_ID",
"parse_mode": "HTML"
},
"timeout": 10,
"retry_attempts": 3,
"retry_delay": 1.0
}
EOF# Test your connection
notify2 test
# Send a simple message
notify2 send "Hello, World! 🚀"
# Send with formatting
notify2 send "*Bold text* and _italic text_" --parse-mode Markdown
# Send a photo
notify2 photo image.jpg --caption "Check this out!"
# Send a document
notify2 document report.pdf --caption "Monthly report"
# Show current configuration
notify2 infoFor full documentation, including CLI usage, API reference, configuration, and troubleshooting, please refer to our documentation site.
Test the Telegram connection and display bot information.
notify2 test # Use default config
notify2 test --env # Use environment variables
notify2 test -c config.json # Use custom config fileSend text messages with various formatting options.
notify2 send "Hello, World!" # Simple message
notify2 send "*Bold* text" --parse-mode Markdown # Formatted
echo "Hello" | notify2 send # From stdin
notify2 send --silent "Secret message" # Silent messageOptions:
--parse-mode: HTML, Markdown, or MarkdownV2--disable-preview: Disable web page previews--silent: Send without notification sound
Send photos with optional captions.
notify2 photo image.jpg # Simple photo
notify2 photo sunset.png --caption "Beautiful!" # With caption
notify2 photo pic.jpg --parse-mode Markdown # Formatted captionSend documents with optional captions.
notify2 document report.pdf # Simple document
notify2 document data.csv --caption "Monthly data" # With caption
notify2 document file.txt --parse-mode Markdown # Formatted captionInteractive setup wizard for configuration.
notify2 setupThis guides you through:
- Entering your bot token from @BotFather
- Entering your chat ID
- Testing the connection
- Saving the configuration
Show current configuration information.
notify2 infofrom notify2 import TelegramNotifier, Config
# Load configuration
config = Config.from_file()
# Send messages
with TelegramNotifier(config) as notifier:
# Simple message
result = notifier.send_message("Hello, World!")
print(f"Message sent with ID: {result['result']['message_id']}")
# Formatted message
result = notifier.send_message(
"**Bold text** and *italic text*",
parse_mode="Markdown"
)
# Photo with caption
result = notifier.send_photo("image.jpg", "Beautiful sunset!")
# Document
result = notifier.send_document("report.pdf", "Monthly report")from notify2 import Config, TelegramConfig
# Create configuration from environment variables
config = Config.from_env()
# Create configuration from file
config = Config.from_file()
# Create configuration manually
telegram_config = TelegramConfig(
bot_token="YOUR_BOT_TOKEN",
chat_id="YOUR_CHAT_ID",
parse_mode="HTML"
)
config = Config(
telegram=telegram_config,
timeout=30,
retry_attempts=5,
retry_delay=2.0
)
# Save configuration
config.save_to_file()from notify2 import TelegramNotifier, Config
config = Config.from_file()
with TelegramNotifier(config) as notifier:
# Test connection
if notifier.test_connection():
print("Connection successful!")
# Get bot information
bot_info = notifier.get_me()
print(f"Bot name: {bot_info['result']['first_name']}")
# Send message with all options
result = notifier.send_message(
message="Hello with options!",
parse_mode="Markdown",
disable_web_page_preview=True,
disable_notification=True,
reply_to_message_id=123
)export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"Default location: ~/.notify2/config.json
{
"telegram": {
"bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
"chat_id": "123456789",
"parse_mode": "HTML"
},
"timeout": 10,
"retry_attempts": 3,
"retry_delay": 1.0
}| Option | Type | Default | Description |
|---|---|---|---|
bot_token |
string | required | Telegram bot token from @BotFather |
chat_id |
string | required | Target chat ID for messages |
parse_mode |
string | "HTML" | Message parsing mode (HTML, Markdown, MarkdownV2) |
timeout |
int | 10 | Request timeout in seconds (1-300) |
retry_attempts |
int | 3 | Number of retry attempts (0-10) |
retry_delay |
float | 1.0 | Delay between retries in seconds (0.1-60.0) |
- Connection Pooling: Reuses HTTP connections for better performance
- Automatic Retries: Exponential backoff for failed requests
- Resource Management: Proper cleanup with context managers
- Type Safety: Pydantic validation prevents runtime errors
# Run setup wizard
notify2 setup
# Or create config manually
mkdir -p ~/.notify2
# Edit ~/.notify2/config.json- Get a new bot token from @BotFather
- Ensure the token format is correct:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
- Use @userinfobot to get your chat ID
- For groups, use @RawDataBot in the group
- Telegram has a 4096 character limit for messages
- Split long messages into multiple parts
This project is licensed under the MIT License - see the LICENSE file for details.
- Telegram Bot API for the excellent API
- Pydantic for data validation
- Rich for beautiful terminal output
- Click for CLI framework
- Issues: GitHub Issues
- Documentation: Documentation
- Examples: Basic Usage
Made with ❤️ and ☕ by the Notify2 team