You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# Telegram Integration for Digital Twin Monitoring
|
|
|
|
This document provides comprehensive information about the Telegram integration for the Digital Twin Monitoring application. The integration allows the application to send automatic notifications to Telegram when parts with red status are detected.
|
|
|
|
## Overview
|
|
|
|
The Telegram integration consists of:
|
|
|
|
1. **telegram_notifier.py**: A module that provides functionality to send Telegram notifications
|
|
2. **test_telegram_notification.py**: A script to test the Telegram notification functionality
|
|
3. **telegram_setup_guide.md**: A guide explaining how to set up a Telegram bot and configure the integration
|
|
|
|
## Features
|
|
|
|
- Automatic notifications when parts with red status are detected
|
|
- Detailed information about the affected parts in the notification message
|
|
- Configurable via environment variables or direct code configuration
|
|
- Easy to test and verify using the provided test script
|
|
|
|
## Files Added
|
|
|
|
### 1. telegram_notifier.py
|
|
|
|
This is the core module that provides the Telegram notification functionality. It includes:
|
|
|
|
- `TelegramNotifier` class: A class to send notifications to Telegram
|
|
- `check_red_status_and_notify` function: A convenience function to check for parts with red status and send notifications
|
|
|
|
### 2. test_telegram_notification.py
|
|
|
|
A script to test the Telegram notification functionality. It includes:
|
|
|
|
- `test_direct_message` function: Tests sending a direct message to Telegram
|
|
- `test_red_status_notification` function: Tests sending a notification for parts with red status
|
|
|
|
### 3. telegram_setup_guide.md
|
|
|
|
A comprehensive guide explaining how to set up a Telegram bot and configure the integration.
|
|
|
|
## Integration with app.py
|
|
|
|
The Telegram notification functionality is integrated into the main application (app.py) in the `/api/data` route. When this route is called, the application:
|
|
|
|
1. Fetches data from the database
|
|
2. Analyzes the data to determine part statuses
|
|
3. Checks for parts with red status and sends a Telegram notification if any are found
|
|
4. Returns the results as JSON
|
|
|
|
## How to Use
|
|
|
|
### 1. Setup
|
|
|
|
Follow the instructions in `telegram_setup_guide.md` to:
|
|
|
|
1. Create a Telegram bot
|
|
2. Get your chat ID
|
|
3. Configure the application with your bot token and chat ID
|
|
|
|
### 2. Testing
|
|
|
|
Use the `test_telegram_notification.py` script to test your Telegram notification setup:
|
|
|
|
```bash
|
|
python test_telegram_notification.py
|
|
```
|
|
|
|
This will:
|
|
1. Send a direct test message to your Telegram chat
|
|
2. Send a notification for sample parts with red status
|
|
|
|
### 3. Running the Application
|
|
|
|
Once you've set up and tested the Telegram integration, you can run the application as usual:
|
|
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
The application will now automatically send Telegram notifications when parts with red status are detected.
|
|
|
|
## Configuration Options
|
|
|
|
### Environment Variables
|
|
|
|
Set these environment variables to configure the Telegram integration:
|
|
|
|
- `TELEGRAM_BOT_TOKEN`: Your Telegram bot token
|
|
- `TELEGRAM_CHAT_ID`: Your Telegram chat ID
|
|
|
|
### Direct Configuration
|
|
|
|
You can also configure the Telegram integration directly in code:
|
|
|
|
```python
|
|
from telegram_notifier import check_red_status_and_notify
|
|
|
|
# After analyzing data and getting results
|
|
check_red_status_and_notify(results, bot_token="your_bot_token_here", chat_id="your_chat_id_here")
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
If you're not receiving notifications:
|
|
|
|
1. Check that your bot token and chat ID are correct
|
|
2. Ensure your bot has permission to send messages to the chat
|
|
3. Check the application logs for any error messages related to Telegram notifications
|
|
4. Make sure the requests library is installed (`pip install requests`)
|
|
5. Verify that there are actually parts with red status in the system
|
|
|
|
## Security Considerations
|
|
|
|
- Never hardcode your bot token in the source code
|
|
- Use environment variables or a secure configuration system
|
|
- Regularly rotate your bot token if you suspect it has been compromised
|
|
- Be careful about what information is included in the notifications
|
|
|
|
## Dependencies
|
|
|
|
The Telegram integration requires the `requests` library, which has been added to `requirements.txt`. Make sure to install it:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Additional Resources
|
|
|
|
- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
|
|
- [Python Requests Library Documentation](https://docs.python-requests.org/en/latest/) |