SuperCharged-Claude-Code-Upgrade/dexto/examples/telegram-bot/README.md

Telegram Bot Example

This is a reference implementation showing how to integrate DextoAgent with Telegram using grammy. It demonstrates:

• Connecting to Telegram Bot API with long polling
• Processing messages and commands
• Handling inline queries for direct responses in any chat
• Handling image attachments
• Managing per-user conversation sessions
• Integrating tool calls with Telegram messages

⚠️ Important: This is a Reference Implementation

This example is provided to show how to build Telegram integrations with Dexto. While it works, it's not a production-ready bot and may lack:

• Advanced error recovery and retry logic
• Comprehensive logging and monitoring
• Scalability features for large deployments
• Webhook support (currently uses long polling only)
• Advanced rate limiting

Use this as a foundation to build your own customized Telegram bot!

Quick Start

1. Get Your Telegram Bot Token

1. Open Telegram and search for BotFather (verify it has the blue checkmark)
2. Send /start to begin a conversation
3. Send /newbot to create a new bot
4. Follow the prompts:
   • Give your bot a name (e.g., "Dexto AI Bot")
   • Give it a username ending in "bot" (e.g., "dexto_ai_bot")
5. BotFather will provide your token - save it for the next step

2. Set Up Your Environment Variables

Copy .env.example to .env:

cp .env.example .env

Edit .env and add:

1. Your Telegram Bot Token (required):

   TELEGRAM_BOT_TOKEN=your_token_here
   

2. Your LLM API Key (required):

   For OpenAI (default):

   OPENAI_API_KEY=your_openai_api_key_here
   

   Or use a different provider and update agent-config.yml:

   # ANTHROPIC_API_KEY=your_key_here
   # GOOGLE_GENERATIVE_AI_API_KEY=your_key_here
   

Get API Keys:

• OpenAI: https://platform.openai.com/account/api-keys
• Anthropic: https://console.anthropic.com/account/keys
• Google: https://ai.google.dev

3. Install Dependencies

Install the required dependencies:

pnpm install

4. Run the Bot

Start the bot:

pnpm start

You should see:

🚀 Initializing Telegram bot...
📡 Starting Telegram bot connection...
✅ Telegram bot is running! Start with /start command.

5. Test Your Bot

1. Open Telegram and search for your bot's username
2. Click "Start" or send /start command
3. You should see a welcome message with buttons

Usage

Commands

• /start - Display welcome message with command buttons and options
• /ask <question> - Ask a question (works in groups with prefix)
• /explain <topic> - Get detailed explanations of topics
• /summarize <text> - Summarize provided content
• /code <problem> - Get help with programming tasks
• /analyze <data> - Analyze information or data
• /creative <idea> - Brainstorm creatively on a topic

Features

Quick Command Buttons

When you send /start, the bot displays interactive buttons for each command. Click a button to start that interaction without typing a command!

Available command buttons:

• 💡 Explain
• 📋 Summarize
• 💻 Code
• ✨ Creative
• 🔍 Analyze

Text Messages

Send any message directly to the bot in DMs, and it will respond using the configured LLM with full conversation context.

Image Support

Send photos with optional captions, and the bot will analyze them using the agent's vision capabilities (for models that support vision).

Audio/Voice Messages

Send voice messages or audio files, and the bot will:

• Transcribe the audio (if model supports speech recognition)
• Analyze the audio content
• Use voice as context for responses

Supported audio formats: OGG (Telegram voice), MP3, WAV, and other audio formats your LLM supports.

Inline Queries

In any chat (without messaging the bot), use inline mode:

@your_bot_name What is the capital of France?

The bot will respond with a result you can send directly to the chat.

Session Management

• Reset Conversation - Use the 🔄 Reset button from /start to clear conversation history
• Help - Use the ❓ Help button to see all available features

Per-User Sessions

Each Telegram user gets their own isolated conversation session. Multiple users in a group chat will each have separate conversations, preventing cross-user context pollution.

Configuration

Adding Custom Prompts

The bot automatically loads prompts from your agent-config.yml file. These prompts appear as buttons in /start and can be invoked as slash commands.

To add a new prompt:

prompts:
  - type: inline
    id: mycommand       # Used as /mycommand
    title: "🎯 My Command"  # Button label
    description: "What this command does"
    prompt: "System instruction:\n\n{{context}}"  # Template with {{context}} placeholder
    category: custom
    priority: 10

Example prompts included:

Self-contained (execute immediately):

• /quick-start - Learn what the bot can do
• /demo - See tools in action

Context-requiring (ask for input):

• /summarize - Summarize content
• /explain - Detailed explanations
• /code - Programming help
• /translate - Language translation

Using prompts:

1. As slash commands: /summarize Your text here
2. As buttons:
   • Self-contained prompts execute immediately ⚡
   • Context-requiring prompts ask for input 💬
3. Smart detection: Bot automatically determines if context is needed
4. Dynamic loading: Prompts update when you restart the bot

Switching LLM Providers

The bot comes configured with OpenAI by default. To use a different provider:

1. Update agent-config.yml - Change the llm section:

   # For Anthropic Claude:
   llm:
     provider: anthropic
     model: claude-sonnet-4-5-20250929
     apiKey: $ANTHROPIC_API_KEY
   
   # For Google Gemini:
   llm:
     provider: google
     model: gemini-2.0-flash
     apiKey: $GOOGLE_GENERATIVE_AI_API_KEY
   

2. Set the API key in .env:

   ANTHROPIC_API_KEY=your_key_here
   # or
   GOOGLE_GENERATIVE_AI_API_KEY=your_key_here
   

Environment Variables

Create a .env file with:

• TELEGRAM_BOT_TOKEN (Required): Your bot's authentication token from BotFather
• OPENAI_API_KEY (Required for OpenAI): Your OpenAI API key
• ANTHROPIC_API_KEY (Optional): For using Claude models
• GOOGLE_GENERATIVE_AI_API_KEY (Optional): For using Gemini models
• TELEGRAM_INLINE_QUERY_CONCURRENCY (Optional): Max concurrent inline queries (default: 5)

Features

Session Management

Each Telegram user gets their own persistent conversation session during the bot's lifetime. Messages from different users don't interfere with each other.

Tool Notifications

When the LLM calls a tool (e.g., making an API call), the bot sends a notification message so users can see what's happening:

Calling get_weather with args: {...}

Inline Query Debouncing

Repeated inline queries are cached for 2 seconds to reduce redundant processing.

Concurrency Control

By default, the bot limits concurrent inline query processing to 5 to prevent overwhelming the system. Adjust via TELEGRAM_INLINE_QUERY_CONCURRENCY.

Architecture

Telegram Message
    ↓
startTelegramBot() wires up event handlers
    ↓
agent.run() processes the message
    ↓
Response sent back to Telegram
    ↓
agentEventBus emits events (tool calls, etc.)
    ↓
Tool notifications sent to chat

Transport Methods

Long Polling (Current)

The bot uses long polling by default. It continuously asks Telegram "any new messages?" This is:

• ✅ Simpler to implement
• ✅ Works behind firewalls
• ❌ More network overhead
• ❌ Slightly higher latency

Webhook (Optional)

For production use, consider implementing webhook support for better performance. This would require:

• A public URL with HTTPS
• Updating grammy configuration
• Setting up a reverse proxy if needed

Limitations

• No persistence across restarts: Sessions are lost when the bot restarts. For persistent sessions, implement a database layer.
• Long polling: Not ideal for high-volume bots. Consider webhooks for production.
• Per-deployment limits: The bot runs as a single instance. For horizontal scaling, implement clustering with a distributed session store.
• No button callbacks for advanced features: This example shows basic callback handling. Extend for more complex interactions.

Troubleshooting

Bot doesn't respond to messages

• Verify TELEGRAM_BOT_TOKEN is correct in .env
• Check that the bot is online by sending /start to BotFather
• Ensure the bot is running (npm start)

"TELEGRAM_BOT_TOKEN is not set"

• Check that .env file exists in the example directory
• Verify the token is correctly copied from BotFather

Timeout on inline queries

• Check TELEGRAM_INLINE_QUERY_CONCURRENCY setting
• The bot has a 15-second timeout for inline queries - if your LLM is slow, increase this in bot.ts

Image processing fails

• Ensure images are valid and not corrupted
• Check network connectivity for downloading images

Next Steps

To customize this bot:

1. Modify agent-config.yml:

   • Change the LLM provider/model
   • Add MCP servers for additional capabilities
   • Customize the system prompt

2. Extend bot.ts:

   • Add more commands
   • Implement webhook support
   • Add logging/monitoring
   • Add database persistence

3. Deploy:

   • Run on a server/VPS that stays online 24/7
   • Use process managers like PM2 to auto-restart on crashes
   • Consider hosting on platforms like Railway, Heroku, or AWS
   • Migrate to webhook transport for better scalability

Documentation

• grammY Documentation
• Telegram Bot API
• BotFather Commands
• Dexto Documentation
• Dexto Agent API

License

MIT