mattata

A feature-rich Telegram group management and utility bot, written in Lua.

Features

• Group Administration - Ban, kick, mute, warn, tempban, tempmute, promote, demote, trust
• Federation System - Cross-group ban management with federated admin networks
• Captcha Verification - Challenge new members with built-in or custom captcha
• Anti-Spam - Rate limiting, word filters, link filtering, auto-delete
• 100+ Plugins - Weather, translate, search, currency, Wikipedia, AI chat, and more
• Async HTTP - Non-blocking HTTP client for plugin API calls via copas
• Stored Procedures - All database operations use PostgreSQL stored procedures
• Forum Topics - Full support for forum topic management and slow mode
• Reaction Karma - Track karma via message reactions
• RSS Feeds - Subscribe to and monitor RSS/Atom feeds
• Scheduled Messages - Queue messages for future delivery
• Inline Queries - Inline search and sharing across chats
• QR Codes - Generate QR codes from text
• Multi-Language - 10 language packs included (EN, DE, AR, PL, PT, TR, Scottish)
• PostgreSQL + Redis - PostgreSQL for persistent data, Redis for caching
• Hot-Reloadable Plugins - Reload plugins without restarting the bot
• Docker Ready - One command deployment with Docker Compose

Quick Start (Docker)

cp .env.example .env
# Edit .env and set BOT_TOKEN
docker compose up -d

Quick Start (Manual)

Prerequisites

• Lua 5.3+
• LuaRocks
• PostgreSQL 14+
• Redis 7+

Installation

# Install Lua dependencies
luarocks install telegram-bot-lua
luarocks install pgmoon
luarocks install redis-lua
luarocks install dkjson
luarocks install luautf8

# Configure
cp .env.example .env
# Edit .env with your settings

# Start
lua main.lua

Upgrading from v1.5

If you are upgrading from mattata v1.5, the migration is automatic. On first boot, mattata v2 detects v1.5 data and imports it into the new schema.

What gets migrated

• Chat settings (antilink, welcome, captcha, max warnings, etc.)
• Welcome messages
• Rules
• Warnings (per-user warning counts)
• Disabled plugins (with name mapping to v2 plugin names)
• Filters (word filters with actions)
• Triggers (auto-responses)
• Bans (group blocklist entries)
• Configuration (configuration.lua converted to .env format)

How it works

1. On startup, mattata scans Redis for v1-era key patterns and checks for configuration.lua
2. If v1 data is found, it imports everything into PostgreSQL via a single transaction
3. The migration is recorded in schema_migrations so it only runs once
4. After success, v1 Redis keys are cleaned up and configuration.lua is renamed to configuration.lua.v1.bak

Prerequisites

• Your v1.5 Redis instance must still be accessible (same host/port/db)
• PostgreSQL must be running and configured in .env (or the migration will create .env from configuration.lua)

Config mapping reference

| v1 (configuration.lua) | v2 (.env) | |---------------------------|-------------| | bot_token | BOT_TOKEN | | admins | BOT_ADMINS | | redis.host | REDIS_HOST | | redis.port | REDIS_PORT | | redis.password | REDIS_PASSWORD | | keys.lastfm | LASTFM_API_KEY | | keys.youtube | YOUTUBE_API_KEY | | keys.weather | OPENWEATHERMAP_API_KEY | | keys.spotify_client_id | SPOTIFY_CLIENT_ID | | keys.spotify_client_secret | SPOTIFY_CLIENT_SECRET | | keys.spamwatch | SPAMWATCH_TOKEN | | log_channel / log_chat | LOG_CHAT |

Configuration

All configuration is managed through environment variables. See .env.example for the full reference.

Required

| Variable | Description | |----------|-------------| | BOT_TOKEN | Telegram Bot API token from @BotFather |

Optional API Keys

| Variable | Description | Used By | |----------|-------------|---------| | LASTFM_API_KEY | Last.fm API key | /lastfm, /np | | YOUTUBE_API_KEY | YouTube Data API v3 key | /youtube | | SPOTIFY_CLIENT_ID | Spotify app client ID | /spotify | | SPOTIFY_CLIENT_SECRET | Spotify app client secret | /spotify | | SPAMWATCH_TOKEN | SpamWatch API token | Anti-spam | | OPENAI_API_KEY | OpenAI API key | /ai | | ANTHROPIC_API_KEY | Anthropic API key | /ai |

Architecture

mattata/
├── main.lua                    # Entry point
├── src/
│   ├── core/                   # Framework modules
│   │   ├── config.lua          # .env configuration reader
│   │   ├── loader.lua          # Plugin discovery & hot-reload
│   │   ├── router.lua          # Event dispatch
│   │   ├── middleware.lua       # Middleware pipeline
│   │   ├── database.lua        # PostgreSQL (pgmoon)
│   │   ├── redis.lua           # Redis connection
│   │   ├── http.lua            # Async HTTP client (copas)
│   │   ├── permissions.lua     # Admin/mod/trusted checks
│   │   ├── session.lua         # Redis session/cache management
│   │   ├── i18n.lua            # Language manager
│   │   └── logger.lua          # Structured logging
│   ├── middleware/              # Middleware chain
│   ├── plugins/                # Plugin categories
│   │   ├── admin/              # Group management (35+ plugins)
│   │   ├── utility/            # Tools & info (33+ plugins)
│   │   ├── fun/                # Entertainment (16 plugins)
│   │   ├── media/              # Media search (7 plugins)
│   │   └── ai/                 # LLM integration
│   ├── db/migrations/          # PostgreSQL schema migrations
│   ├── languages/              # 10 language packs
│   └── data/                   # Static data (slaps, join messages)
├── docker-compose.yml
├── docker-compose.matticate.yml
├── Dockerfile
└── .env.example

Plugin Development

Plugins follow a simple contract:

local plugin = {}
plugin.name = 'myplugin'
plugin.category = 'utility'
plugin.description = 'Does something useful'
plugin.commands = { 'mycommand', 'alias' }
plugin.help = '/mycommand <args> - Does the thing.'

function plugin.on_message(api, message, ctx)
    return api.send_message(message.chat.id, 'Hello!')
end

return plugin

Add your plugin to the category's init.lua manifest and it will be auto-loaded.

License

MIT License - see LICENSE for details.

Credits

Created by Matt Hesketh.