Alita Robot 🤖

Alita is a powerful, modern Telegram group management bot built with Go and the Gotgbot library. Designed for speed, reliability, and extensive customization, Alita provides comprehensive moderation tools for Telegram communities of any size.

📋 Table of Contents

• Features
• Quick Start
• One-Click Deploy
• Installation
• Docker (Recommended)
• Binary Release
• Build from Source
• Configuration
• Bot Commands
• Development
• Contributing
• License

✨ Features

📊 Performance & Optimization

• Parallel Bulk Processing: High-performance batch operations for filters, blacklists, and warnings
• Worker Pool Architecture: Efficient concurrent task processing with rate limiting
• Smart Caching: Redis-backed caching with stampede protection and TTL management
• Resource Monitoring: Automatic detection and alerting for memory/goroutine issues
• Performance Analytics: Built-in statistics collection and performance tracking

🛡️ Admin & Moderation

• User Management: Ban, mute, kick, and warn users with customizable actions
• Permission System: Granular permission control for admins
• Anti-Spam: Configurable flood control and spam detection
• Blacklist: Word and sticker filtering with pattern matching

💬 Messaging & Content

• Welcome/Goodbye: Customizable greeting messages with variables
• Filters: Keyword-triggered auto-responses with regex support
• Notes: Save and retrieve formatted messages
• Pins: Manage pinned messages with anti-spam protection
• Locks: Control message types (links, forwards, media, etc.)

🔧 Technical Excellence

• Performance: Built with Go for blazing-fast response times
• Cache: Redis with TTL support and stampede protection
• Database: PostgreSQL with connection pooling and batch operations
• Deployment Modes: Support for both polling and webhook modes
• Multi-Language: i18n support with YAML locale files
• Monitoring: Built-in resource monitoring and health checks

🚀 Modern Architecture

• Fully Asynchronous: Non-blocking operations throughout
• Repository Pattern: Clean separation of concerns
• Middleware System: Extensible command decorators
• Graceful Shutdown: Proper cleanup and connection handling
• Docker Ready: Multi-architecture images for easy deployment
• Worker Pools: Concurrent processing with configurable worker pools
• Batch Operations: Optimized bulk database operations with parallel processing
• Performance Monitoring: Built-in metrics collection and analysis

🚀 Quick Start

Get Alita running in under 5 minutes!

Prerequisites

• Docker and Docker Compose installed
• PostgreSQL database (or use the included one)
• Redis instance (or use the included one)
• Telegram Bot Token from @BotFather

Step 1: Clone the Repository

git clone https://github.com/divkix/Alita_Robot.git
cd Alita_Robot

Step 2: Configure Environment

cp sample.env .env
# Edit .env with your configuration
nano .env

Required variables:

BOT_TOKEN=your_bot_token_from_botfather
OWNER_ID=your_telegram_user_id
MESSAGE_DUMP=-100xxxxxxxxx  # Your log channel
DATABASE_URL=postgres://postgres:password@postgres:5432/alita_robot
REDIS_ADDRESS=redis:6379

Step 3: Run with Docker

docker compose up -d

That's it! Your bot should now be running. Check the logs:

docker compose logs -f alita

Interact with Your Bot

Open Telegram and search for your bot username to start using it!

Note: After deploying, configure the required environment variables (BOT_TOKEN, OWNER_ID, MESSAGE_DUMP) in your platform's dashboard.

Platform-specific notes:

• Render: PostgreSQL and Redis are automatically provisioned. Free tier includes 750 hours/month.
• Railway: PostgreSQL and Redis are included in the template.
• Heroku: Requires paid dynos ($5/mo) + PostgreSQL Essential ($5/mo) + Redis Mini ($3/mo). All addons are auto-configured.

💻 Installation

Docker (Recommended)

We provide official Docker images at ghcr.io/divkix/alita_robot for easy deployment.

Using Docker Compose (Full Stack)

This includes PostgreSQL, Redis, and the bot:

# Clone the repository
git clone https://github.com/divkix/Alita_Robot.git
cd Alita_Robot

# Configure environment
cp sample.env .env
# Edit .env with your settings

# Start all services
docker compose up -d

# View logs
docker compose logs -f alita

# Stop services
docker compose down

Note: Database migrations run automatically in Docker (AUTO_MIGRATE=true).

Optional: To run a local Telegram Bot API server for faster file handling, use the compose profile and set API_SERVER in your .env:

# .env
API_SERVER=http://telegram-bot-api:8081
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash

# Start with profile
docker compose --profile local-bot-api up -d

Using Docker Run (Bot Only)

If you have existing PostgreSQL and Redis instances:

docker run -d \
  --name alita-bot \
  --restart unless-stopped \
  -e BOT_TOKEN="your_bot_token" \
  -e DATABASE_URL="your_postgres_url" \
  -e REDIS_ADDRESS="your_redis_address" \
  -e OWNER_ID="your_telegram_id" \
  -e MESSAGE_DUMP="-100xxxxxxxxx" \
  ghcr.io/divkix/alita_robot:latest

Binary Release

Download pre-built binaries for your platform:

1. Visit the Releases page
2. Download the appropriate binary for your OS/architecture:
3. Linux: alita_robot_*_linux_amd64.tar.gz or _arm64
4. macOS: alita_robot_*_darwin_amd64.tar.gz or _arm64

5. Windows: alita_robot_*_windows_amd64.zip

6. Extract and run:

# Linux/macOS
tar -xzf alita_robot_*.tar.gz
chmod +x alita_robot
./alita_robot

# Windows
# Extract the zip file and run alita_robot.exe

Build from Source

Prerequisites

• Go 1.26 or higher
• PostgreSQL 14+
• Redis 6+
• Make (optional)

Build Steps

# Clone the repository
git clone https://github.com/divkix/Alita_Robot.git
cd Alita_Robot

# Install dependencies
go mod download

# Build the binary
go build -o alita_robot .

# Or use make
make build

# Run the bot
./alita_robot

# (Recommended) Run database migrations before the first run
# Provide your Postgres connection via env vars:
#   PSQL_DB_HOST, PSQL_DB_NAME, PSQL_DB_USER, PSQL_DB_PASSWORD
# Optional: PSQL_DB_PORT (default 5432), PSQL_DB_SSLMODE (default require)
make psql-migrate

Development Build

# Run with hot reload (requires air)
go install github.com/cosmtrek/air@latest
air

# Or use make
make run

⚙️ Configuration

Environment Variables

Alita uses environment variables for configuration. Create a .env file in the project root:

Required Variables

Optional Variables

See sample.env for the complete list of configuration options including database pool tuning, worker pool sizes, monitoring, and performance settings.

Webhook Mode (Production)

For production deployments, webhook mode provides better performance and lower resource usage than polling. Alita supports webhooks with Cloudflare Tunnel for easy setup behind firewalls.

Prerequisites

• Cloudflare account with a domain added to Cloudflare
• Docker and Docker Compose installed

Step 1: Create Cloudflare Tunnel

1. Go to Cloudflare Zero Trust Dashboard
2. Navigate to Networks > Tunnels
3. Click Create a tunnel → Choose Cloudflared
4. Name your tunnel (e.g., alita-telegram-bot)
5. Copy the tunnel token from the command shown (the long string after --token)

Step 2: Configure Public Hostname

1. In your tunnel dashboard, go to Public Hostnames tab
2. Click Add a public hostname
3. Configure:
4. Subdomain: alita-bot (or your preference)
5. Domain: Select your domain
6. Service: http://alita:8080
7. Path: /webhook/your-secret (replace with your actual WEBHOOK_SECRET)

Step 3: Environment Configuration

Create your .env file with webhook settings:

# Bot Configuration
BOT_TOKEN=your_bot_token_here
OWNER_ID=your_telegram_user_id
MESSAGE_DUMP=-100xxxxxxxxx

# Database Configuration
DATABASE_URL=postgres://postgres:password@postgres:5432/alita_robot?sslmode=disable
REDIS_ADDRESS=redis:6379
REDIS_PASSWORD=your_redis_password

# Webhook Configuration
USE_WEBHOOKS=true
WEBHOOK_DOMAIN=https://alita-bot.yourdomain.com
WEBHOOK_SECRET=your-random-secret-string-here
HTTP_PORT=8080

# Cloudflare Tunnel
CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiNzU1...your-tunnel-token-here

Step 4: Enable Cloudflare Tunnel in Docker

Uncomment the cloudflared service in your docker-compose.yml:

# Uncomment this section for webhook mode
cloudflared:
  image: cloudflare/cloudflared:latest
  container_name: alita-cloudflared
  environment:
    - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}
  command: tunnel --no-autoupdate run
  restart: unless-stopped
  depends_on:
    - alita
  deploy:
    resources:
      limits:
        memory: 128M
        cpus: "0.1"

Step 5: Register Webhook with Telegram

After your bot is running, register the webhook URL with Telegram:

```bash

Replace YOUR_BOT_TOKEN with your actual b