From 1d0d01c00bca3aeb36319de0d07132375eb8324e Mon Sep 17 00:00:00 2001 From: krypt77 Date: Tue, 8 Jul 2025 19:10:13 +0200 Subject: [PATCH] Update README.md --- README.md | 246 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 245 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a6e46b3..5aa694f 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,246 @@ -# RSS-To-Telegram-Bot +# RSS to Telegram Bot +A simple PHP script that monitors RSS feeds and automatically sends new articles to Telegram channels. Perfect for news aggregation, blog updates, or any RSS-based content distribution. + +## What it does + +- 📡 Monitors multiple RSS feeds simultaneously +- 🚫 Prevents duplicates automatically +- ⚡ Supports Telegram Instant View +- 🎨 HTML formatting with rich text +- 📝 Comprehensive logging system +- 💾 Persists state between runs +- ⏰ Cron job compatible +- 🛠️ Error handling and automatic recovery + +## How it works + +### Tracking system + +The script uses a simple but effective system to avoid duplicate messages: + +1. **State file (`rss_state.json`)**: Stores info about processed articles for each feed and date +2. **Daily reset**: Automatically cleans old data, keeping only current day's records +3. **URL-based detection**: Uses article links to identify duplicates +4. **Per-feed tracking**: Each RSS feed maintains its own state + +### Workflow + +``` +RSS Feed → Parse XML → Filter by date → Check duplicates → Format message → Send to Telegram +``` + +1. **RSS parsing**: Uses SimpleXML to read feeds +2. **Date filtering**: Only processes today's articles (configurable) +3. **Anti-duplicates**: Checks against already sent URLs +4. **Formatting**: Creates HTML messages with source attribution +5. **Delivery**: Sends formatted messages to the channel + +## Installation + +1. **Clone the repository** + ```bash + git clone https://github.com/yourusername/rss-to-telegram-bot.git + cd rss-to-telegram-bot + ``` + +2. **Create a Telegram bot** + - Message [@BotFather](https://t.me/BotFather) on Telegram + - Use `/newbot` to create a new bot + - Copy the API token + +3. **Get channel ID** + - Add [@userinfobot](https://t.me/userinfobot) to your channel + - Forward a message from the channel to @userinfobot + - Copy the channel ID (starts with `-100`) + +4. **Configure the script** + Edit the configuration section: + ```php + $apiToken = "YOUR_BOT_TOKEN_HERE"; + $channelId = "YOUR_CHANNEL_ID"; + $rssFeeds = [ + ["https://example.com/feed/", ""], + ["https://another-feed.com/rss/", "INSTANT_VIEW_HASH"] + ]; + ``` + +## Configuration + +### Basic settings + +- `$apiToken`: Your bot token from BotFather +- `$channelId`: Target Telegram channel ID (must start with `-100`) +- `$rssFeeds`: Array of RSS feeds to monitor + +### RSS feed format + +```php +$rssFeeds = [ + ["RSS_URL", "INSTANT_VIEW_HASH"], + ["https://example.com/feed/", ""], // Without instant view + ["https://news.site.com/rss/", "abc123def456"] // With instant view +]; +``` + +### Instant View (optional) + +Telegram's Instant View provides a clean, fast-loading version of articles: + +1. Create an Instant View template at [instantview.telegram.org](https://instantview.telegram.org) +2. Get the template hash from the URL +3. Add it as the second parameter in the RSS feed array + +## Automation + +### Cron job (recommended) + +Add to your crontab to run every 15 minutes: + +```bash +crontab -e +``` + +Add this line: +``` +*/15 * * * * /usr/bin/php /path/to/rss-to-telegram-bot.php >/dev/null 2>&1 +``` + +### Other scheduling examples + +```bash +# Every 5 minutes +*/5 * * * * /usr/bin/php /path/to/script.php + +# Every hour +0 * * * * /usr/bin/php /path/to/script.php + +# Twice daily (9 AM and 6 PM) +0 9,18 * * * /usr/bin/php /path/to/script.php +``` + +## File structure + +``` +rss-to-telegram-bot/ +├── rss-to-telegram-bot.php # Main script +├── rss_state.json # Generated: tracks processed articles +├── rss_log.txt # Generated: execution logs +├── LICENSE # GPL v3 license +└── README.md # This file +``` + +## Generated files + +### State file (`rss_state.json`) +Tracks processed articles to prevent duplicates: +```json +{ + "https://example.com/feed/": { + "2024-01-15": [ + "https://example.com/article1", + "https://example.com/article2" + ] + } +} +``` + +### Log file (`rss_log.txt`) +Contains execution logs with timestamps: +``` +[2024-01-15 10:30:01] Script started for date: 2024-01-15 +[2024-01-15 10:30:02] Feed: https://example.com/feed/, New items: 3 +[2024-01-15 10:30:05] Message sent successfully: Breaking News Article +[2024-01-15 10:30:06] Script completed +``` + +## Message format + +The bot sends formatted messages with: + +- **Source attribution** with publication date +- **Article title** in bold +- **Description/excerpt** with preserved HTML formatting +- **Direct link** to original article +- **Invisible Instant View link** (if configured) + +Example output: +``` +Source: Example News - 15/01/2024 + +Breaking: Important News Update +This is the article description with basic HTML formatting preserved. + +https://example.com/article-url +``` + +## Troubleshooting + +### Common issues + +1. **No messages sent** + - Check bot token and channel ID + - Verify bot is admin in the channel + - Check if RSS feed URLs are accessible + +2. **Duplicate messages** + - Ensure `rss_state.json` has write permissions + - Check if script is running multiple times simultaneously + +3. **HTML formatting issues** + - Verify Telegram bot API limits (4096 characters max) + - Check for unsupported HTML tags + +### Debug mode + +For testing, modify the date to process yesterday's articles: +```php +// $todayDate = date('Y-m-d'); +$todayDate = date('Y-m-d', strtotime('-1 day')); +``` + +### Permissions + +Ensure proper file permissions: +```bash +chmod 755 rss-to-telegram-bot.php +chmod 666 rss_state.json rss_log.txt +``` + +## Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/improvement`) +3. Commit your changes (`git commit -am 'Add new feature'`) +4. Push to the branch (`git push origin feature/improvement`) +5. Create a Pull Request + +## License + +This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. + +### What this means: +- ✅ You can use this software for any purpose +- ✅ You can modify and distribute it +- ✅ You can use it commercially +- ⚠️ If you distribute modified versions, they must also be GPL v3 +- ⚠️ You must include the original license and copyright notices + +## Support + +If you encounter issues or have questions: + +1. Check the [troubleshooting section](#troubleshooting) +2. Review the log file for error messages +3. Open an issue on GitHub with detailed information + +## Changelog + +### v1.0.0 +- Initial release +- Basic RSS to Telegram functionality +- State tracking system +- Instant View support +- Comprehensive logging + +---