Telegram Integration¶

Telegram is used for time-sensitive notifications and system health alerts.

Configuration¶

Chat ID: 1275129801 Bot Token: Stored in ~/.claude.json at mcpServers.telegram.env.TELEGRAM_BOT_TOKEN

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/telegram-mcp-server/dist/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<token-value>"
      }
    }
  }
}

MCP Tools¶

Send Messages¶

# Send text message
mcp__telegram__send_message(
    chat_id="1275129801",
    text="System alert: High memory usage detected"
)

# Send with formatting
mcp__telegram__send_message(
    chat_id="1275129801",
    text="**Critical Alert**\n\nMemory: 95%",
    parse_mode="Markdown"
)

Get Updates¶

# Retrieve recent messages
updates = mcp__telegram__get_updates(
    limit=10
)

Notification Patterns¶

System Health Alerts¶

from aegis.alerts import send_telegram_alert

# High memory usage
if mem.percent > 90:
    send_telegram_alert(
        "🔴 Memory Critical",
        f"Memory usage: {mem.percent}%\nFree: {mem.available / (1024**3):.1f}GB"
    )

Error Escalations¶

After three-strike debug protocol:

mcp__telegram__send_message(
    chat_id="1275129801",
    text=f"""
🚨 **Error Escalation**

Error: {error_type}
Strikes: 3
Context: {context}

Awaiting human intervention.
    """.strip()
)

Deployment Notifications¶

mcp__telegram__send_message(
    chat_id="1275129801",
    text=f"🚀 Deployed {service_name} to {domain}"
)

Emergency Notifications¶

For critical issues requiring immediate attention:

mcp__telegram__send_message(
    chat_id="1275129801",
    text="""
🆘 **EMERGENCY**

Service: {service}
Issue: {issue}
Impact: Production down

Action required immediately.
    """.strip()
)

Best Practices¶

Brevity: Keep messages concise (Telegram is for alerts, not logs)
Urgency: Only use for time-sensitive notifications
Formatting: Use Markdown for structure (**bold**, _italic_, `code`)
Emoji: Use emoji for quick visual scanning (🔴 critical, ⚠️ warning, ✅ success)
Actionability: Include what action is needed or what was done

Message Formatting¶

Telegram supports Markdown and HTML:

# Markdown
text = """
**Alert**: High CPU
_Status_: Investigating
`Process`: nginx

Action: Restart scheduled
"""

# HTML
text = """
<b>Alert</b>: High CPU
<i>Status</i>: Investigating
<code>Process</code>: nginx

Action: Restart scheduled
"""

Rate Limits¶

30 messages per second per bot
20 messages per minute per chat

For high-frequency alerts, consider batching or using Discord instead.

Troubleshooting¶

Bot Token Not Found¶

Check ~/.claude.json:

cat ~/.claude.json | grep -A5 telegram

Token should be under mcpServers.telegram.env.TELEGRAM_BOT_TOKEN.

Message Not Delivered¶

Verify chat ID:

# Get updates to see chat IDs
updates = mcp__telegram__get_updates()
for update in updates:
    print(f"Chat ID: {update['message']['chat']['id']}")

MCP Server Not Running¶

Restart the Telegram MCP server:

# Check logs
docker logs aegis-dashboard

# Restart container
docker restart aegis-dashboard