Setup

Lillo's primary interface is implemented through the Telegram Bot API, providing a robust and scalable chatbot infrastructure.

Overview

The Telegram interface is built on:

• Telegraf.js for bot interactions

• Vercel Edge Functions for webhook handling

• Redis KV for state management

• PostgreSQL for persistent storage

Configuration

1. Bot Setup

// Environment Variables
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/webhook
TELEGRAM_ADMIN_IDS=123456789,987654321

2. Initialization

// Bot initialization
const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN);
const telegram = new Telegram(process.env.TELEGRAM_BOT_TOKEN);

// Webhook setup
await bot.telegram.setWebhook(process.env.TELEGRAM_WEBHOOK_URL);

Core Components

1. Bot Instance

interface BotInstance {
  bot: Telegraf;
  telegram: Telegram;
  activeAgent: Agent;
  lastAgentFetch: number;
}

2. Message Types

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

interface InlineKeyboard {
  inline_keyboard: Array<Array<{
    text: string;
    url?: string;
    callback_data?: string;
  }>>;
}

Features

1. Message Handling

• Message storage in PostgreSQL

• Chat history tracking

• Reply support

• Inline keyboard interactions

2. Admin Controls

• Role-based access control

• Admin command restrictions

• Group management features

3. Content Generation

• Image generation

• Random illustrations

• Photo message support

• Processing status updates

4. Integration Points

• OpenAI for responses

• KV storage for caching

• Database for persistence

• Command registry integration

Utilities

1. Message Formatting

// Social message formatting
formatSocialMessage(text: string): string

// User mention formatting
formatUserMention(user: TelegramUser): string

2. Media Handling

// Send photo message
sendTelegramPhotoMessage(
  chatId: number,
  photo: string,
  caption?: string
): Promise<void>

// Processing message
sendProcessingMessage(
  chatId: number,
  replyToMessageId?: number
): Promise<number>

Configuration Management

1. Agent Configuration

// Get active agent configuration
async function getActiveAgentCached(): Promise<Agent> {
  const now = Date.now();
  if (!activeAgent || now - lastAgentFetch > AGENT_CACHE_TTL) {
    activeAgent = await AgentConfigService.getActiveAgent();
    lastAgentFetch = now;
  }
  return activeAgent;
}

2. Bot Settings

interface BotSettings {
  token: string;
  adminIds: number[];
  allowedGroups: number[];
  webhookUrl: string;
  commands: Command[];
}

Security

1. Authentication

• Bot token validation

• Admin ID verification

• Group membership checks

2. Rate Limiting

• Message rate limits

• Command cooldowns

• API call restrictions

3. Access Control

// Check admin role
async function hasRequiredRole(
  userId: number,
  role: AdminRole
): Promise<boolean>

// Validate group
async function isAllowedGroup(
  chatId: number
): Promise<boolean>

Error Handling

1. Message Errors

• Invalid command handling

• API error recovery

• Rate limit management

2. Connection Issues

• Webhook retry logic

• Database reconnection

• API fallbacks

Performance

1. Caching Strategy

• Agent configuration caching

• Command result caching

• User data caching

2. Optimization

• Message batching

• Connection pooling

• Response streaming

Deployment

1. Vercel Setup

{
  "rewrites": [
    {
      "source": "/api/webhook",
      "destination": "/api/telegram/webhook"
    }
  ]
}

2. Environment Setup

# Development
vercel env pull .env.local

# Production
vercel env add TELEGRAM_BOT_TOKEN
vercel env add TELEGRAM_WEBHOOK_URL
vercel env add TELEGRAM_ADMIN_IDS

Related Documentation

• Command System

• Database Schema

• Agent Configuration