# 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/)