# 43 - Telegram Bot Configuration

### Overview

OpenAlgo integrates with Telegram to provide real-time trading notifications, account information, and bot commands. Users can configure their Telegram bot to receive order alerts, position updates, and execute queries.

### Architecture Diagram

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                       Telegram Bot Architecture                              │
└──────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Telegram Cloud                                     │
│                                                                              │
│  ┌─────────────────┐              ┌─────────────────┐                       │
│  │  User's         │              │   Bot Father    │                       │
│  │  Telegram App   │              │   @BotFather    │                       │
│  └────────┬────────┘              └────────┬────────┘                       │
│           │                                │                                 │
│           │  Messages/Commands             │  Create Bot Token              │
│           │                                │                                 │
│           └────────────────┬───────────────┘                                │
│                            │                                                 │
│                    Bot API Gateway                                          │
│                            │                                                 │
└────────────────────────────┼────────────────────────────────────────────────┘
                             │
                             │ Webhook / Long Polling
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        OpenAlgo Backend                                      │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    Telegram Blueprint                                │   │
│  │                    /telegram/*                                       │   │
│  │                                                                      │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │   │
│  │  │ /settings    │  │ /webhook     │  │ /test        │              │   │
│  │  │ Configure    │  │ Receive      │  │ Send test    │              │   │
│  │  │ bot token    │  │ updates      │  │ message      │              │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                         │
│                                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    Telegram Service                                  │   │
│  │                                                                      │   │
│  │  ┌──────────────────────────────────────────────────────────────┐  │   │
│  │  │  Command Handler                                              │  │   │
│  │  │                                                               │  │   │
│  │  │  /start    - Initialize bot                                   │  │   │
│  │  │  /help     - Show commands                                    │  │   │
│  │  │  /funds    - Account balance                                  │  │   │
│  │  │  /positions- Open positions                                   │  │   │
│  │  │  /orders   - Order book                                       │  │   │
│  │  │  /holdings - Portfolio holdings                               │  │   │
│  │  │  /trades   - Trade book                                       │  │   │
│  │  │  /pnl      - P&L summary                                      │  │   │
│  │  │  /quote    - Get LTP                                          │  │   │
│  │  │  /status   - Connection status                                │  │   │
│  │  │  /alerts   - Toggle alerts                                    │  │   │
│  │  │  /settings - Preferences                                      │  │   │
│  │  │  /logout   - Disconnect                                       │  │   │
│  │  └──────────────────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                         │
│                                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    Database Layer                                    │   │
│  │                                                                      │   │
│  │  telegram_users │ bot_config │ command_log │ notification_queue     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Database Schema

#### telegram\_users Table

```
┌────────────────────────────────────────────────────────────────┐
│                    telegram_users table                         │
├──────────────────┬──────────────┬──────────────────────────────┤
│ Column           │ Type         │ Description                  │
├──────────────────┼──────────────┼──────────────────────────────┤
│ id               │ INTEGER PK   │ Auto-increment               │
│ user_id          │ VARCHAR(255) │ OpenAlgo user ID             │
│ telegram_id      │ BIGINT       │ Telegram chat ID             │
│ username         │ VARCHAR(255) │ Telegram username            │
│ first_name       │ VARCHAR(255) │ User's first name            │
│ is_active        │ BOOLEAN      │ Bot active status            │
│ linked_at        │ DATETIME     │ When linked                  │
│ last_activity    │ DATETIME     │ Last command time            │
└──────────────────┴──────────────┴──────────────────────────────┘
```

#### bot\_config Table

```
┌────────────────────────────────────────────────────────────────┐
│                      bot_config table                           │
├──────────────────┬──────────────┬──────────────────────────────┤
│ Column           │ Type         │ Description                  │
├──────────────────┼──────────────┼──────────────────────────────┤
│ id               │ INTEGER PK   │ Auto-increment               │
│ user_id          │ VARCHAR(255) │ OpenAlgo user ID (unique)    │
│ bot_token        │ TEXT         │ Encrypted bot token          │
│ webhook_url      │ VARCHAR(500) │ Webhook endpoint             │
│ is_enabled       │ BOOLEAN      │ Bot enabled status           │
│ created_at       │ DATETIME     │ Configuration created        │
│ updated_at       │ DATETIME     │ Last modified                │
└──────────────────┴──────────────┴──────────────────────────────┘
```

#### notification\_queue Table

```
┌────────────────────────────────────────────────────────────────┐
│                  notification_queue table                       │
├──────────────────┬──────────────┬──────────────────────────────┤
│ Column           │ Type         │ Description                  │
├──────────────────┼──────────────┼──────────────────────────────┤
│ id               │ INTEGER PK   │ Auto-increment               │
│ user_id          │ VARCHAR(255) │ Target user                  │
│ message_type     │ VARCHAR(50)  │ order/position/alert         │
│ message          │ TEXT         │ Message content              │
│ status           │ VARCHAR(20)  │ pending/sent/failed          │
│ created_at       │ DATETIME     │ Queue time                   │
│ sent_at          │ DATETIME     │ Delivery time                │
│ retry_count      │ INTEGER      │ Retry attempts               │
└──────────────────┴──────────────┴──────────────────────────────┘
```

#### user\_preferences Table

```
┌────────────────────────────────────────────────────────────────┐
│                   user_preferences table                        │
├──────────────────┬──────────────┬──────────────────────────────┤
│ Column           │ Type         │ Description                  │
├──────────────────┼──────────────┼──────────────────────────────┤
│ id               │ INTEGER PK   │ Auto-increment               │
│ user_id          │ VARCHAR(255) │ User ID (unique)             │
│ order_alerts     │ BOOLEAN      │ Order notifications          │
│ position_alerts  │ BOOLEAN      │ Position updates             │
│ pnl_alerts       │ BOOLEAN      │ P&L notifications            │
│ daily_summary    │ BOOLEAN      │ End of day summary           │
│ alert_threshold  │ DECIMAL      │ P&L alert threshold          │
└──────────────────┴──────────────┴──────────────────────────────┘
```

### Bot Commands

#### Command Reference

| Command        | Description                     | Example     |
| -------------- | ------------------------------- | ----------- |
| /start         | Initialize bot and link account | /start      |
| /help          | Display available commands      | /help       |
| /funds         | Get account balance and margin  | /funds      |
| /positions     | View open positions with P\&L   | /positions  |
| /orders        | Get today's order book          | /orders     |
| /holdings      | View portfolio holdings         | /holdings   |
| /trades        | Get executed trades             | /trades     |
| /pnl           | Get P\&L summary                | /pnl        |
| /quote SYMBOL  | Get last traded price           | /quote SBIN |
| /status        | Check broker connection         | /status     |
| /alerts on/off | Toggle notifications            | /alerts on  |
| /settings      | View/modify preferences         | /settings   |
| /logout        | Disconnect bot                  | /logout     |

### Configuration Flow

```
┌────────────────────────────────────────────────────────────────────────────┐
│                     Telegram Bot Setup Flow                                 │
│                                                                             │
│  1. Create Bot with BotFather ─────────────────────────────────────────►   │
│           │                                                                 │
│           ├──► Message @BotFather                                          │
│           ├──► /newbot command                                             │
│           ├──► Set bot name and username                                   │
│           └──► Receive bot token                                           │
│                       │                                                     │
│                       ▼                                                     │
│  2. Configure in OpenAlgo ─────────────────────────────────────────────►   │
│           │                                                                 │
│           ├──► Go to Settings > Telegram                                   │
│           ├──► Enter bot token                                             │
│           ├──► Set webhook URL (optional)                                  │
│           └──► Save configuration                                          │
│                       │                                                     │
│                       ▼                                                     │
│  3. Link Telegram Account ─────────────────────────────────────────────►   │
│           │                                                                 │
│           ├──► Open bot in Telegram                                        │
│           ├──► Send /start command                                         │
│           ├──► Enter verification code                                     │
│           └──► Account linked                                              │
│                       │                                                     │
│                       ▼                                                     │
│  4. Configure Notifications ───────────────────────────────────────────►   │
│           │                                                                 │
│           ├──► /settings in Telegram                                       │
│           ├──► Select notification types                                   │
│           └──► Set thresholds                                              │
│                                                                             │
└────────────────────────────────────────────────────────────────────────────┘
```

### Service Implementation

#### Bot Token Security

```python
from cryptography.fernet import Fernet
from utils.env_utils import get_fernet_key

def encrypt_bot_token(token):
    """Encrypt bot token before storage"""
    key = get_fernet_key()
    fernet = Fernet(key)
    return fernet.encrypt(token.encode()).decode()

def decrypt_bot_token(encrypted_token):
    """Decrypt bot token for use"""
    key = get_fernet_key()
    fernet = Fernet(key)
    return fernet.decrypt(encrypted_token.encode()).decode()
```

#### Command Handler

```python
def handle_telegram_command(update):
    """Process incoming Telegram command"""
    chat_id = update['message']['chat']['id']
    text = update['message'].get('text', '')

    # Parse command
    if text.startswith('/'):
        command = text.split()[0].lower()
        args = text.split()[1:] if len(text.split()) > 1 else []

        handlers = {
            '/start': handle_start,
            '/help': handle_help,
            '/funds': handle_funds,
            '/positions': handle_positions,
            '/orders': handle_orders,
            '/holdings': handle_holdings,
            '/trades': handle_trades,
            '/pnl': handle_pnl,
            '/quote': handle_quote,
            '/status': handle_status,
            '/alerts': handle_alerts,
            '/settings': handle_settings,
            '/logout': handle_logout
        }

        handler = handlers.get(command, handle_unknown)
        return handler(chat_id, args)
```

#### Notification Service

```python
from concurrent.futures import ThreadPoolExecutor

executor = ThreadPoolExecutor(max_workers=4)

def send_notification_async(user_id, message_type, message):
    """Send notification in background thread"""
    executor.submit(_send_notification, user_id, message_type, message)

def _send_notification(user_id, message_type, message):
    """Send Telegram notification"""
    # Get user's telegram config
    config = get_bot_config(user_id)
    telegram_user = get_telegram_user(user_id)

    if not config or not telegram_user or not config.is_enabled:
        return

    # Check user preferences
    prefs = get_user_preferences(user_id)
    if message_type == 'order' and not prefs.order_alerts:
        return

    # Send via Telegram API
    bot_token = decrypt_bot_token(config.bot_token)
    send_telegram_message(bot_token, telegram_user.telegram_id, message)

    # Log notification
    log_notification(user_id, message_type, 'sent')
```

### API Endpoints

#### Save Configuration

```
POST /telegram/settings
Content-Type: application/json

{
    "bot_token": "123456:ABC-DEF...",
    "webhook_url": "https://example.com/webhook",
    "is_enabled": true
}
```

#### Test Connection

```
POST /telegram/test
```

**Response:**

```json
{
    "status": "success",
    "message": "Test message sent successfully"
}
```

#### Webhook Endpoint

```
POST /telegram/webhook
Content-Type: application/json

{
    "update_id": 123456789,
    "message": {
        "chat": {"id": 987654321},
        "text": "/funds"
    }
}
```

### Notification Types

#### Order Notifications

```
📊 Order Executed

Symbol: SBIN
Action: BUY
Quantity: 100
Price: ₹625.50
Status: COMPLETE

Order ID: 230125000123
Time: 10:30:15 IST
```

#### Position Alerts

```
📈 Position Update

Symbol: SBIN
Quantity: 100
Entry: ₹625.50
LTP: ₹630.00
P&L: +₹450.00 (+0.72%)

Time: 10:45:00 IST
```

#### P\&L Summary

```
📊 Daily P&L Summary

Realized: +₹2,500.00
Unrealized: +₹1,250.00
Total: +₹3,750.00

Trades: 5
Win Rate: 80%

Date: 25-Jan-2025
```

### Error Handling

#### Rate Limiting

```python
TELEGRAM_RATE_LIMIT = 30  # messages per second

def check_rate_limit(user_id):
    """Ensure rate limit compliance"""
    key = f"telegram_rate:{user_id}"
    count = cache.get(key, 0)

    if count >= TELEGRAM_RATE_LIMIT:
        return False

    cache.set(key, count + 1, ttl=1)
    return True
```

#### Retry Logic

```python
MAX_RETRIES = 3
RETRY_DELAY = [1, 5, 15]  # seconds

def send_with_retry(bot_token, chat_id, message):
    """Send message with retry on failure"""
    for attempt in range(MAX_RETRIES):
        try:
            response = send_telegram_message(bot_token, chat_id, message)
            if response.ok:
                return True
        except Exception as e:
            logger.error(f"Telegram send failed: {e}")

        if attempt < MAX_RETRIES - 1:
            time.sleep(RETRY_DELAY[attempt])

    return False
```

### Key Files Reference

| File                                      | Purpose                     |
| ----------------------------------------- | --------------------------- |
| `blueprints/telegram.py`                  | Telegram routes and webhook |
| `services/telegram_bot_service.py`        | Bot command handlers        |
| `services/telegram_alert_service.py`      | Alert/notification service  |
| `database/telegram_db.py`                 | Database models             |
| `restx_api/telegram_bot.py`               | REST API endpoints          |
| `frontend/src/pages/TelegramSettings.tsx` | Configuration UI            |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openalgo.in/developers/design-documentation/43-telegram-bot-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.