SuperSeriousBot

A modular, asynchronous, highly-configurable, plug and play Telegram bot built using the fantastic python-telegram-bot library.

Introduction

SuperSeriousBot is an asynchronous Telegram bot with modular commands, SQLite-backed state, and API-key-gated optional features.

✨ Features

Current command set includes:

• AI features: /ask, /edit, /tldr, /tr, /model, /thinking
• Object store + media: /set, /get, /dl, /gif, /meme, /joke
• Language + utility: /tl, /tts, /define, /ud, /calc, /book
• Group utilities: /remind, /habit, /summon, /highlight
• Stats + moderation: /stats, /gstats, /ustats, /seen, /block, /unblock, /whitelist
• Social graph: /friends
• Weather + quotes: /weather, /addquote, /quote

Notes:

• No standalone caption command. Image captioning is done by replying to an image/sticker with /ask.
• Most API-key commands are auto-disabled when keys are missing; some validate at runtime (for example /weather).
• Send /help to @SuperSeriousBot for the live command list.

🏗 Usage

Configuration

Before you can begin, you'll need to get a token and API keys for your bot. You can get the token from @BotFather.

Run the following command to generate an empty environment file:

$ git clone https://github.com/obviyus/SuperSeriousBot
$ cp .env.example ssgbot.env

Fill ssgbot.env.

Required:

• TELEGRAM_TOKEN
• QUOTE_CHANNEL_ID

Optional:

• OPENROUTER_API_KEY for /ask, /edit, /tldr, /tr
• WAQI_API_KEY for /weather
• GIPHY_API_KEY for /gif
• GOODREADS_API_KEY for /book
• WOLFRAM_APP_ID for /calc
• COBALT_URL for /dl backend override
• ADMINS, UPDATER, WEBHOOK_URL, LOGGING_CHANNEL_ID for bot ops

Running

SuperSeriousBot is run via Docker. The latest image can always be found at: ghcr.io/obviyus/SuperSeriousBot.

To start the bot you only need docker-compose.yaml and a valid ssgbot.env file.

$ docker compose up --build

Development

Local dev (without Docker):

$ uv sync
$ uv run python src/main.py

Recommended Reading

• Telegram API documentation
• python-telegram-bot documentation

Contributing

All commit messages must conform to the Angular Commit Message conventions.