📦

Overview

Telegram Gateway is a bidirectional bridge between the gmsg messaging system and Telegram. Allows Claude Code agents to send/receive Telegram messages via the gmsg interface.

The problem: AI agents work autonomously, often for hours. When an agent needs input, encounters a blocker, or completes a major task, there’s no way to notify the human immediately. Users have to manually check agent terminals or message logs to know what happened.

The solution: Telegram Gateway bridges gmsg (agent messaging) and Telegram (human messaging). Agents send messages through gmsg tagged for “Telegram” delivery, and the gateway forwards them to your Telegram account. You reply in Telegram, and the message routes back to the agent’s gmsg inbox.

Key Features

  • Telegram Bot Integration - Send and receive via Telegram Bot API
  • Message Format Translation - gmsg ↔ Telegram format conversion
  • User Authentication - Verify Telegram users before accepting messages
  • Real-Time Notifications - Instant push notifications from agents → mobile
  • Command Interface - Send commands to agents from Telegram (start, stop, query status)
  • Systemd Service - Production deployment as background service

Use Cases

Long-Running Task Notifications

Agent works overnight on a refactoring task. When complete (or when blocked), sends notification to your phone.

Mobile Agent Monitoring

Check agent fleet status from anywhere. Send command via Telegram: “Status report, all agents.” Get instant summary.

Urgent Blockers

Agent encounters error it can’t resolve. Sends Telegram message: “Deploy script failed: permission denied on /var/www. Need sudo access?” You respond from mobile, agent continues.

Remote Task Triggering

You’re away from desk. Send Telegram command: “EE, review the latest PR and report findings.” EE agent starts work, reports back via Telegram when done.

Team Coordination

Multiple humans monitoring agent fleet. Agents broadcast progress updates to Telegram group. Team sees what’s happening in real-time.

Architecture

┌──────────────────────────────┐
│   Claude Code Agents         │
│                              │
│  ┌────────┐    ┌────────┐   │
│  │Agent EE│    │Agent MM│   │
│  └───┬────┘    └───┬────┘   │
│      │             │         │
└──────┼─────────────┼─────────┘
       │             │
    ┌──▼─────────────▼──┐
    │   gmsg Server     │
    └─────────┬─────────┘
              │
    ┌─────────▼─────────┐
    │ Telegram Gateway  │
    │                   │
    │ ┌───────────────┐ │
    │ │  Format       │ │
    │ │  Translation  │ │
    │ └───────┬───────┘ │
    └─────────┼─────────┘
              │
    ┌─────────▼─────────┐
    │  Telegram Bot API │
    └─────────┬─────────┘
              │
       ┌──────▼──────┐
       │ Your Phone  │
       │  (Telegram) │
       └─────────────┘

Message Flow

Agent → Human:

  1. Agent sends gmsg message with receiver="telegram"
  2. Gateway polls gmsg for telegram-tagged messages
  3. Gateway translates to Telegram format
  4. Telegram Bot API delivers to your phone

Human → Agent:

  1. You send Telegram message to bot
  2. Gateway receives via Telegram Bot API webhook
  3. Gateway translates to gmsg format
  4. gmsg routes message to target agent’s inbox

Configuration

# telegram_gateway_config.yaml
telegram:
  bot_token: "YOUR_BOT_TOKEN"
  allowed_users:
    - telegram_user_id: 123456789
      name: "Your Name"

gmsg:
  server: "unix:/tmp/gmsg.sock"
  polling_interval: 5  # seconds

routing:
  default_agent: "EE"  # Default recipient if not specified
  broadcast_to_telegram: true  # Forward agent broadcasts

Message Format Examples

Agent notification:

🤖 Agent EE

✅ Task Complete

Refactoring complete:
- 47 files updated
- All tests passing
- PR ready for review

Next: Await human review

Agent blocker:

🤖 Agent MM

⚠️ Blocker

Cannot publish blog post:
Dev.to API returned 403 Forbidden

Possible cause: API key expired?

Need: New API key or permission check

Status query response:

🤖 Agent Fleet Status

EE: Active (52% context)
MM: Idle
Brand_Manager: Active (68% context)
MacR: Not running

Active tasks:
- EE: Homepage redesign review
- Brand_Manager: Product descriptions

What Makes It Different

vs. Email Notifications:

  • Real-time - Instant push, not polling
  • Two-way - Reply directly to agents
  • Mobile-native - Telegram optimized for mobile

vs. Slack/Discord Bots:

  • Agent-aware - Built for AI agent communication patterns
  • gmsg integration - Native to SW2 infrastructure
  • Lightweight - No workspace overhead

vs. SMS:

  • Rich formatting - Code blocks, markdown, multi-line
  • Free - No per-message costs
  • Command interface - Send structured commands, not just text

Tech Stack

  • Python - Gateway service
  • python-telegram-bot - Telegram Bot API client
  • gmsg - Message broker integration
  • systemd - Production deployment
  • YAML - Configuration

Status

Production — Deployed as systemd service, actively used for remote agent monitoring at Silver Wizard Software.

Internal Infrastructure: Telegram Gateway is production infrastructure developed for remote monitoring of SW2’s agent fleet. Available for licensing to organizations building agentic systems.

Security Considerations

  1. Bot token - Keep secure, don’t commit to repos
  2. User authentication - Whitelist allowed Telegram user IDs
  3. Message sanitization - Strip sensitive data before forwarding
  4. Rate limiting - Prevent spam to agents or Telegram API
  5. SSL/TLS - Telegram Bot API uses HTTPS

Best Practices

  1. Tag messages clearly - Use receiver="telegram" in gmsg
  2. Format for mobile - Short lines, clear structure, emojis for status
  3. Use commands sparingly - Telegram → agent commands should be high-level
  4. Test bot locally first - Use Telegram’s BotFather test environment
  5. Monitor gateway logs - Watch for failed deliveries or API errors

Deployment

# Install as systemd service
sudo cp telegram-gateway.service /etc/systemd/system/
sudo systemctl enable telegram-gateway
sudo systemctl start telegram-gateway

# Check status
sudo systemctl status telegram-gateway

# View logs
sudo journalctl -u telegram-gateway -f

Licensing

Telegram Gateway is internal production infrastructure available for licensing to organizations building multi-agent AI systems with remote monitoring needs.

Contact: silver.wizard001@proton.me for licensing inquiries.

Documentation

Support