Telegram Smart Notes

A Telegram bot for "smart" reminders: write a message in natural language (e.g. "remind me to call the bank tomorrow at 3 pm") and the bot, powered by Google Gemini, automatically extracts the task, the deadline and any recurrence. It includes a web dashboard (also usable as a Telegram Mini App) to manage your reminders from a browser.

Features

• Create reminders from free-form text, with deadline and recurrence extracted via Gemini

• Attachments (photos/documents) linked to reminders

• Automatic notifications at the deadline, plus a daily summary of overdue, uncompleted reminders

• Web dashboard with automatic login (Telegram Mini App) or manual login (6-digit code generated with /login)

• Whitelist of authorized chats, with an /authorize command to add new ones

• Fully internationalized: bot messages, dashboard and AI parsing work in the language you choose (English and Italian included), with a configurable timezone

Requirements

• Docker and Docker Compose
• A Telegram bot created via @BotFather → you need its token
• A Google Gemini API key
• Your Telegram chat ID (you can get it by messaging @userinfobot)

Quick start

1. Clone the repository and enter the folder.
2. Copy the example environment file:

   cp .env.example .env

3. Open .env and fill in the values (see the table below).
4. Start the service:

   docker compose up -d --build

5. On Telegram, open a chat with your bot and send /start.

Environment variables

Variable	Description
GEMINI_API_KEY	Google Gemini API key, used to classify notes
TELEGRAM_BOT_TOKEN	Bot token, obtained from @BotFather
AUTHORIZED_CHAT_IDS	Comma-separated "Master Admin" chat IDs; they can use /authorize and /stats
DASHBOARD_URL	Public URL of the dashboard, used in the link generated by /login
WEB_PORT	Port on which the dashboard is exposed (default 3000)
LANGUAGE	Language of the bot and dashboard: a file in locales/ (en, it; default en)
TIMEZONE	IANA timezone for deadlines, notifications and the 09:00 daily summary (default UTC, e.g. Europe/Rome)

Bot commands

Command	Description
/start	Welcome message
/help	List of commands
/list	Show active reminders
/login	Generate a code/link to access the web dashboard
/authorize <id> [name]	(Master Admin only) Authorize a new chat to use the bot
/stats	(Master Admin only) System statistics

Language and timezone

All user-facing text lives in locales/<code>.json. Set LANGUAGE in .env to pick one (en and it are included); missing keys fall back to English. Notes can be written in any language regardless of LANGUAGE: the AI keeps the task text in the language you used.

To add a new language, copy locales/en.json to locales/<code>.json (e.g. fr.json), translate the values (keep the {placeholders} untouched), adjust _locale (BCP 47 tag, used to format dates) and _dateFormat if needed, then set LANGUAGE=<code>.

Telegram Mini App setup (optional)

To open the dashboard inside Telegram with automatic login, DASHBOARD_URL must be a public HTTPS URL. Then, with @BotFather: /mybots → your bot → Bot Settings → Menu Button → Configure menu button, and paste the URL. Without this, /login still works: it sends a link and a 6-digit code.

Data persistence

The SQLite database and attachments are stored in /usr/src/app/data inside the container. The provided docker-compose.yml uses a named Docker volume (notes-data) so data automatically survives restarts.

If you prefer to see the files directly on the host (e.g. to make backups more easily), comment out the named volume line in docker-compose.yml and use the bind-mount on ./data instead, after creating the folder locally.

Local development (without Docker)

npm install
cp .env.example .env   # and fill in the values
npm run dev            # uses nodemon for automatic reload

Security notes

• Never commit the .env file or the data/ folder (they contain secrets and real data): both are already excluded by .gitignore.
• Only chats listed in AUTHORIZED_CHAT_IDS (or authorized via /authorize) can use the bot.
• If you ever publicly shared a bot token or an API key, regenerate them (BotFather → /revoke, Google AI Studio → delete and recreate the key): an exposed secret must be considered compromised even if it is later removed from the code.
• Note text is HTML-escaped in the dashboard, so a malicious note cannot inject scripts.
• Note text is automatically escaped before being inserted into Telegram messages sent with parse_mode: Markdown, so characters like _ * \ [` in a note's content no longer break formatting.
• Telegram Mini App authentication (verifyTmaData) now rejects an initData older than 24 hours (the TMA_MAX_AGE_SECONDS constant in web-server.js), in addition to validating its signature. You can shorten this window if you expose the dashboard publicly.

Known limitations / possible future improvements

• No license file is included: if the repository will be public, consider adding one (e.g. MIT).