> ## Documentation Index > Fetch the complete documentation index at: https://docs.mypraxos.com/llms.txt > Use this file to discover all available pages before exploring further. # Telegram Integration > Connect Praxos with Telegram for fast, secure messaging ## 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](https://t.me/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: ```bash theme={null} TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz ``` ### 3. Set Webhook (Production) For production deployments, configure a webhook: ```bash theme={null} curl -X POST "https://api.telegram.org/bot/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: | Command | Description | | ----------- | --------------------------------------- | | `/start` | Initialize bot and show welcome message | | `/help` | Display available commands | | `/settings` | Configure preferences | | `/history` | View conversation history | | `/clear` | Clear 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 ```bash theme={null} # 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** ```bash theme={null} # Verify token is set echo $TELEGRAM_BOT_TOKEN # Test token validity curl "https://api.telegram.org/bot/getMe" ``` **Check Logs** ```bash theme={null} # Local development tail -f logs/hetairos.log | grep telegram # Kubernetes kubectl logs -f deployment/hetairos | grep telegram ``` ### Webhook Issues **Verify Webhook Status** ```bash theme={null} curl "https://api.telegram.org/bot/getWebhookInfo" ``` **Common Problems** * SSL certificate issues (webhook requires HTTPS) * Firewall blocking incoming requests * Incorrect webhook URL **Delete Webhook (for local dev)** ```bash theme={null} curl -X POST "https://api.telegram.org/bot/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 Explore what Praxos can do Connect additional services