Duty Teller (Telegram Bot)

A minimal Telegram bot boilerplate using python-telegram-bot v22 with the Application API.

Get a bot token

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to create a bot.
3. Copy the token BotFather gives you.

Setup

1. Clone and enter the project

   cd duty-teller
   

2. Create a virtual environment (recommended)

   python -m venv venv
   source venv/bin/activate   # Linux/macOS
   # or: venv\Scripts\activate  # Windows
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Configure the bot

   cp .env.example .env
   

   Edit .env and set BOT_TOKEN to the token from BotFather.

5. Miniapp access (calendar)
   To allow access to the calendar miniapp, set ALLOWED_USERNAMES to a comma-separated list of Telegram usernames (without @). Users in ADMIN_USERNAMES also have access; the admin role is reserved for future bot commands and API features. If both are empty, no one can open the calendar.
   Mini App URL: When configuring the bot's menu button or Web App URL (e.g. in @BotFather or via setChatMenuButton), use the URL with a trailing slash, e.g. https://your-domain.com/app/. A redirect from /app to /app/ can cause the browser to drop the fragment that Telegram sends, which breaks authorization.
   How to open: Users must open the calendar via the bot's menu button (⋮ → «Календарь» or the configured label) or a Web App inline button. If they use «Open in browser» or a direct link, Telegram may not send user data (tgWebAppData), and access will be denied.
   BOT_TOKEN: The server that serves /api/duties (e.g. your production host) must have in .env the same bot token as the bot from which users open the Mini App. If the token differs (e.g. test vs production bot), validation returns "hash_mismatch" and access is denied.

6. Optional env

   • DATABASE_URL – DB connection (default: sqlite:///data/duty_teller.db).
   • MINI_APP_BASE_URL – Base URL of the miniapp (for documentation / CORS).
   • MINI_APP_SKIP_AUTH – Set to 1 to allow /api/duties without Telegram initData (dev only; insecure).
   • INIT_DATA_MAX_AGE_SECONDS – Reject Telegram initData older than this (e.g. 86400 = 24h). 0 = disabled (default).
   • CORS_ORIGINS – Comma-separated allowed origins for CORS, or leave unset for *.
   • EXTERNAL_CALENDAR_ICS_URL – URL of a public ICS calendar (e.g. holidays). If set, those days are highlighted on the duty grid; users can tap «i» on a cell to see the event summary. Empty = no external calendar.

Run

python main.py

Or after pip install -e .:

duty-teller

The bot runs in polling mode. Send /start or /help to your bot in Telegram to test.

Run with Docker

Ensure .env exists (e.g. cp .env.example .env) and contains BOT_TOKEN.

• Dev (volume mount; code changes apply without rebuild):

  docker compose -f docker-compose.dev.yml up --build
  

  Stop with Ctrl+C or docker compose -f docker-compose.dev.yml down.

• Prod (no volume; runs the built image; restarts on failure):

  docker compose -f docker-compose.prod.yml up -d --build
  

  For production deployments you may use Docker secrets or your orchestrator’s env instead of a .env file.

Production behind a reverse proxy: When the app is behind nginx/Caddy etc., request.client.host is usually the proxy (e.g. 127.0.0.1). The "private IP" bypass (allowing requests without initData from localhost) then applies to the proxy, not the real client. Either ensure the Mini App always sends initData, or forward the real client IP (e.g. X-Forwarded-For) and use it for that check. See api/app.py _is_private_client for details.

Project layout

• main.py – Entry point: builds the Application, registers handlers, runs polling and FastAPI in a thread. Calls duty_teller.config.require_bot_token() so the app exits with a clear message if BOT_TOKEN is missing.
• duty_teller/ – Main package (install with pip install -e .). Contains:
  • config.py – Loads BOT_TOKEN, DATABASE_URL, ALLOWED_USERNAMES, etc. from env; no exit on import; use require_bot_token() in main when running the bot. Optional Settings dataclass for tests. PROJECT_ROOT for webapp path.
  • api/ – FastAPI app (/api/duties, /api/calendar-events), dependencies.py (DB session, auth, date validation), static webapp mounted from PROJECT_ROOT/webapp.
  • db/ – SQLAlchemy models, session (session_scope), repository, schemas.
  • handlers/ – Telegram command and chat handlers; register via register_handlers(app).
  • services/ – Business logic (group duty pin, import); accept session from caller.
  • utils/ – Shared date, user, and handover helpers.
  • importers/ – Duty-schedule JSON parser.
• alembic/ – Migrations; config in pyproject.toml under [tool.alembic]; URL and metadata from duty_teller.config and duty_teller.db.models.Base. Run: alembic -c pyproject.toml upgrade head.
• webapp/ – Miniapp UI (calendar, duty list); served at /app.
• tests/ – Tests; helpers.py provides make_init_data for auth tests.
• pyproject.toml – Installable package (pip install -e .).

To add commands, define async handlers in duty_teller/handlers/commands.py (or a new module) and register them in duty_teller/handlers/__init__.py.

Импорт расписания дежурств (duty-schedule)

Команда /import_duty_schedule доступна только пользователям из ADMIN_USERNAMES. Импорт выполняется в два шага:

1. Время пересменки — бот просит указать время и при необходимости часовой пояс (например 09:00 Europe/Moscow или 06:00 UTC). Время приводится к UTC и используется для границ смен при создании записей.
2. Файл JSON — отправьте файл в формате duty-schedule (см. ниже).

Формат duty-schedule:

• meta: обязательное поле start_date (YYYY-MM-DD), опционально weeks; количество дней определяется по длине строки duty.
• schedule: массив объектов с полями:
  • name — ФИО (строка);
  • duty — строка с разделителем ;: каждый элемент соответствует дню с start_date по порядку. Пусто или пробелы — нет события; в, В, б, Б — дежурство; Н — недоступен; О — отпуск.

При повторном импорте дежурства в том же диапазоне дат для каждого пользователя заменяются новыми.

Tests

Install dev dependencies and run pytest:

pip install -r requirements-dev.txt
pytest

Tests cover api/telegram_auth (validate_init_data, auth_date expiry), config (is_admin, can_access_miniapp), and the API (date validation, 403/200 with mocked auth, plus an E2E auth test without auth mocks).