- Python 98.7%
- Dockerfile 0.8%
- HTML 0.5%
|
|
||
|---|---|---|
| .gitea/workflows | ||
| docs | ||
| scripts | ||
| src/tomorrow_team_bot | ||
| tests | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| compose.yaml | ||
| Dockerfile | ||
| pyproject.toml | ||
| README.md | ||
| requirements-dev.lock | ||
| requirements.lock | ||
Availability Bot
A runnable Telegram bot and web dashboard for a team's daily work plans. Each evening it asks about the next day; each morning it publishes a named summary. Runs as one Docker container with a persistent SQLite volume.
Features
- In office / Work from home / Out of office buttons; members can change their plans for today or tomorrow.
- Named morning summaries, including people who haven't replied.
- Multiple independent teams, each with its own admins, channel/group, timezone, workdays and schedule. Sunday evening can ask about Monday.
- Admin-approved invitation links, direct member enrollment, admin roles, deactivation/reactivation with retained history, and last-admin protection.
- Inclusive PTO ranges, automatically reflected in summaries and reports.
- Admin-only 30-calendar-day table and CSV, in Telegram and the web dashboard.
- A responsive UI for daily plans, people, PTO, reporting, settings and activity.
- Private, single-use Telegram sign-in links; eight-hour sessions and CSRF checks.
- Durable delivery queue, polling offsets, retry/backoff, rate-limit handling, missed-event catch-up and delivery diagnostics.
- Docker Compose, health checks, non-root runtime and pinned runtime dependencies.
Try it without a Telegram token
git clone ssh://git@git.c3n.ro:2222/codinm/availability-bot.git
cd availability-bot
DEMO_MODE=true TELEGRAM_BOT_TOKEN= docker compose -p availability-demo up --build -d
Open http://localhost:8080, then choose Explore the demo. It uses synthetic people and records. Demo mode sends no Telegram messages. Keep demo and live instances on separate Compose projects/volumes; a demo database cannot be started in live mode.
Stop the demo with docker compose -p availability-demo down. Its named data volume
is preserved. To run on a different local port, set both WEB_PORT=8188 and
APP_BASE_URL=http://localhost:8188 in the command environment.
Run your real bot
- Create a bot in Telegram with @BotFather. Copy
.env.exampleto.envand setTELEGRAM_BOT_TOKEN. Keep this file private and out of Git. - Set
APP_BASE_URLto the dashboard's browser origin. Local testing can usehttp://localhost:8080; remote access requires an HTTPS origin behind your reverse proxy. The UI and API use that same origin. No Telegram webhook or inbound Telegram port is needed: the bot uses long polling. - Set
BOOTSTRAP_ADMIN_IDSto the Telegram numeric user IDs allowed to create teams, comma-separated. If you don't know your ID, initially leave it empty, start the bot, send/startprivately, read your ID, then set it and recreate the container. An empty list grants team-creation rights to nobody. - Start with
docker compose up --build -d. After changing.env, rundocker compose up -dto recreate the service with the new environment. - As an operator, send
/newteam Your team name, then/web. Open the private single-use dashboard link from Telegram. Localhost links work on the computer hosting Docker; use the HTTPS origin for other devices. - Add the bot to your group/channel and promote it to administrator. The bot
privately sends the inviting user its chat ID when possible. Connect it in
Settings → Telegram destination, using the negative chat ID or a public
@channel_username. You must also be a Telegram admin of that destination. In groups,/idis another way to get the chat ID. - Share the invite link from Team members. Members open the bot, request to
join, and appear for admin approval. Sending
/startenables private reminders. - Configure workdays and local times, add PTO, and use Send check-in or Publish today's summary to check delivery immediately.
Default times are 18:00 / 09:00 Europe/Bucharest, with every calendar day selected. A check-in asks about the next calendar day and is sent only if that next day is selected as a workday. Change the workdays to suit your team.
The Compose port binds to loopback (127.0.0.1). A host reverse proxy can forward
the configured HTTPS origin to it. For a proxy running in Docker, attach the app
to the proxy's network instead and route to port 8080. Run one app process per
volume; a file lock prevents multiple pollers from sharing the same database.
Commands
Send /help privately for the complete list. Key commands:
/teams
/tomorrow TEAM_ID
/today TEAM_ID
/web
/newteam Team name operator only
/bind TEAM_ID CHAT_ID team admin
/invite TEAM_ID team admin
/approve TEAM_ID USER_ID team admin
/admin TEAM_ID USER_ID on|off team admin
/remove TEAM_ID USER_ID team admin
/pto TEAM_ID USER_ID YYYY-MM-DD YYYY-MM-DD team admin
/pto_cancel TEAM_ID PTO_ID team admin
/report TEAM_ID team admin, private delivery
/prompt TEAM_ID team admin
/announce TEAM_ID team admin
Delivery and reporting rules
- Admins and memberships are scoped to each team; forwarded buttons grant no role.
- Reports contain 30 inclusive calendar dates ending today, using the team's
timezone, and include retained records of deactivated members. Missing replies
remain
NO_RESPONSE; unenrolled dates and inactive gaps areNOT_ENROLLED. - These are declared plans, not verified attendance or hours worked.
- PTO overrides daily responses. Canceling a PTO range recalculates the report and reveals any earlier response. All role/PTO/status changes are audited.
- Missed scheduled events catch up for two hours, then are skipped. A persisted event key prevents a restart from creating the same scheduled event twice.
- Delivery attempts survive restarts. Failed/blocked recipients are isolated; Telegram rate limits delay the queue. An accepted message followed by a network timeout can occasionally be delivered twice; Telegram has no general send idempotency key. This is not an exactly-once delivery guarantee.
- Report permission is checked when the CSV/preview is delivered. Scheduled private reminders skip PTO members and people who have already answered.
- Completed/expired delivery payloads are cleared; delivery metadata is retained for 30 days. Core availability history and audit records remain until an operator applies a retention policy to their own installation.
Development and validation
Python 3.11+; the image uses 3.12. No frontend build step, CDN or Node runtime is needed.
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.lock
.venv/bin/pip install --no-deps -e .
.venv/bin/pytest -q
.venv/bin/ruff check src tests
# Local demo (separate database from production):
DEMO_MODE=true DATABASE_PATH=data/demo.sqlite3 .venv/bin/availability-bot
Tests cover Telegram updates and callbacks, replay/rollback, channel setup, permissions, expiring login links, CSRF, PTO, reports, SQLite migration, schedule windows/DST, queue retries/rate limits, large summaries and HTTP multipart uploads. Telegram calls use a simulator; no real messages or credentials are needed.
See operations and backups, Telegram behavior, architecture, and the validation record. A real BotFather token and a test channel are needed for your installation's live Telegram acceptance check.