README

A comprehensive Telegram bot extension for Flarum that sends real-time notifications with advanced rate limiting and customization options.
✨ Features

🔔 Real-time notifications - discussions, posts, users, likes, and more
⚡ Advanced rate limiting - hourly limits, minimum gaps, quiet hours
🎛️ Granular notification controls - enable/disable specific event types
🌙 Quiet hours support - no notifications during sleep time
📊 Built-in analytics and monitoring
🔧 Easy console setup and testing tools
🚀 Multi-language support
🛡️ Error handling with automatic retries
📋 Requirements

Flarum ^1.0
PHP ^7.4 | ^8.0
cURL extension
Valid Telegram Bot Token
🚀 Installation

# Navigate to your Flarum directory
cd /path/to/your/flarum

# Install via Composer
composer require cryptofxnotify/telegram

# Enable the extension
php flarum extension:enable cryptofxnotify-telegram

# Clear cache
php flarum cache:clear
🤖 Bot Setup
Step 1: Create Telegram Bot

Open Telegram and search for @BotFather
Start a chat and send: /newbot
Follow the prompts:
Bot Name: Your Forum Notifications
Username: yourforum_bot (must end with _bot)


Copy the Bot Token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Step 2: Get Chat/Channel ID
For Personal Notifications:

Start a chat with your bot
Send any message to the bot
Visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
Find "chat":{"id":12345678} - that's your Chat ID

For Channel/Group Notifications:

Add your bot to the channel/group as admin
Send a message in the channel
Visit the same URL above
Look for "chat":{"id":-100123456789} - negative numbers are for groups/channels

Step 3: Configure the Extension
# Interactive configuration wizard
php flarum telegram:config

# Or configure manually
php flarum settings:set telegram.bot_token "YOUR_BOT_TOKEN"
php flarum settings:set telegram.chat_id "YOUR_CHAT_ID"
Step 4: Test Your Setup
# Send a test notification
php flarum telegram:test

# Expected output:
# ✅ Test notification sent successfully!
# ✅ Telegram integration is working properly
⚙️ Configuration Reference
Core Settings



Setting
Description
Default
Example



telegram.bot_token
Your Telegram bot token
-
123456789:ABC...


telegram.chat_id
Chat/Channel ID for notifications
-
12345678 or -100123456789


telegram.enabled
Enable/disable all notifications
true
true/false


telegram.parse_mode
Message formatting mode
HTML
HTML/Markdown


Rate Limiting Settings



Setting
Description
Default
Range
Example



telegram.max_per_hour
Maximum notifications per hour
10
1-999
5 (more restrictive)


telegram.min_gap_seconds
Minimum seconds between notifications
180
0-3600
300 (5 minutes)


telegram.quiet_start
Quiet hours start (24h format)
22
0-23
23 (11 PM)


telegram.quiet_end
Quiet hours end (24h format)
8
0-23
7 (7 AM)


Notification Type Controls



Setting
Description
Default
Events Covered



telegram.notify_discussions
New discussions created
true
Discussion started, renamed, deleted


telegram.notify_posts
New posts and replies
true
Post created, edited, deleted


telegram.notify_users
User activities
true
Registration, activation


telegram.notify_likes
Post likes/reactions
false
Post liked, unliked


🔧 Console Commands
Configuration Command
php flarum telegram:config

# Interactive prompts:
# - Enter bot token
# - Enter chat ID
# - Configure rate limits
# - Set quiet hours
# - Choose notification types
Test Command
php flarum telegram:test

# Options:
php flarum telegram:test --silent    # No console output
php flarum telegram:test --verbose   # Detailed debugging info
Settings Management
# View all telegram settings
php flarum settings:list | grep telegram

# Get specific setting
php flarum settings:get telegram.bot_token

# Update settings
php flarum settings:set telegram.max_per_hour "5"
php flarum settings:set telegram.quiet_start "23"
php flarum settings:set telegram.notify_likes "true"

# Disable temporarily
php flarum settings:set telegram.enabled "false"
📊 Rate Limiting Examples
Example 1: Conservative Setup (Low Traffic)
php flarum settings:set telegram.max_per_hour "3"       # Max 3/hour
php flarum settings:set telegram.min_gap_seconds "300"  # 5 min gap
php flarum settings:set telegram.quiet_start "22"      # Sleep 10 PM
php flarum settings:set telegram.quiet_end "8"         # Wake 8 AM
Timeline:

10:00 AM - Discussion created → ✅ Sent (1/3)
10:03 AM - Post created → ❌ Blocked (need 5 min gap)
10:06 AM - Post created → ✅ Sent (2/3)
10:15 AM - User registered → ✅ Sent (3/3)
10:30 AM - New discussion → ❌ Blocked (hourly limit reached)
11:01 AM - New post → ✅ Sent (new hour, counter reset)

Example 2: Aggressive Setup (High Traffic)
php flarum settings:set telegram.max_per_hour "1"       # Only 1/hour
php flarum settings:set telegram.min_gap_seconds "600"  # 10 min gap  
php flarum settings:set telegram.quiet_start "20"      # Sleep 8 PM
php flarum settings:set telegram.quiet_end "10"        # Wake 10 AM
Example 3: Relaxed Setup (Development)
php flarum settings:set telegram.max_per_hour "50"     # High limit
php flarum settings:set telegram.min_gap_seconds "30"  # 30 sec gap
php flarum settings:set telegram.quiet_start "25"      # No quiet hours (invalid = disabled)
php flarum settings:set telegram.quiet_end "25"        
🔍 Troubleshooting
Common Issues
❌ "Bot token is invalid"
# Check token format (should be 45-46 characters)
php flarum settings:get telegram.bot_token

# Verify with Telegram API
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
❌ "Chat not found" or "Forbidden"
# Ensure bot can access chat
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getChat?chat_id=<YOUR_CHAT_ID>"

# For channels: Make sure bot is admin
# For groups: Bot must be added as member first
❌ "Notifications not sending"
# Check if telegram is enabled
php flarum settings:get telegram.enabled

# Check rate limiting status
php flarum settings:get telegram.hourly_count
php flarum settings:get telegram.last_sent_time

# Send test notification
php flarum telegram:test --verbose
❌ "Rate limited" messages
Current hour notification count exceeded. Solutions:
# Check current limits
php flarum settings:get telegram.max_per_hour
php flarum settings:get telegram.hourly_count

# Increase hourly limit
php flarum settings:set telegram.max_per_hour "20"

# Or manually reset counter (emergency)
php flarum settings:set telegram.hourly_count "0"
php flarum settings:set telegram.count_reset_time "0"
Debug Mode
Enable detailed logging:
# Check Flarum logs
tail -f storage/logs/flarum.log | grep telegram

# Test with verbose output
php flarum telegram:test --verbose
Notification Format Examples
Discussion Created:
🆕 New Discussion

📋 Title: "How to install extensions?"
👤 Author: John Doe
🕐 Time: 2024-01-15 14:30

💬 "I need help with installing Flarum extensions..."

🔗 View: https://yourforum.com/d/123
New Post:
💬 New Reply

📋 Discussion: "Installation Help"  
👤 Author: Jane Smith
🕐 Time: 2024-01-15 14:35

"You can install extensions using composer require..."

🔗 View: https://yourforum.com/d/123/5
User Registered:
👋 New Member

👤 User: Mike Johnson
📧 Email: mike@example.com  
🕐 Joined: 2024-01-15 14:40

🔗 Profile: https://yourforum.com/u/mike-johnson
🛠️ Advanced Configuration
Multiple Chat Support
# Primary notifications
php flarum settings:set telegram.chat_id "12345678"

# For multiple chats, use comma separation (future feature)
php flarum settings:set telegram.chat_id "12345678,-100987654321"
Custom Message Templates
The extension uses built-in templates, but you can customize them by:

Creating language overrides in your theme
Modifying the message formatting in the extension code
Using the parse_mode setting for different formatting styles

Integration with Other Extensions
The bot automatically detects and supports:

Blog extensions (post notifications)  
Pages extensions (page creation)
Custom discussion types
Tag-based filtering (coming soon)

📈 Performance Considerations

Rate limiting prevents API abuse and telegram blocking
Quiet hours reduce nighttime disturbances  
Minimum gaps prevent notification spam
Error handling includes automatic retries with exponential backoff
Database optimization - minimal settings storage

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙋‍♂️ Support

Issues: GitHub Issues
Discussions: Flarum Community
Documentation: This README and inline code comments

🔄 Changelog
v1.0.0

Initial release
Basic notification support
Rate limiting system
Console commands
Quiet hours support

v1.1.0 (Coming Soon)

Multiple chat support
Custom message templates
Tag-based filtering
Analytics dashboard


Made with ❤️ for the Flarum community

This complete README file includes:
- ✅ Professional formatting with badges
- ✅ Complete installation guide  
- ✅ Step-by-step bot setup
- ✅ Comprehensive configuration reference
- ✅ Console commands with examples
- ✅ Rate limiting examples with timelines
- ✅ Detailed troubleshooting section
- ✅ Message format previews
- ✅ Advanced configuration options
- ✅ Contributing guidelines
- ✅ Support information

Just save this as `README.md` and push to your GitHub repo! 🚀
cryptofxnotify / telegram-notifications

Maintainers

Details

README

✨ Features

📋 Requirements

🚀 Installation
