What it is
(ex)SpenserBot is a Telegram bot that extracts structured expense data — amount, currency, merchant, date, category — from receipt photos, PDF receipts (1–5 pages), and free-text messages, using an LLM for the extraction. Expenses are stored per user and can be exported as a monthly CSV.
It is fully self-hosted: a single Docker container, a SQLite database, and any OpenAI-compatible LLM endpoint.
Prerequisites
- Telegram bot token — create a bot with @BotFather on Telegram and copy the token.
- LLM API access — any OpenAI-compatible endpoint works (OpenAI, Groq, Ollama, vLLM, LM Studio, …). You need a base URL, an API key, and a model name that supports the features you want (vision for receipt photos).
- Docker with the Compose plugin, on any machine that can reach Telegram and your LLM endpoint.
Setup in five steps
- Create the bot — talk to @BotFather, run
/newbot, and keep the token safe. - Clone the repository —
git clone git@github.com:Cirius1792/expense-report-bot.git - Configure the environment — copy
.env.exampleto.envand fill in your token, LLM credentials, and authorization paths. See the configuration reference. - Allow your user — create
authorized-users.jsonwith your Telegram user ID. Only whitelisted users can use the bot. - Start it —
docker compose --env-file .env.deploy up -d, then send/startto your bot on Telegram. Full instructions in the deployment guide.
Need your Telegram user ID? Message @userinfobot on Telegram — it replies with your numeric ID, which is what goes into the whitelist.