Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
| TELEGRAM_BOT_TOKEN | Yes | — | Bot token from @BotFather |
| LLM_BASE_URL | Yes | — | Any OpenAI-compatible endpoint, e.g. https://api.openai.com/v1 |
| LLM_API_KEY | Yes | — | API key for the LLM endpoint |
| LLM_MODEL | Yes | — | Model name your endpoint supports (use a vision-capable model for receipt photos) |
| EXPENSE_DB_PATH | No | expenses.db | SQLite database location |
| AUTHORIZED_USERS_CONFIG_PATH | Recommended | — | Path to the JSON whitelist of Telegram user IDs. In Docker: /data/authorized-users.json |
| UNAUTHORIZED_LOG_PATH | No | beside EXPENSE_DB_PATH | Dedicated audit file for unauthorized access attempts |
| LOG_LEVEL | No | INFO | Python logging level for the bot's stdout logs. An invalid value falls back to INFO with a warning |
User authorization
Only Telegram user IDs listed in the whitelist can interact with the bot. Everyone else is silently ignored and recorded in the audit log.
# authorized-users.json
{
"authorized_users": ["123456789"]
}
Values must be numeric strings. Find your own ID by messaging @userinfobot.
Startup failure behavior
| Situation | Behavior |
|---|---|
| Path not set, file missing, or file unreadable | Bot starts with no authorized users and logs a warning |
| Valid JSON, invalid schema | Bot starts with no authorized users and logs a warning |
| Malformed JSON | Startup fails |
| Audit log not writable | Startup fails |
Audit log
Each unauthorized attempt appends one line:
2026-07-19T12:00:00Z user_id=987654321
Data & privacy
- Storage — a single SQLite file. Amounts are stored as exact decimal strings (no floating-point drift).
- User isolation — every read and write is scoped to the sender's Telegram user ID. A user can only see, report, and delete their own expenses.
- Multi-currency — expenses keep their original ISO 4217 currency. No conversion to a base currency is performed.
- Deletion — deleting an expense marks it as deleted (logical deletion) so records are auditable and IDs stay stable.
Example: run from a source checkout
cp .env.example .env
uv sync
uv run pre-commit install
# migrations run through the project's Liquibase wrapper
export PATH="$PWD/scripts:$PATH"
# fill in .env, create authorized-users.json, then:
uv run expense-bot
The bot migrates the database before it opens it (ADR 0013). The wrapper on your PATH runs the official Liquibase Docker image, so Docker is required even when you run the bot from a source checkout — or you can put your own liquibase CLI on the PATH instead.