Skip to main content

​
Overview

Telegram is one of the most popular platforms for Praxos, offering rich features, speed, and security.

​
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

Add the token to your .env file: 
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

​
3. Set Webhook (Production)

For production deployments, configure a webhook: 
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"}'
For local development, Praxos uses polling mode automatically.

​
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

Built-in Telegram commands:
CommandDescription
/startInitialize bot and show welcome message
/helpDisplay available commands
/settingsConfigure preferences
/historyView conversation history
/clearClear conversation context

​
Advanced Features

​
Group Chats

Add Praxos to 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

Praxos can send interactive buttons: 
Would you like to schedule this?
[Yes, 9 AM] [Yes, 2 PM] [No, thanks]

​
File Handling

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

​
Rich Formatting

Praxos supports Telegram’s 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

Users can configure:
  • Response length preference
  • Notification settings
  • Default timezone
  • Language preference

​
Security

​
Bot Token Security

Never share your bot token publicly. Treat it like a password.
  • 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

Telegram’s limits:
  • 30 messages per second per bot
  • 20 messages per minute per chat
  • Praxos automatically queues and throttles

​
Troubleshooting

​
Bot Not Responding

Check Configuration 
# Verify token is set
echo $TELEGRAM_BOT_TOKEN

# Test token validity
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
Check Logs 
# Local development
tail -f logs/hetairos.log | grep telegram

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

​
Webhook Issues

Verify Webhook Status 
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo"
Common Problems
  • SSL certificate issues (webhook requires HTTPS)
  • Firewall blocking incoming requests
  • Incorrect webhook URL
Delete Webhook (for local dev) 
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

Track key metrics:
  • 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

Tools Overview

Explore what Praxos can do

Add More Integrations

Connect additional services