Skip to main content

Telegram Setup

Status: working. Telegram is the supported channel today, via the bridge script (bun scripts/poc-telegram.ts). A packaged setup wizard is on the roadmap.

Connect xops to Telegram for mobile access from anywhere.

Why Telegram?​

  • Mobile Access - Message your copilot from your phone
  • Push Notifications - Get alerts and morning briefings
  • Rich Formatting - Code blocks, markdown, and more
  • Free & Fast - No additional costs, instant delivery

Step 1: Create a Bot with BotFather​

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Choose a name (e.g., "My xops")
  4. Choose a username (must end in bot, e.g., my_xops_bot)
  5. Copy the API token - you'll need this!
BotFather: Done! Congratulations on your new bot.

Use this token to access the HTTP API:
7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
Keep Your Token Secret

Never share your bot token publicly. Anyone with the token can control your bot.

Step 2: Configure xops​

During Setup​

When running xops setup, select "Yes" when asked about Telegram:

? Enable Telegram bot? Yes
? Enter Telegram bot token (from @BotFather) ▪▪▪▪▪▪▪▪▪▪
? Your Telegram username @yourusername

Manual Configuration​

Edit ~/.xops/config.yaml:

channels:
  telegram:
    enabled: true
    accounts:
      default:
        token: "7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"
        allowFrom:
          - "yourusername"
          - "teammate1"

Step 3: Start and Test​

xops gateway start

Look for:

✓ Telegram bot connected

Now open Telegram and message your bot:

You: /start

xops: Hello! I'm xops, your 24/7 DevOps copilot.

Access Control​

Allow Specific Users​

Only users in the allowFrom list can interact with the bot:

channels:
  telegram:
    accounts:
      default:
        token: "..."
        allowFrom:
          - "yourusername"      # Your username (without @)
          - "teammate"          # Team member
          - "123456789"         # User ID also works

To allow anyone to use your bot, omit the allowFrom field:

channels:
  telegram:
    accounts:
      default:
        token: "..."
        # No allowFrom = anyone can use it
Security Risk

Without access control, anyone who discovers your bot can use it to run commands on your infrastructure.

Bot Commands​

xops responds to these built-in commands:

CommandDescription
/startWelcome message and capabilities
/helpShow available commands
/statusCheck xops status
/memory <query>Search memory

You can also just send natural language messages:

You: Check if any pods are failing in production

xops: I'll check the pod status in the production namespace...

Multiple Accounts​

You can configure multiple Telegram bots (e.g., for different teams):

channels:
  telegram:
    enabled: true
    accounts:
      default:
        token: "${TELEGRAM_BOT_TOKEN}"
        allowFrom: ["admin1", "admin2"]

      readonly:
        token: "${TELEGRAM_READONLY_TOKEN}"
        allowFrom: ["viewer1", "viewer2"]
        # Future: readonly mode

Using Environment Variables​

Keep tokens out of config files:

channels:
  telegram:
    accounts:
      default:
        token: "${TELEGRAM_BOT_TOKEN}"

Then set the environment variable:

export TELEGRAM_BOT_TOKEN="7123456789:AAHdq..."
xops gateway start

Webhook Mode (Advanced)​

For production deployments, you can use webhooks instead of polling:

channels:
  telegram:
    accounts:
      default:
        token: "..."
        webhookUrl: "https://your-domain.com/webhook/telegram"

This requires:

  1. A public HTTPS endpoint
  2. SSL certificate (Let's Encrypt works)
  3. Configure your firewall/reverse proxy

Troubleshooting​

"Access denied" message​

Your username is not in the allowFrom list. Check:

  1. Spelling (no @ prefix needed)
  2. Case sensitivity (usernames are case-insensitive)
  3. Config file was saved and gateway restarted

Bot not responding​

  1. Check gateway is running: xops gateway status
  2. Verify token is correct
  3. Check gateway logs for errors
  4. Try /start to test basic connectivity

"Conflict: terminated by other getUpdates request"​

Another instance is using the same bot. Only one process can poll a bot at a time.

# Find and stop other instances
ps aux | grep xops
kill <pid>

Messages are delayed​

Polling mode checks for updates every few seconds. For real-time delivery, use webhook mode.

Best Practices​

  1. Use environment variables for tokens
  2. Restrict access to known usernames
  3. Use descriptive bot names like "DevOps-Prod" or "K8s-Helper"
  4. Enable notifications on your phone for the bot
  5. Create separate bots for production vs development

Next Steps​