ResourceUsageAPI/TELEGRAM_SETUP.md

# Telegram Bot Alert Setup Guide

The Resource Monitor Service supports sending alerts via Telegram bot. This allows you to receive real-time notifications about system resource warnings and critical alerts directly to your Telegram chat.

## Prerequisites

1. **Create a Telegram Bot**:
   - Open Telegram and search for `@BotFather`
   - Send `/newbot` command
   - Follow the instructions to create a new bot
   - Save the Bot Token (format: `123456789:ABCdefGHIjklMNOpqrSTUvwxyz`)

2. **Get Your Chat ID**:
   - Send a message to your bot
   - Visit: `https://api.telegram.org/bot<YourBOTToken>/getUpdates`
   - Find your chat ID in the response (it's a number, can be negative for groups)

## Configuration

### 1. Edit appsettings.json

Add or update the Telegram configuration in your `appsettings.json`:

```json
{
  "MonitoringSettings": {
    // ... other settings ...
    "Telegram": {
      "IsEnabled": true,
      "BotToken": "123456789:ABCdefGHIjklMNOpqrSTUvwxyz",
      "ChatIds": [12345678, -987654321],
      "SendWarningAlerts": true,
      "SendCriticalAlerts": true,
      "SendResolutionNotifications": true,
      "MessageTemplate": "🚨 *{Level} Alert*\n\n📊 *{Component}*\n💬 {Message}\n⏰ {Timestamp}",
      "ResolutionTemplate": "✅ *Alert Resolved*\n\n📊 *{Component}*\n💬 {Message}\n⏰ Resolved at {ResolvedAt}"
    }
  }
}
```

### 2. Configuration Options

| Setting | Description | Default |
|---------|-------------|---------|
| `IsEnabled` | Enable/disable Telegram notifications | `false` |
| `BotToken` | Your Telegram bot token from BotFather | `""` |
| `ChatIds` | Array of chat IDs to send alerts to | `[]` |
| `SendWarningAlerts` | Send warning level alerts | `true` |
| `SendCriticalAlerts` | Send critical level alerts | `true` |
| `SendResolutionNotifications` | Send alert resolution notifications | `true` |
| `MessageTemplate` | Template for alert messages | See above |
| `ResolutionTemplate` | Template for resolution messages | See above |

### 3. Message Templates

Templates support the following placeholders:

- `{Level}` - Alert level (Warning, Critical)
- `{Component}` - Component name (CPU, Memory, GPU, etc.)
- `{Message}` - Full alert message
- `{Timestamp}` - Alert timestamp
- `{CurrentValue}` - Current resource value
- `{ThresholdValue}` - Threshold that was exceeded
- `{ResolvedAt}` - Resolution timestamp (resolution template only)

## API Endpoints

### Check Telegram Status
```
GET /api/telegram/status
```

Returns the current status of Telegram integration:
```json
{
  "enabled": true,
  "connected": true
}
```

### Send Test Alert
```
POST /api/telegram/test
```

Sends a test alert to verify the Telegram bot is working correctly.

## Features

### Alert Types

The bot sends different types of alerts:

1. **Warning Alerts** ⚠️
   - Sent when thresholds are exceeded but not critical
   - Notifications are silent (no sound/vibration)

2. **Critical Alerts** 🔴
   - Sent when critical thresholds are exceeded
   - Normal notifications (with sound/vibration)

3. **Resolution Notifications** ✅
   - Sent when alerts are resolved
   - Always silent notifications

### Icons and Formatting

The bot automatically adds relevant icons:

- 🖥️ CPU usage
- 🌡️ Temperature alerts
- 💾 Memory usage
- 🎮 GPU usage
- 💽 Disk usage
- ⚙️ Process alerts

Messages are formatted using Telegram's Markdown formatting for better readability.

### Multiple Chat Support

You can send alerts to multiple chats:
- Personal chats
- Group chats
- Channels (if bot is admin)

Just add multiple chat IDs to the `ChatIds` array.

## Troubleshooting

### Common Issues

1. **Bot not responding**:
   - Verify bot token is correct
   - Ensure bot is not blocked
   - Check `/api/telegram/status` endpoint

2. **Messages not received**:
   - Verify chat ID is correct
   - Ensure you've sent at least one message to the bot
   - Check bot has permission to send messages

3. **Connection errors**:
   - Check internet connectivity
   - Verify Telegram API is accessible
   - Check firewall settings

### Testing

1. Set `IsEnabled: true` in configuration
2. Restart the service
3. Call `POST /api/telegram/test` to send a test message
4. Check if the message is received in Telegram

### Logs

Monitor the service logs for Telegram-related errors:
```
grep -i telegram logs/resourcemonitor-*.txt
```

## Security Considerations

1. **Keep bot token secure** - Never commit it to version control
2. **Use environment variables** for sensitive configuration in production
3. **Limit chat IDs** to trusted users/groups only
4. **Regular token rotation** if compromised

## Example Alert Messages

### Warning Alert
```
⚠️ 🖥️ 🚨 Warning Alert

📊 CPU
💬 CPU Usage is warning: 85.2% (threshold: 80.0%)
⏰ 2025-08-07 14:30:15
```

### Critical Alert
```
🔴 💾 🚨 Critical Alert

📊 Memory
💬 Memory Usage is critical: 96.8% (threshold: 95.0%)
⏰ 2025-08-07 14:35:22
```

### Resolution
```
✅ 🖥️ Alert Resolved

📊 CPU
💬 CPU Usage is warning: 85.2% (threshold: 80.0%)
⏰ Resolved at 2025-08-07 14:32:45
```