Telegram Integration

Run Maestro as a Telegram bot for mobile access to your AI agents.

Prerequisites

• Telegram account
• Maestro installed and configured

Setup

1. Create a bot with BotFather

   Open Telegram and message @BotFather:

   /newbot

   Follow the prompts:

   • Choose a name (e.g., “My Maestro Bot”)
   • Choose a username (must end in bot, e.g., my_maestro_bot)

   BotFather will give you a token like:

   123456789:ABCdefGHIjklMNOpqrsTUVwxyz

2. Add the token to your environment

   Edit your .env file:

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

3. Start the bot

   # Docker
   docker compose up -d telegram
   
   # Or local development
   npm run dev

4. Test it

   Open Telegram and message your bot:

   /start

   The bot should respond. Try a conversation:

   You: Hello!
   Bot: Hi! I'm your Maestro assistant. How can I help?
   
   You: What's 25 * 47?
   Bot: 25 * 47 = 1,175

Bot Commands

The Telegram bot responds to regular messages. You can also set up commands via BotFather:

/setcommands

Then provide:

start - Start the bot
help - Show help message
clear - Clear conversation history
cost - Show token usage

Group Chats

The bot works in group chats too:

1. Add the bot to a group
2. Make it an admin (or disable privacy mode in BotFather)
3. The bot responds to messages that mention it or reply to it

Note

In groups, each chat has its own session ID, so conversations are isolated per group.

Privacy Mode

By default, Telegram bots in groups only see:

• Messages that mention the bot
• Replies to the bot’s messages
• Commands

To see all messages, disable privacy mode in BotFather:

/setprivacy

Select “Disable”.

Caution

Disabling privacy mode means the bot receives all messages in groups. Only do this if you need the bot to participate in general conversation.

Deployment

Docker Compose

The default docker-compose.yml includes a telegram service:

services:
  telegram:
    build: .
    environment:
      - ANTHROPIC_API_KEY
      - TELEGRAM_BOT_TOKEN
    volumes:
      - ./data:/app/data
      - ./projects:/app/projects

Start it:

docker compose up -d telegram

Running Alongside API

You can run both Telegram and API services:

docker compose up -d

They share the same data directory and agent configurations.

Formatting

The bot supports Telegram’s markdown formatting:

• Bold: **text** or __text__
• Italic: *text* or _text_
• Code: `code`
• Code blocks: ```language\ncode\n```

The LLM’s responses are automatically formatted for Telegram.

Troubleshooting

Bot doesn’t respond

1. Check the token is correct in .env
2. Check logs: docker compose logs telegram
3. Verify the bot is running: docker compose ps

”Unauthorized” error

Your bot token is invalid. Get a new one from BotFather.

Messages not received in groups

Enable the bot as admin or disable privacy mode.

Slow responses

• Check your network connection
• The Anthropic API might be slow
• Large context (long conversations) takes longer

Security

• Keep your bot token secret
• Don’t commit .env to version control
• Consider restricting who can use the bot (not built-in, requires code changes)

Rate Limits

Telegram has rate limits:

• ~30 messages per second to different chats
• ~1 message per second to the same chat

Maestro handles these automatically, but very high usage might hit limits.