Home / Documentation

Getting started

Everything you need to have (ex)SpenserBot running on your own server and accepting your first receipt.

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

  1. Create the bot — talk to @BotFather, run /newbot, and keep the token safe.
  2. Clone the repository — git clone git@github.com:Cirius1792/expense-report-bot.git
  3. Configure the environment — copy .env.example to .env and fill in your token, LLM credentials, and authorization paths. See the configuration reference.
  4. Allow your user — create authorized-users.json with your Telegram user ID. Only whitelisted users can use the bot.
  5. Start it — docker compose --env-file .env.deploy up -d, then send /start to 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.