Telegram | Documentation

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

Telegram Bot Must Be Running
- Start the bot from OpenAlgo Telegram settings
- Bot must be active to send alerts
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
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

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

Use Correct Username: Always use your OpenAlgo login username (the one you use to login to OpenAlgo app), NOT your Telegram username (@handle)
Keep Messages Concise: Short, actionable messages work best
Use Emojis Wisely: Emojis improve readability but don't overuse
Set Appropriate Priority: Reserve high priority (9-10) for urgent alerts only
Format for Readability: Use line breaks and sections for multi-line messages
Test First: Send test messages before automating
Handle Errors: Implement error handling for failed notifications
Username Match: Ensure username matches exactly (case-sensitive)
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

Custom Messages: Send any text-based alert
Priority System: Control message importance (1-10)
Rich Formatting: Support for emojis, markdown, line breaks
User-Specific: Target specific users by username
High Reliability: Messages queued if delivery fails
Rate Limited: Prevents spam and abuse
Secure: API key authentication required

Troubleshooting

Alert Not Received

Check Bot Status: Ensure bot is running in OpenAlgo settings
Verify Username: Confirm username matches linked account (case-sensitive)
Check Linking: User must have linked account via /link command
Review Logs: Check OpenAlgo logs for error messages
Test Connection: Use /status command in Telegram bot

Delivery Delays

Rate Limiting: Check if rate limit exceeded (30/min)
Bot Load: High message volume may cause slight delays
Network Issues: Check internet connectivity
Telegram API: Telegram may have temporary issues

Formatting Issues

Escape Characters: Use proper JSON escaping for special characters
Line Breaks: Use \n not actual line breaks in JSON
Markdown: Check markdown syntax is correct
Message Length: Keep messages under 4096 characters (Telegram limit)

Security Considerations

API Key Protection: Never expose API keys in client-side code
Username Privacy: Usernames are case-sensitive and private
Message Content: Don't send sensitive data in plain text
Rate Limiting: Prevents abuse and spam
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

PreviousAlert API NextWebsockets

Last updated 18 hours ago

Was this helpful?