No description
  • Python 98.7%
  • Dockerfile 0.8%
  • HTML 0.5%
Find a file
Codin Moldovanu 2e308fbc85
Some checks failed
Test / test (push) Has been cancelled
Implement Telegram availability bot with admin dashboard and Docker runtime
2026-10-29 18:37:47 +02:00
.gitea/workflows Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
docs Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
scripts Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
src/tomorrow_team_bot Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
tests Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
.dockerignore Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
.env.example Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
.gitignore Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
compose.yaml Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
Dockerfile Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
pyproject.toml Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
README.md Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
requirements-dev.lock Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00
requirements.lock Implement Telegram availability bot with admin dashboard and Docker runtime 2026-10-29 18:37:47 +02:00

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

  1. Create a bot in Telegram with @BotFather. Copy .env.example to .env and set TELEGRAM_BOT_TOKEN. Keep this file private and out of Git.
  2. Set APP_BASE_URL to the dashboard's browser origin. Local testing can use http://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.
  3. Set BOOTSTRAP_ADMIN_IDS to 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 /start privately, read your ID, then set it and recreate the container. An empty list grants team-creation rights to nobody.
  4. Start with docker compose up --build -d. After changing .env, run docker compose up -d to recreate the service with the new environment.
  5. 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.
  6. 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, /id is another way to get the chat ID.
  7. Share the invite link from Team members. Members open the bot, request to join, and appear for admin approval. Sending /start enables private reminders.
  8. 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 are NOT_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.