Botspot Template

A template for creating Telegram bots using botspot, an aiogram framework with batteries included.

botspot   aiogram   Telegram Bot API

Use this template

Clone, set a bot token, run. botspot wires the command menu, error handler, and send_safe into your aiogram dispatcher.

Install

Needs Python ≥ 3.12, uv, make, and a bot token from @BotFather.

GitHub: Use this template. Or clone:

git clone https://github.com/calmmage/botspot-template.git your-bot-name
cd your-bot-name
make wizard                 # help, then make setup (uv sync + doctor)
cp example.env .env         # set TELEGRAM_BOT_TOKEN
make run                    # uv run python run.py

Equivalent live start: uv run python run.py. make setup is the only install path. Done when make doctor prints cli: ok. Doctor and make test need no Telegram token.

Enable components in .env; see example.env for names.

Agents: follow AGENTS.md in this repo, botspot AGENTS.md for the library, and botspot_101.md for component snippets.

Give this to an agent

Paste:

Clone https://github.com/calmmage/botspot-template and follow AGENTS.md. Install uv if missing. Do not invent an install path. A Telegram bot token from @BotFather is the human's — put it in .env as TELEGRAM_BOT_TOKEN. Then make wizard, cp example.env .env, and make run.

What you get

Surface	What it is
App	src/app.py — typed AppConfig (TELEGRAM_BOT_TOKEN)
Bot	src/bot.py — BotManager enables error handler, ask_user, command menu, LLM provider, then polling
Router	src/router.py — @botspot_command /start, /help, /ask, friends-only
Config	example.env — every current botspot component prefix
Tests	make test — uv run pytest tests/
Docker	Dockerfile runs uv run python run.py

Project structure

.
├── src/
│   ├── app.py           # AppConfig + App
│   ├── bot.py           # BotManager + polling
│   ├── router.py        # commands (visibility, t(), /ask, friends-only)
│   ├── i18n.py          # botspot t() strings (en/ru)
│   └── __init__.py
├── run.py               # entry point (make run / docker)
├── docs/examples/       # logo, favicon, hero screenshot
├── example.env          # component flags (placeholders only)
├── botspot_101.md       # component snippets
├── AGENTS.md            # agent install wizard
├── Makefile             # wizard / setup / doctor / check / test / run
├── Dockerfile
└── pyproject.toml

Docs

This page, install, screenshot	README.md
In-repo docs index	docs/index.md
Component snippets	botspot_101.md
Agent install	AGENTS.md
Library	calmmage/botspot · AGENTS.md
Vulnerability reports	SECURITY.md

Docs stay in this repository and are linked from the README. GitHub Pages is not used.

make wizard   # install
make doctor   # cli: ok
make test     # pytest, no token
make run      # needs .env

License

GPL-3.0 — see LICENSE. Vulnerabilities: SECURITY.md.