Telegram Integration

​

Overview

​

Features

• Text messaging
• Voice messages
• File sharing (documents, images, videos)
• Inline keyboards for interactive commands
• Real-time responses
• Group chat support

​

Setup

​

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow prompts to name your bot
4. Copy the bot token provided

​

2. Configure Praxos

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

​

3. Set Webhook (Production)

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/telegram/webhook"}'

​

4. Start Conversation

1. Find your bot in Telegram (search for the username you created)
2. Send /start to initialize
3. Begin chatting with Praxos

​

Bot Commands

​

Advanced Features

​

Group Chats

1. Add bot to group as member
2. Grant admin permissions (optional, for better functionality)
3. Mention bot using @YourBotName to interact
4. Configure group-specific settings

​

Inline Keyboards

Would you like to schedule this?
[Yes, 9 AM] [Yes, 2 PM] [No, thanks]

​

File Handling

• Documents - PDFs, Word docs, text files
• Images - JPG, PNG (with OCR support)
• Voice Messages - Audio transcription
• Videos - Metadata extraction

​

Rich Formatting

• Bold, italic, code
• Links and mentions
• Code blocks with syntax highlighting

​

Configuration Options

​

Environment Variables

# Required
TELEGRAM_BOT_TOKEN=your_bot_token

# Optional
TELEGRAM_WEBHOOK_URL=https://your-domain.com/telegram/webhook
TELEGRAM_MAX_MESSAGE_LENGTH=4096
TELEGRAM_PARSE_MODE=Markdown  # or HTML

​

User Preferences

• Response length preference
• Notification settings
• Default timezone
• Language preference

​

Security

​

Bot Token Security

• Store token in environment variables
• Use Azure Key Vault in production
• Rotate tokens if compromised

​

User Privacy

• All conversations are private by default
• User data is isolated per user
• Praxos never shares messages with other users

​

Rate Limiting

• 30 messages per second per bot
• 20 messages per minute per chat
• Praxos automatically queues and throttles

​

Troubleshooting

​

Bot Not Responding

# Verify token is set
echo $TELEGRAM_BOT_TOKEN

# Test token validity
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

# Local development
tail -f logs/hetairos.log | grep telegram

# Kubernetes
kubectl logs -f deployment/hetairos | grep telegram

​

Webhook Issues

curl "https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo"

• SSL certificate issues (webhook requires HTTPS)
• Firewall blocking incoming requests
• Incorrect webhook URL

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"

​

Message Formatting Errors

• Use parse_mode=Markdown for Markdown formatting
• Escape special characters: _, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !
• Or use HTML mode with proper tags

​

Best Practices

​

User Experience

• Quick Responses - Send typing indicators for long operations
• Clear Messages - Format responses clearly with proper structure
• Interactive Elements - Use inline keyboards for common actions
• File Support - Accept multiple file types

​

Performance

• Async Operations - All Telegram API calls are async
• Connection Pooling - Reuse HTTP connections
• Retry Logic - Automatic retries for transient failures
• Caching - Cache user context to reduce database calls

​

Monitoring

• Message processing time
• Error rates
• Active users
• API call volumes

​

Example Interactions

​

Simple Query

User: What's the weather like?
Praxos: Let me check the weather for you...
Praxos: Current weather in San Francisco:
         🌤️ Partly cloudy, 68°F
         Humidity: 65%
         Wind: 8 mph NW

​

Task Creation

User: Remind me to call John tomorrow at 2pm
Praxos: I'll remind you tomorrow at 2:00 PM to call John.
         [View Reminders] [Edit] [Cancel]

​

File Processing

User: [Sends PDF document]
Praxos: Received "Q4_Report.pdf" (2.3 MB)
         Processing document...

         Summary:
         - 45 pages
         - Q4 revenue: $2.3M
         - Key metrics improved 23% YoY

         [Full Summary] [Ask Questions] [Save to Notion]

​

Next Steps