Commands

The Telegram interface implements a robust command system that handles user interactions through a type-safe, extensible architecture.

Command Architecture

Core Components

// Command Handler Interface
interface CommandHandler {
  name: string;
  description: string;
  adminOnly?: boolean;
  groupOnly?: boolean;
  dmOnly?: boolean;
  execute(context: CommandContext, agent: Agent): Promise<CommandResponse>;
}

// Command Context
interface CommandContext {
  userId: number;
  chatId: number;
  args: string;
  message: TelegramMessage;
  telegram: Telegram;
}

// Command Response
interface CommandResponse {
  text?: string;
  success: boolean;
  keyboard?: {
    inline_keyboard: Array<Array<{
      text: string;
      url?: string;
      callback_data?: string;
    }>>;
  };
}

Command Registry

The command registry manages command registration and execution:

class CommandRegistry {
  private commands: Map<string, CommandHandler>;

  register(handler: CommandHandler): void;
  getCommand(name: string): CommandHandler | undefined;
  getAllCommands(): CommandHandler[];
  executeCommand(
    name: string, 
    context: CommandContext, 
    agent: Agent
  ): Promise<CommandResponse>;
}

Available Commands

System Commands

1. Start Command

• Usage: /start

• Description: Initializes bot interaction

• Access: All users

2. Help Command

• Usage: /help

• Description: Displays available commands

• Access: All users

3. Admin Command

• Usage: /admin [action]

• Description: Administrative controls

• Access: Admin only

Content Generation

1. Image Commands

• Usage: /img [prompt]

• Description: Generates images using DALL-E

• Access: All users

2. Meme Command

• Usage: /meme [text]

• Description: Creates memes

• Access: All users

3. Random Command

• Usage: /random

• Description: Generates random illustrations

• Access: All users

Market Data

1. DEX Command

• Usage: /dex [token]

• Description: Fetches DEX prices

• Access: All users

2. Gecko Command

• Usage: /gecko [token]

• Description: Gets CoinGecko data

• Access: All users

3. Ticker Command

• Usage: /ticker [symbol]

• Description: Real-time price data

• Access: All users

Social Features

1. Tweet Command

• Usage: /tweet [content]

• Description: Posts to Twitter

• Access: All users

2. Message Command

• Usage: /msg [text]

• Description: Formats social messages

• Access: All users

Agent Management

1. Model Command

• Usage: /model [preferences]

• Description: Sets model preferences

• Access: All users

2. Spawn Command

• Usage: /spawn

• Description: Creates new agent instances

• Access: Admin only

Command Implementation

1. Basic Command Structure

const exampleCommand: CommandHandler = {
  name: 'example',
  description: 'Example command description',
  adminOnly: false,
  
  async execute(context: CommandContext, agent: Agent): Promise<CommandResponse> {
    return {
      success: true,
      text: 'Command executed successfully'
    };
  }
};

2. Command Registration

// Register commands
function registerCommands() {
  const commands = [
    startCommand,
    imgCommand,
    dexCommand,
    geckoCommand,
    tickerCommand,
    helpCommand,
    memeCommand,
    adminCommand,
    tweetCommand,
    randomCommand,
    msgCommand,
    weatherCommand,
    modelCommand,
    spawnCommand
  ];

  for (const command of commands) {
    commandRegistry.register(command);
  }
}

Command Execution Flow

1. Message Reception

   • Webhook receives message

   • Command pattern identified

2. Command Processing

   • Registry locates handler

   • Context created

   • Agent configuration loaded

3. Execution

   • Handler executes command

   • Response generated

   • Metrics recorded

4. Response Handling

   • Success/failure determined

   • Response formatted

   • Message sent to user

Command Metrics

interface CommandMetrics {
  command: string;
  userId: number;
  chatId: number;
  duration: number;
  success: boolean;
  error?: string;
  timestamp: number;
}

Error Handling

1. Command Errors

try {
  const response = await handler.execute(context, agent);
  // Success handling
} catch (error) {
  // Error metrics stored
  return {
    success: false,
    text: `❌ Error executing command "${name}"`
  };
}

2. Rate Limiting

• Command cooldowns

• User restrictions

• Group limits

Best Practices

1. Command Design

• Clear, single responsibility

• Proper error handling

• Type safety

• Performance optimization

2. Implementation

• Consistent response format

• Proper validation

• Metric tracking

• Clear documentation

3. Security

• Access control

• Input validation

• Rate limiting

• Error handling

Related Documentation

• Telegram Setup

• Agent System

• Market Data