- TypeScript 81%
- CSS 17%
- JavaScript 1%
- Docker <1%
- HTML <1%
Telegram Kanban #
A Trello-style Kanban board that runs as a Telegram Mini App, with one board per group chat.
How it works #
- Multi-tenant: the bot can be added to any number of groups; each gets its own board, scoped by chat ID. Open the bot in a private chat to see a picker across every group you're in.
- Owner approval (optional): set
OWNER_IDand newly-added groups stay unusable until you approve them via inline buttons the bot DMs you. Unset it and every group is auto-approved. - No membership API needed for auth: users are identified by validating Telegram's signed
initData; access to a specific board is checked against a local membership cache built up as people open it (seeserver/src/middleware/resolveChatId.ts). - Discussion happens in the chat, not the app: creating a task posts an anchor message into the group; the task's "Discuss in chat" button deep-links straight to that message thread. Attachments work the same way — reply to that thread with a file and it shows up on the task.
- Tasks support multiple assignees, a checklist, start/due dates, and archiving.
- Data is a single SQLite file. The client polls
GET /api/boardevery ~3s instead of using websockets. The bot itself is long-polling (getUpdates), not webhook-based — no public inbound endpoint needed beyond the Mini App's own HTTPS URL.
1. Create the bot #
- Open a chat with @BotFather in Telegram.
- Send
/newbotand follow the prompts (choose a name and a unique username ending inbot). - BotFather replies with an API token that looks like
123456789:AAExampleTokenValue. Save it — this is yourBOT_TOKEN.
2. Register the Mini App #
- In BotFather, send
/newappand select your bot. - Fill in the app's title, description, and image when prompted.
- When asked for the Web App URL, enter your deployed HTTPS URL (e.g.
https://kanban.yourdomain.com). Telegram requires a real TLS certificate here — a bare IP orhttp://won't work. - Also set this as the bot's menu button: talk to BotFather → your bot → Bot Settings → Menu Button → set it to the same URL, so it can be opened directly from any chat.
While developing locally before you have a real HTTPS deployment, you can point the Web App URL at
an ngrok/Cloudflare Tunnel HTTPS URL that forwards to your local dev server, and update it later.
3. Add the bot to a group #
Just add it as a member of any group (no admin rights required). The bot picks this up
automatically via long-polling and registers the group — no manual chat-ID lookup needed anymore.
If OWNER_ID is set, you'll get a DM to approve/deny it before its board becomes usable.
4. Configure environment variables #
Copy .env.example to server/.env and fill in (note: it must live in server/, since that's
the working directory npm run dev:server/npm run start actually run from):
BOT_TOKEN=123456789:AAExampleTokenValue
OWNER_ID=123456789 # optional — your own Telegram user ID, see "How it works" above
PORT=3000
DB_PATH=./data/dev.db
OWNER_ID isn't your bot's ID — it's your personal Telegram user ID (the account that should
receive approval prompts). Get it from a bot like @userinfobot.
5. Run it locally #
npm install
npm run build # builds server (tsc) + client (vite)
npm run dev:server # starts the API on PORT, serving client/dist too
For frontend-only iteration with hot reload, run the Vite dev server alongside the API
(npm run dev:client, proxies /api to localhost:3000) — but note the Telegram SDK and
initData validation only work when actually opened inside Telegram, so UI-only changes are
easiest to preview with a mocked /api/board response; real auth flows need to be opened from
Telegram itself (see below).
To test against real Telegram before you have a permanent deployment, expose your local server
with a tunnel (e.g. cloudflared tunnel --url http://localhost:3000) and temporarily point the
BotFather Web App URL at the HTTPS URL it gives you.
Only run one instance against a given BOT_TOKEN at a time. Telegram allows a single active
getUpdates long-poll connection per bot token — running a local dev server and the production
deployment simultaneously causes them to silently steal updates from each other.
6. Deploy with Kamal #
config/deploy.yml and .kamal/secrets are not tracked in git (they contain server-specific
details like your host and domain) — create them yourself:
config/deploy.yml:
service: telegram-kanban
image: telegram-kanban
servers:
web:
- <your-server-ip-or-ssh-host-alias>
registry:
server: localhost:5555 # local registry — Kamal builds on your machine, no external registry needed
builder:
arch: amd64 # match your server's CPU arch
env:
clear:
PORT: "3000"
DB_PATH: "/app/server/data/kanban.db"
secret:
- BOT_TOKEN
- OWNER_ID
volumes:
- "telegram_kanban_data:/app/server/data"
proxy:
ssl: true
host: kanban.yourdomain.com # must already resolve to your server for Let's Encrypt to work
app_port: 3000
.kamal/secrets:
BOT_TOKEN=<your bot token>
OWNER_ID=<your telegram user id>
Then:
kamal setup(first time), thenkamal deployfor subsequent deploys.- The SQLite file lives on a named Docker volume (
telegram_kanban_data) mounted at/app/server/data, so it survives redeploys. Back it up periodically, e.g.:kamal app exec 'sqlite3 /app/server/data/kanban.db ".backup /app/server/data/backup.db"' - Once deployed, update the BotFather Web App URL (step 2) to point at your real domain if you were previously using a tunnel.
Project layout #
server/— Express API + SQLite, serves the built client as static files too. Talks to Telegram both ways: outbound viaserver/src/telegram/botApi.ts(posting messages), and inbound viaserver/src/telegram/poller.ts(long-polling for group-membership and approval callback events).client/— React + Vite frontend using@telegram-apps/sdk-react.config/deploy.yml— Kamal deploy config (untracked — see step 6).Dockerfile— multi-stage build producing the single deployed image.
License #
MIT — see LICENSE.