WebsiteCommunityDeploy your Lillo Agent

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

PreviousCommands

Last updated