Telegram

Endpoint URL

This API Function Sends Custom Alert Messages to Telegram Users

Local Host   :  POST http://127.0.0.1:5000/api/v1/telegram/notify
Ngrok Domain :  POST https://<your-ngrok-domain>.ngrok-free.app/api/v1/telegram/notify
Custom Domain:  POST https://<your-custom-domain>/api/v1/telegram/notify

Prerequisites

1. Telegram Bot Must Be Running

   • Start the bot from OpenAlgo Telegram settings

   • Bot must be active to send alerts

2. User Must Be Linked

   • User must have linked their account using /link command in Telegram

   • Username in API request must match your OpenAlgo login username (the username you use to login to OpenAlgo app)

   • This is NOT your Telegram username

3. Valid API Key

   • API key must be active and valid

   • Get API key from OpenAlgo settings

Sample API Request (Basic Notification)

{
    "apikey": "your_api_key",
    "username": "john_trader",
    "message": "NIFTY crossed 24000! Consider taking profit on long positions."
}

Note: username should be your OpenAlgo login username (e.g., "john_trader"), not your Telegram username (e.g., @johntrader).

Sample API Response (Success)

{
    "status": "success",
    "message": "Notification sent successfully"
}

Sample API Request (With Priority)

{
    "apikey": "your_api_key",
    "username": "john_trader",
    "message": "🚨 URGENT: Stop loss hit on BANKNIFTY position!",
    "priority": 10
}

Sample API Request (Multi-line Alert)

{
    "apikey": "your_api_key",
    "username": "john_trader",
    "message": "📊 Daily Trading Summary\n─────────────────────\n✅ Winning Trades: 8\n❌ Losing Trades: 2\n💰 Net P&L: +₹15,450\n📈 Win Rate: 80%\n\n🎯 Great day! Keep it up!",
    "priority": 5
}

Parameter Description

Parameters	Description	Mandatory/Optional	Default Value
apikey	App API key	Mandatory	-
username	OpenAlgo login username (the username used to login to OpenAlgo app, NOT Telegram username)	Mandatory	-
message	Alert message to send	Mandatory	-
priority	Message priority (1-10, higher = more urgent)	Optional	5

Response Parameters

Parameter	Description	Type
status	API response status (success/error)	string
message	Response message	string

Use Cases

1. Price Alert Notifications

{
    "apikey": "your_api_key",
    "username": "trader_123",
    "message": "🔔 Price Alert: RELIANCE reached target price ₹2,850",
    "priority": 8
}

2. Strategy Signal Alerts

{
    "apikey": "your_api_key",
    "username": "algo_trader",
    "message": "📈 BUY Signal: RSI oversold on NIFTY 24000 CE\nEntry: ₹145.50\nTarget: ₹165.00\nSL: ₹138.00",
    "priority": 9
}

3. Risk Management Alerts

{
    "apikey": "your_api_key",
    "username": "trader_123",
    "message": "⚠️ Risk Alert: Daily loss limit reached (-₹25,000)\nNo new positions recommended.",
    "priority": 10
}

4. Market Update Notifications

{
    "apikey": "your_api_key",
    "username": "trader_123",
    "message": "📰 Market Update: FII bought ₹2,500 crores today\nMarket sentiment: Bullish\nNIFTY support: 23,800",
    "priority": 5
}

5. Trade Execution Confirmation

{
    "apikey": "your_api_key",
    "username": "trader_123",
    "message": "✅ Order Executed\nSymbol: BANKNIFTY 48000 CE\nAction: BUY\nQty: 30\nPrice: ₹245.75\nTotal: ₹7,372.50",
    "priority": 7
}

6. Technical Indicator Alerts

{
    "apikey": "your_api_key",
    "username": "technical_trader",
    "message": "📊 Technical Alert: NIFTY\n• RSI: 72 (Overbought)\n• MACD: Bearish Crossover\n• Support: 23,850\n• Resistance: 24,150\n\nConsider booking profits.",
    "priority": 8
}

Priority Levels

Priority	Description	Use Case
1-3	Low Priority	General updates, market news
4-6	Normal Priority	Trade signals, daily summaries
7-8	High Priority	Price alerts, position updates
9-10	Urgent	Stop loss hits, risk alerts

Note: Priority affects message delivery order but all messages are delivered.

Error Responses

Invalid API Key

{
    "status": "error",
    "message": "Invalid or missing API key"
}

User Not Found

{
    "status": "error",
    "message": "User not found or not linked to Telegram"
}

Common Cause: Using Telegram username instead of OpenAlgo login username. Use the username you login to OpenAlgo with, not your @telegram_handle.

Missing Parameters

{
    "status": "error",
    "message": "Username and message are required"
}

Bot Not Running

{
    "status": "error",
    "message": "Failed to send notification"
}

Common Error Messages

Error Message	Cause	Solution
Invalid or missing API key	API key is incorrect or expired	Check API key in settings
User not found or not linked to Telegram	User hasn't linked account OR using wrong username	Use OpenAlgo login username (not Telegram username). Link account via /link command
Username and message are required	Missing required fields	Provide username and message
Failed to send notification	Bot is not running	Start bot from Telegram settings

Message Formatting

Supported Markdown

• Bold: *text* or **text**

• Italic: _text_ or __text__

• Code: `text`

• Pre-formatted: ```text```

• Links: [text](url)

Emojis

Use standard Unicode emojis in messages:

• 📈 📉 Charts

• 💰 💵 Money

• ✅ ❌ Status

• 🚨 ⚠️ Alerts

• 📊 📉 Analytics

• 🎯 🔔 Notifications

Line Breaks

Use \n for line breaks in JSON strings.

Rate Limiting

• Limit: 30 requests per minute per user

• Scope: Per API endpoint

• Response: 429 status code if limit exceeded

Best Practices

1. Use Correct Username: Always use your OpenAlgo login username (the one you use to login to OpenAlgo app), NOT your Telegram username (@handle)

2. Keep Messages Concise: Short, actionable messages work best

3. Use Emojis Wisely: Emojis improve readability but don't overuse

4. Set Appropriate Priority: Reserve high priority (9-10) for urgent alerts only

5. Format for Readability: Use line breaks and sections for multi-line messages

6. Test First: Send test messages before automating

7. Handle Errors: Implement error handling for failed notifications

8. Username Match: Ensure username matches exactly (case-sensitive)

9. Bot Status: Check bot is running before bulk notifications

Integration Examples

Python Example

import requests
import json

def send_telegram_alert(username, message, priority=5):
    url = "http://127.0.0.1:5000/api/v1/telegram/notify"

    payload = {
        "apikey": "your_api_key_here",
        "username": username,
        "message": message,
        "priority": priority
    }

    response = requests.post(url, json=payload)
    return response.json()

# Usage
result = send_telegram_alert(
    username="trader_123",
    message="🎯 Target reached on NIFTY 24000 CE",
    priority=8
)

print(result)

JavaScript Example

async function sendTelegramAlert(username, message, priority = 5) {
    const url = 'http://127.0.0.1:5000/api/v1/telegram/notify';

    const payload = {
        apikey: 'your_api_key_here',
        username: username,
        message: message,
        priority: priority
    };

    const response = await fetch(url, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
    });

    return await response.json();
}

// Usage
sendTelegramAlert(
    'trader_123',
    '📈 Buy signal detected on BANKNIFTY',
    8
).then(result => console.log(result));

cURL Example

curl -X POST http://127.0.0.1:5000/api/v1/telegram/notify \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "your_api_key_here",
    "username": "trader_123",
    "message": "Test alert from API",
    "priority": 5
  }'

Workflow Integration

With Trading Strategies

# After order execution
if order_status == "success":
    send_telegram_alert(
        username="trader_123",
        message=f"✅ Order executed: {symbol} {action} {quantity}",
        priority=7
    )

With Price Monitoring

# Price alert system
if current_price >= target_price:
    send_telegram_alert(
        username="trader_123",
        message=f"🎯 {symbol} reached target price: ₹{current_price}",
        priority=9
    )

With Risk Management

# Daily loss limit
if daily_loss >= max_loss_limit:
    send_telegram_alert(
        username="trader_123",
        message=f"🚨 Daily loss limit reached: -₹{daily_loss}\nTrading halted.",
        priority=10
    )

Features

1. Custom Messages: Send any text-based alert

2. Priority System: Control message importance (1-10)

3. Rich Formatting: Support for emojis, markdown, line breaks

4. User-Specific: Target specific users by username

5. High Reliability: Messages queued if delivery fails

6. Rate Limited: Prevents spam and abuse

7. Secure: API key authentication required

Troubleshooting

Alert Not Received

1. Check Bot Status: Ensure bot is running in OpenAlgo settings

2. Verify Username: Confirm username matches linked account (case-sensitive)

3. Check Linking: User must have linked account via /link command

4. Review Logs: Check OpenAlgo logs for error messages

5. Test Connection: Use /status command in Telegram bot

Delivery Delays

1. Rate Limiting: Check if rate limit exceeded (30/min)

2. Bot Load: High message volume may cause slight delays

3. Network Issues: Check internet connectivity

4. Telegram API: Telegram may have temporary issues

Formatting Issues

1. Escape Characters: Use proper JSON escaping for special characters

2. Line Breaks: Use \n not actual line breaks in JSON

3. Markdown: Check markdown syntax is correct

4. Message Length: Keep messages under 4096 characters (Telegram limit)

Security Considerations

1. API Key Protection: Never expose API keys in client-side code

2. Username Privacy: Usernames are case-sensitive and private

3. Message Content: Don't send sensitive data in plain text

4. Rate Limiting: Prevents abuse and spam

5. Authentication: Every request must include valid API key

Limitations

• Maximum message length: 4096 characters (Telegram limit)

• Rate limit: 30 messages per minute per user

• Bot must be running to send messages

• User must be linked to receive messages

• Messages are queued but not guaranteed during bot downtime

Support

For issues or questions:

• Check bot status in OpenAlgo Telegram settings

• Verify user is linked via /status command in Telegram

• Review API response for specific error messages

• Check OpenAlgo logs for detailed error information