Commands

Overview

Lillo's chat system includes a comprehensive set of commands for managing conversations, interactions, and bot behavior. These commands provide granular control over chat behavior, message handling, bot responses, and agent configurations.

Core Commands

Message Control

/msg

• Description: Send a message to the community

• Usage: /msg <message>

• Access: DM only

• Example:

  /msg Hello everyone! Welcome to our community!

Chat Management

/settings

• Description: Configure chat settings

• Usage: /settings

• Access: Admin only

• Options:

  • Model preferences

  • Response style

  • Function permissions

  • Agent configuration

  • Rate limits

/clear

• Description: Clear recent chat history

• Usage: /clear [number]

• Access: Admin only

• Parameters:

  • number: Optional, number of messages to clear (default: 50)

Agent Management

/myagents

• Description: List and manage your agents

• Usage: /myagents

• Access: All users

• Features:

  • View active agents

  • Switch agents

  • Configure agent settings

/newagent

• Description: Create a new agent

• Usage: /newagent

• Access: Admin only

• Steps:

  1. Token verification

  2. Personality setup

  3. Social configuration

  4. Crypto settings

Function Integration

Image Generation

case "generate_image":
  return await generateAndSendImage(
    agent,
    chatId,
    prompt,
    messageId,
    userId
  );

Weather Data

case "get_weather":
  result = await handleWeatherRequest(
    agentConfig,
    location,
    chatId.toString()
  );

Market Data

case "getGeckoTokenData":
  response = await getGeckoTokenData(query);
  result = response.content;

Time Information

case "get_time":
  result = await handleTimeRequest(location);

Command Handling

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 Handler

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

Response Formatting

User Mentions

• Format: {mention:USER_ID:USER_NAME}

• Example: {mention:123456:John}

• Usage: Direct user references in responses

Message Structure

interface ChatHistoryEntry {
  messageId: number;
  userId: number;
  userFirstName: string;
  username?: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: number;
  chatId: number;
  replyToMessageId?: number;
  agentId: string;
}

Command Metrics

Metrics Collection

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

Storage

async function storeCommandMetrics(metrics: CommandMetrics) {
  // Store in KV for quick access
  const key = `metrics:cmd:${metrics.command}:${metrics.timestamp}`;
  await storeInKV(key, metrics);

  // Store in Postgres for long-term analysis
  await sql`
    INSERT INTO command_metrics (
      command, user_id, chat_id, duration,
      success, error, timestamp
    ) VALUES (
      ${metrics.command}, ${metrics.userId},
      ${metrics.chatId}, ${metrics.duration},
      ${metrics.success}, ${metrics.error},
      ${metrics.timestamp}
    );
  `;
}

Error Handling

Rate Limiting

if (!await canUseFunctions(userId, agent)) {
  errorMessage = '❌ Sorry, too many requests. Please allow a few seconds between function calling to prevent abuse.';
}

Content Policy

if (error.message.toLowerCase().includes('content policy')) {
  errorMessage = '❌ I cannot process that request due to content policy restrictions.';
}

Permission Errors

if (!await hasRequiredRole(userId, AdminRole.ADMIN)) {
  return {
    success: false,
    text: '❌ This command requires admin privileges.'
  };
}

Best Practices

1. Command Usage

   • Use commands in appropriate contexts

   • Follow rate limiting guidelines

   • Check command permissions

   • Validate input parameters

   • Handle all error cases

2. Message Formatting

   • Use proper mention syntax

   • Include necessary context

   • Follow response guidelines

   • Escape special characters

   • Handle markdown/HTML properly

3. Error Recovery

   • Handle errors gracefully

   • Provide clear error messages

   • Implement retry logic

   • Log failures appropriately

   • Maintain user experience

4. Performance

   • Cache command results

   • Use efficient queries

   • Implement timeouts

   • Handle concurrent requests

   • Monitor execution times

Related Documentation

• Chat Overview

• Command System

• Function Reference

• Agent Configuration