Telegram Integration

Pilot provides a Telegram bot interface for conversational task submission, voice messages, image analysis, and real-time execution status. It’s the most interactive way to communicate with Pilot.

Setup

1. Create a Telegram Bot

1. Open Telegram and find @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token (format: 123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Get Your Chat ID

To find your Telegram user/chat ID:

1. Start a chat with your new bot
2. Send any message
3. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
4. Look for "chat":{"id":123456789} in the response

Or use @userinfobot to get your user ID.

3. Configure Pilot

# ~/.pilot/config.yaml
adapters:
  telegram:
    enabled: true
    bot_token: ${TELEGRAM_BOT_TOKEN}
    chat_id: "123456789"
    allowed_ids:
      - 123456789        # Your user ID
    project_path: /path/to/repo
    polling: true
    plain_text_mode: true

Configuration Reference

Forum Topics

Supergroups with Topics enabled route every message to a topic. Set message_thread_id to post notifications and approval prompts into one topic instead of General:

adapters:
  telegram:
    chat_id: "-1001234567890"
    message_thread_id: 12

The id is the middle segment of a link to any message in that topic — https://t.me/c/<chat>/<topic>/<msg>. Leave it unset for chats without Topics; sending a topic id to a non-forum chat is rejected by the Bot API.

Approval prompts addressed to an individual approver (where approvers[0] is a chat ID) go to that chat directly and ignore this setting. Alert channels take their own message_thread_id — see Alerts.

Replies follow the conversation

Replies to a message you sent — answers, plans, task confirmations, results — go back to the topic that message came from, whichever topic that is. message_thread_id is the default for messages Pilot starts on its own (task lifecycle notifications and alerts), not a ceiling on where replies can go.

Messages sent in a forum’s General thread are answered in General. In a supergroup without Topics enabled, replies are unaffected — the Bot API only accepts a topic for forum supergroups, so Pilot deliberately ignores the thread id of an ordinary reply chain rather than sending one that would be rejected.

Chat Modes

Pilot automatically detects your intent and responds in one of five modes:

Task Mode

Triggered by action-oriented messages:

"Add a logout button to the header"
"Fix the bug in user authentication"
"Create a new API endpoint for orders"

Pilot will:

1. Show a confirmation message with the task details
2. Wait for you to confirm (Execute/Cancel buttons)
3. Execute and create a PR
4. Report results back to the chat

Question Mode

Triggered by questions about the codebase:

"What handles authentication?"
"How does the payment flow work?"
"Where is the config loaded?"

Pilot will:

1. Explore the codebase (read-only)
2. Return a concise answer
3. Not make any changes

Research Mode

Triggered by research requests:

"Analyze the API response times"
"Research how competitors implement this feature"
"Investigate the memory usage patterns"

Pilot will:

1. Perform deep analysis
2. Return structured findings
3. Save results to .agent/research/

Planning Mode

Triggered by planning requests:

"Plan the implementation for user notifications"
"How should we approach adding caching?"
"Design the architecture for the new module"

Pilot will:

1. Explore the codebase
2. Draft an implementation plan
3. Offer Execute/Cancel buttons to proceed

If planning fails, Pilot shows a specific error message depending on the failure type:

• Timeout — planning exceeded the configured planning_timeout duration
• API error — the upstream LLM call failed
• Empty result — planning completed but produced no output

The timeout is controlled by the executor’s planning_timeout setting.

Chat Mode

Triggered by conversational messages:

"Hello"
"Thanks!"
"What can you do?"

Pilot responds conversationally without code execution.

Bot Commands

Voice Messages

Pilot supports voice transcription using OpenAI Whisper:

Enable Voice Support

adapters:
  telegram:
    transcription:
      backend: auto
      openai_api_key: ${OPENAI_API_KEY}

How It Works

1. Send a voice message to the bot
2. Pilot transcribes it using Whisper API
3. Shows you the transcription
4. Processes it as if you typed it

Supported Languages

Whisper automatically detects language. Pilot shows the detected language:

🎤 Transcribed (English):
Add error handling to the payment endpoint

Image Analysis

Send photos to Pilot for visual analysis:

1. Send a photo to the bot
2. Optionally add a caption with instructions
3. Pilot analyzes the image and responds

Use cases:

• Screenshot analysis
• UI mockup interpretation
• Error message screenshots
• Architecture diagrams

Multi-Project Support

Switch between configured projects:

/projects          # List all projects
/switch backend    # Switch to backend project
/project           # Show current project

Each chat maintains its own active project. When you submit a task, it is always routed to the currently active project — use /switch to change context before submitting.

Task Confirmation

When you submit a task, Pilot shows a confirmation:

📋 New Task

TG-1234567890
"Add logout button to header"

Project: pilot
📁 /path/to/repo

[✅ Execute]  [❌ Cancel]

You can:

• Click Execute or reply “yes” to proceed
• Click Cancel or reply “no” to abort
• Tasks expire after 5 minutes without response

Progress Updates

During execution, Pilot updates the progress message:

🔄 Task TG-1234567890
━━━━━━━━░░ 80%

🔨 Implementing changes...

The progress bar updates in real-time as phases complete.

Ephemeral Tasks

Pilot automatically detects ephemeral tasks (commands that shouldn’t create PRs):

"Run the tests"
"Start the dev server"
"Check the build"

These execute without PR creation. Override with /pr <task> to force PR.

Quick Patterns

Type these shortcuts for common operations:

Rate Limiting

Protect against abuse with per-user rate limits:

rate_limit:
  enabled: true
  messages_per_minute: 20
  tasks_per_hour: 10
  burst_size: 5

When exceeded, users receive a warning message and must wait.

LLM Intent Classification

For better intent detection, enable LLM classification:

llm_classifier:
  enabled: true
  api_key: ${ANTHROPIC_API_KEY}
  timeout_seconds: 2
  history_size: 10
  history_ttl: 30m

Benefits:

• More accurate intent detection
• Context-aware classification
• Better handling of ambiguous messages

Falls back to regex-based detection if LLM fails.

Inline Keyboards

Pilot uses Telegram inline keyboards for interactions:

• Execute/Cancel: Task confirmation
• Project switching: Quick project selection
• Voice setup: Transcription configuration

Singleton Mode

Only one Pilot instance can poll the same bot:

if err := handler.CheckSingleton(ctx); err == telegram.ErrConflict {
    log.Fatal("Another Pilot instance is already running")
}

If you see a 409 error, check for other running instances.

Notifications

Pilot can send proactive notifications to your chat:

• Task completion
• PR ready for review
• Execution failures
• Daily briefs

Configure via daily_brief.channels:

daily_brief:
  channels:
    - type: telegram
      channel: "123456789"

Security Considerations

Allowed IDs

Always configure allowed_ids:

allowed_ids:
  - 123456789        # Your user ID
  - 987654321        # Team member
  - -1001234567890   # Group chat ID

Group chat IDs are negative numbers.

Token Security

• Never commit bot tokens to version control
• Use environment variables
• Rotate tokens if compromised
• Consider using separate bots for dev/prod

Rate Limiting

Enable rate limiting for production:

rate_limit:
  enabled: true
  messages_per_minute: 20
  tasks_per_hour: 10

Team Member Resolution

For multi-user deployments with RBAC:

adapters:
  telegram:
    # ... other config ...
 
team:
  enabled: true
  team_id: engineering

Pilot maps Telegram user IDs to team members for access control.

Troubleshooting

Bot Not Responding

1. Verify bot token is correct
2. Check polling: true is set
3. Ensure no other instance is running (409 error)
4. Check your user ID is in allowed_ids
5. Look for errors in Pilot logs

Voice Not Working

1. Verify openai_api_key is set
2. Run /voice to check status
3. Check OpenAI API quota
4. Ensure audio format is supported (Telegram uses OGG)

Messages Not Authorized

1. Add your user ID to allowed_ids
2. For groups, add the group chat ID (negative number)
3. Restart Pilot after config changes

Progress Updates Not Showing

1. Check plain_text_mode setting
2. Verify message edit permissions
3. Look for rate limit errors
4. Check Telegram API connectivity

Task Timing Out

1. Default timeout is 30 minutes
2. Check for infinite loops in execution
3. Use /stop to cancel stuck tasks
4. Check executor timeout configuration

API Usage

Pilot uses these Telegram Bot API methods:

The bot uses long-polling (30 second timeout) for real-time message reception.