Skip to Content

Telegram Bot

TL;DR

The Telegram channel for @cmdop/bot uses grammy to connect your CMDOP machines to Telegram. Create a bot via @BotFather, configure the TelegramChannel with your bot token and allowed user IDs, then run commands like /shell, /agent, and /ls directly from Telegram. Supports MarkdownV2 formatting, chat mode, typing indicators, and permission manager integration.

Control your CMDOP machines directly from Telegram. Built on grammy .

How do I set up a Telegram bot?

  1. Create a bot via @BotFather 
  2. Get your bot token
  3. Get your Telegram user ID (use @userinfobot )

How do I install @cmdop/bot for Telegram?

# Install the @cmdop/bot package (Telegram adapter is included)
npm install @cmdop/bot

How do I use the Telegram channel?

// Import the hub and Telegram-specific channel adapter
import { IntegrationHub } from '@cmdop/bot';
import { TelegramChannel } from '@cmdop/bot/telegram';
 
// Create the hub with your CMDOP API key and default target machine
const hub = new IntegrationHub({
  apiKey: process.env.CMDOP_API_KEY!,
  machine: 'my-server',
});
 
// Add TelegramChannel with bot token and restrict to specific user IDs
hub.addChannel(new TelegramChannel({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  allowedUsers: [123456789],
}));
 
// Start the bot and begin listening for Telegram messages
hub.start();

What are the TelegramChannel options?

OptionTypeRequiredDescription
tokenstringYesTelegram bot token from @BotFather
allowedUsersnumber[]NoAllowed Telegram user IDs. Omit to allow all
chatModebooleanNoEnable chat mode (no /agent prefix needed)
timeoutnumberNoCommand timeout in milliseconds (default: 30000)

What are the IntegrationHub options?

OptionTypeRequiredDescription
apiKeystringYesCMDOP API key
machinestringNoDefault target machine
permissionsPermissionManagerNoPermission manager

What commands can I use in Telegram?

CommandDescription
/startWelcome message
/helpShow available commands
/shell <cmd>Execute shell command
/agent <task>Run AI agent task
/machine <hostname>Set target machine
/ls [path]List directory
/cat <path>Read file

What features does the Telegram channel support?

  • MarkdownV2 formatting with syntax highlighting
  • Typing indicators during long operations
  • User allowlist for security
  • Permission manager integration
  • Chat mode — type messages without /agent prefix

What environment variables do I need?

# Telegram bot token from @BotFather
export TELEGRAM_BOT_TOKEN="your-bot-token"
# Your CMDOP API key for authenticating with the CMDOP service
export CMDOP_API_KEY="cmdop_xxx"
# Default machine hostname to target for commands
export CMDOP_MACHINE="my-server"

How do I add permissions to my Telegram bot?

// Import PermissionManager and PermissionLevel alongside the hub and channel
import { IntegrationHub, PermissionManager, PermissionLevel } from '@cmdop/bot';
import { TelegramChannel } from '@cmdop/bot/telegram';
 
// Create a permission manager instance
const permissions = new PermissionManager();
// Grant full admin access to a specific Telegram user
permissions.addAdmin('telegram:123456789');
// Grant EXECUTE-level access to another user on a specific machine
permissions.grant({
  identity: 'telegram:555555555',
  machine: 'dev-server',
  level: PermissionLevel.EXECUTE,
});
 
// Pass the permission manager to the hub
const hub = new IntegrationHub({
  apiKey: process.env.CMDOP_API_KEY!,
  permissions,
});
 
// Add the Telegram channel (no allowedUsers needed — permissions handle access)
hub.addChannel(new TelegramChannel({
  token: process.env.TELEGRAM_BOT_TOKEN!,
}));
 
hub.start();

How do I create custom commands?

// Register a custom 'deploy' command that pulls, builds, and replies with output
hub.command('deploy', async (ctx) => {
  const { output } = await ctx.terminal.execute(
    'cd /app && git pull && npm run build'
  );
  await ctx.reply(output);
});
 
// Register a custom 'status' command that checks the systemd service
hub.command('status', async (ctx) => {
  const { output } = await ctx.terminal.execute('systemctl status app');
  await ctx.reply(output);
});

What does a full Telegram bot example look like?

// Full production-ready Telegram bot setup
import { IntegrationHub } from '@cmdop/bot';
import { TelegramChannel } from '@cmdop/bot/telegram';
 
// Create hub using environment variables for configuration
const hub = new IntegrationHub({
  apiKey: process.env.CMDOP_API_KEY!,
  machine: process.env.CMDOP_MACHINE,
});
 
// Parse ALLOWED_USERS from a comma-separated env var into numeric array
hub.addChannel(new TelegramChannel({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  allowedUsers: process.env.ALLOWED_USERS
    ?.split(',')
    .map(Number)
    .filter(Boolean),
}));
 
// Start the bot and log confirmation
hub.start().then(() => {
  console.log('Bot is running');
});
Last updated on
Overview