Mobile interaction with Amplifier sessions via Telegram bot
This collection enables bidirectional communication between your mobile device and Amplifier sessions through a Telegram bot, allowing you to:
- 📱 Receive real-time session updates on your phone
- 💬 Send input to active sessions from anywhere
- 🔐 Secure pairing with one-time codes
- 🚀 Simple setup in ~5 minutes
amplifier collection add git+https://github.com/ramparte/amplifier-collection-telegram-bridge@main- Message @BotFather on Telegram
- Send
/newbotand follow the prompts - Copy your bot token (format:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz) - Set it as an environment variable:
export TELEGRAM_BOT_TOKEN="your-bot-token-here"# Use the mobile profile
amplifier profile use telegram-bridge:mobile
# Start a session
amplifier run "write a blog post about Python testing"In the session (or in another terminal):
amplifier run "/telegram pair"This generates a pairing code like: SUNSET-1234
On your mobile device, message your bot:
/pair SUNSET-1234
You'll receive confirmation that you're paired. From now on, you'll receive all session updates on your phone!
- mobile.md: Complete Telegram bridge configuration
- Hook module for pushing updates
- Tool module for receiving input
- Secure pairing and authorization
- architecture.md: How the two modules work together
- security.md: Security model, threat analysis, and best practices
- troubleshooting.md: Common issues and solutions
The Telegram Bridge uses two modules working in concert:
Type: Non-blocking event observer Repo: amplifier-module-hooks-telegram-bridge
What it does:
- Observes session events (prompts, responses, tool executions)
- Formats them into readable messages
- Pushes to authorized Telegram users
- Non-blocking: Never delays session execution
Type: Polling input tool Repo: amplifier-module-tool-telegram-input
What it does:
- Polls Telegram for new messages
- Filters by authorized users
- Returns messages as tool results to session
- Manages pairing flow
Pairing Flow:
- User requests pairing from trusted session
- System generates one-time code (WORD-NNNN format, 5-minute expiry)
- User sends code to Telegram bot
- System verifies and adds user to whitelist
- All future interactions authorized
Authorization:
- Persistent whitelist in
.telegram_pairing.json - Shared between both modules
- Rate limiting (5 failed attempts → 1 hour block)
- All auth events logged
See context/security.md for detailed security analysis.
Use case: Keep track of long-running tasks while away from desk
# Start a long task
amplifier run "analyze these 100 documents and summarize"
# Go for lunch - updates arrive on your phone
# See progress: "Analyzing document 25/100..."
# Get final result: "Analysis complete. Summary: ..."Use case: Provide feedback or decisions from mobile
# Session asks for human input
# Notification arrives on phone: "Should I proceed with refactoring? (yes/no)"
# Reply from phone
yes
# Session continues with your inputUse case: Quick code reviews during commute
# Session: "I've implemented the authentication feature. Here's the code..."
# [Code snippet arrives on phone]
# You review and reply
Looks good, but add rate limiting to the login endpoint
# Session: "Good point, adding rate limiting..."# Required: Your Telegram bot token
export TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"Edit the profile to customize behavior:
Events to push (hook config):
events_to_push:
- "prompt:submit" # User prompts
- "prompt:complete" # Assistant responses
- "tool:post" # Tool results
- "provider:response" # LLM responsesPoll interval (tool config):
poll_interval: 5 # Seconds between polls (default: 5)
long_poll_timeout: 30 # Wait up to 30s for messagesPairing file location:
pairing_file: ".telegram_pairing.json" # Relative to session working directory# Generate pairing code
/telegram pair
# List authorized users
/telegram list
# Poll for input manually
/telegram poll/start - Welcome message
/help - Show available commands
/pair CODE - Complete pairing (e.g., /pair SUNSET-1234)
Telegram is not end-to-end encrypted for bot messages. This means:
- Telegram (the company) can see all messages
- Use for development/convenience, not sensitive data
- Don't send secrets, API keys, or PII through the bridge
- Development code (non-production)
- Open source projects
- Blog posts, documentation
- High-level progress monitoring
- Production secrets (API keys, passwords)
- Customer data (PII, PHI)
- Proprietary code (trade secrets)
- Compliance-regulated data (HIPAA, GDPR)
See context/security.md for comprehensive security guidance.
"Bot token not set"
# Set the environment variable
export TELEGRAM_BOT_TOKEN="your-token-here""Pairing code expired"
- Codes expire after 5 minutes
- Generate a new one:
/telegram pair
"Not authorized"
- Complete pairing flow first
- Check:
cat .telegram_pairing.json
Not receiving updates
- Verify hook module loaded (check logs)
- Test bot token:
curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe - Confirm you're in authorized users list
See context/troubleshooting.md for comprehensive troubleshooting guide.
The bridge uses a loose coupling architecture where both modules share state via a file:
┌──────────────────────────────────────┐
│ Session Event │
│ ↓ │
│ Hook observes (non-blocking) │
│ ↓ │
│ Check authorization (pairing.json) │
│ ↓ │
│ Push to Telegram │
└──────────────────────────────────────┘
┌──────────────────────────────────────┐
│ Session invokes tool │
│ ↓ │
│ Poll Telegram (long polling) │
│ ↓ │
│ Filter by authorized users │
│ ↓ │
│ Return as ToolResult │
└──────────────────────────────────────┘
Both read/write
↓
.telegram_pairing.json
(authorized users whitelist)
Key design decisions:
- Separate modules: Hook (observer) and Tool (poller) have different responsibilities
- File-based state: Simple, inspectable, persistent
- Non-blocking hook: Never delays session
- Rate limiting: Prevents brute force attacks
- Event logging: Full audit trail
See context/architecture.md for detailed architecture documentation.
- Hook: https://github.com/ramparte/-amplifier-module-hooks-telegram-bridge
- Tool: https://github.com/ramparte/amplifier-module-tool-telegram-input
Contributions welcome! Please:
- File issues in the appropriate repo (hook vs tool vs collection)
- Include debug information (see troubleshooting guide)
- Follow the security model for auth/pairing changes
- Test with real Telegram bot before submitting PR
# Install modules for local development
cd /path/to/hook-module
uv pip install -e .
cd /path/to/tool-module
uv pip install -e .
# Test with a real Telegram bot
export TELEGRAM_BOT_TOKEN="your-test-bot-token"
amplifier profile use telegram-bridge:mobile
amplifier run "test the bridge"Planned features:
- Webhook support (alternative to polling)
- Group chat support (authorized group members)
- Rich message formatting (code blocks, images)
- Custom event filtering per user
- Multi-session support (one bot, multiple sessions)
- Telegram Mini App for better UX
Community requests welcome! File issues with feature requests.
For non-sensitive monitoring: Yes For sensitive data: No (Telegram is not E2E encrypted)
Yes! Each user completes pairing flow independently. All authorized users receive updates.
Yes! Pair once per device, then all sessions using the mobile profile will push to you.
Messages are queued by Telegram (up to 24 hours). You'll receive them when you come back online.
Yes! Remove user from .telegram_pairing.json or generate new bot token.
This collection is Telegram-specific. Similar patterns could work for Discord, Slack, etc. (PRs welcome!)
MIT License - See module repositories for details.
- Issues: File in appropriate repo (see Development section)
- Security issues: Email [security contact]
- Questions: GitHub Discussions in collection repo
Built with:
- Amplifier - AI agent framework
- Telegram Bot API - Chat platform
Inspired by the need for mobile interaction with long-running AI tasks.
Get started: amplifier collection add git+https://github.com/ramparte/amplifier-collection-telegram-bridge@main