PingMe

Personal Telegram bot for managing meetings, interviews, and tasks.

Built with aiogram 3, SQLite, and APScheduler. Access is limited to a whitelist of Telegram chat IDs (ADMIN_CHAT_ID).

Features

• Add events: interview / daily standup / call / task
• Inline calendar and hour/minute time pickers
• Morning daily summary (default 08:30)
• Reminder 10 minutes before timed events
• Reminder to set a status 30 minutes after an interview starts
• Interview statuses, notes, stats, CSV export, and cleanup of old records
• Whitelist-only access

Requirements

• Python 3.10+
• A Telegram bot token from @BotFather
• Your Telegram numeric ID from @userinfobot

Project structure

PingMe/
├── bot/
│   ├── main.py              # Entry point: bot, dispatcher, scheduler
│   ├── config.py            # Loads settings from .env
│   ├── database/
│   │   ├── db.py            # SQLite connection and schema
│   │   └── repository.py    # Data access helpers
│   ├── handlers/            # Command and callback handlers
│   │   ├── start.py         # /start, main menu
│   │   ├── add.py           # /add wizard
│   │   ├── lists.py         # /today, /week
│   │   ├── status.py        # /status filters and cards
│   │   ├── edit.py          # /edit
│   │   ├── delete.py        # /delete
│   │   ├── note.py          # /note
│   │   └── stats_export.py  # /stats, /export, /clean
│   ├── keyboards/           # Inline keyboards and calendar
│   ├── middlewares/         # Access control, DB injection, logging
│   ├── schedulers/          # Morning digest and reminders
│   ├── states/              # FSM forms for multi-step flows
│   └── utils/               # Constants and message formatters
├── data/                    # SQLite DB (created at runtime)
├── logs/                    # Log files (created at runtime)
├── .env.example             # Environment variable template
├── requirements.txt
├── Dockerfile
├── Procfile
└── railway.toml

Quick start (local)

cd PingMe
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env — set BOT_TOKEN and ADMIN_CHAT_ID
python -m bot.main

Environment variables

Variable	Required	Description
BOT_TOKEN	Yes	Telegram bot token
ADMIN_CHAT_ID	Yes	Allowed chat ID(s). Comma-separated for several users: 111,222,333
TIMEZONE	No	Default Europe/Moscow
MORNING_HOUR	No	Hour for morning digest (default 8)
MORNING_MINUTE	No	Minute for morning digest (default 30)
DB_PATH	No	SQLite path (default data/pingme.db)

Example .env:

BOT_TOKEN=123456:ABC...
ADMIN_CHAT_ID=123456789
TIMEZONE=Europe/Moscow
MORNING_HOUR=8
MORNING_MINUTE=30
DB_PATH=data/pingme.db

How to use the bot

1. Start a chat with your bot in Telegram.
2. Send /start — you get a short guide and the main menu.
3. Use /add (or the menu) to create an event step by step: type → title → date/time → optional note. Interviews also ask for company, position, and optional vacancy link.
4. Check the day or week with /today and /week.
5. Manage interviews with /status (filters by outcome, company view, status change, notes).
6. Use /edit, /delete, and /note for updates.
7. Review /stats, download CSV via /export, or remove finished events older than 30 days with /clean.
8. Send /cancel to abort any multi-step flow.

Commands

Command	Description
/start	Welcome and menu
/add	Add an event (guided wizard)
/today	Today's plan
/week	This week's plan
/status	Interview list with filters and status actions
/edit	Edit an event
/delete	Delete an event
/note	Add or update a note
/stats	Interview statistics
/export	Export all events to CSV
/clean	Remove completed events older than 30 days
/cancel	Cancel the current step

Event types

Type	Notes
Interview	Company, position, optional link; status expected after the date
Daily / Call	Timed meetings; optional “done” status
Task	Optional deadline; routine tasks (no deadline) get no reminders

Notifications

Notification	When
Morning digest	Daily at the configured time (default 08:30)
Pre-event reminder	10 minutes before interviews, dailies, and calls
Status nudge	30 minutes after an interview if status is still unset

Deploy on Railway

1. Push the repo to GitHub.
2. Create a project on Railway → Deploy from GitHub.
3. Set environment variables: BOT_TOKEN, ADMIN_CHAT_ID, TIMEZONE (and optional morning time / DB_PATH).
4. Attach a Volume at /app/data so SQLite survives redeploys.
5. Deploy. Logs should show Bot starting….

The included Dockerfile runs python -m bot.main. railway.toml builds from that Dockerfile.

Stack

• Python 3.10+ / aiogram 3.x — Telegram Bot API
• aiosqlite — async SQLite storage
• APScheduler — background jobs (digest and reminders)
• python-dotenv — config from .env