Bot de Conta de Energia para Telegram
goldeen802/electricity-bill-telegram-bot
Divida contas de energia entre colegas direto pelo Telegram
Ver no GitHubBot Telegram que divide automaticamente a conta de eletricidade compartilhada entre colegas de quarto, enviando a cada um sua parte por mensagem privada. Substitui WhatsApp e Excel manual com fluxo 100% por Telegram, extraindo dados de PDF da TNB e calculando o rateio com precisão.
Instalação
npx convez-ai goldeen802/electricity-bill-telegram-bot1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerenciar despesas compartilhadas entre moradores
- Automatizar cálculo e distribuição de contas de energia
- Eliminar processos manuais com WhatsApp e Excel
Veredito

Solução robusta e prática que resolve um problema real do dia a dia: automatizar divisão de contas entre moradores. Migrou com sucesso de scraper frágil para API oficial, mantendo paridade funcional — bom caso de uso para quem quer integração Telegram + processamento de PDFs.
README
A tradução para o português deste README ainda está na fila.
Electricity Bill Bot (Telegram)
Splits the shared TNB electricity bill among rooms and sends each person their share on Telegram. No WhatsApp, no manual sending, no Excel popups.
Roommates only need the Telegram app on their phone — nothing to install. Only the one PC that hosts the bot needs Python.
Demo
A typical month, driven entirely from Telegram:
Admin: /newbill
Bot → group: 📢 New electricity bill is open!
Submit your room's current meter reading:
• Big Room → /br • Single Room → /sr1 • Small Room → /sr2
Admin (in DM): «forwards the TNB bill PDF»
Bot → admin: 📄 Bill read: RM 520.05 for 1056 kWh
Roommate: /sr1 1779
Bot → group: ✅ Single Room: 1779 kWh recorded (Alice)
Admin: /preview
Bot: rate RM 0.4925/kWh
Big Room RM 16.42/person
Single Room RM 39.40/person
Small Room RM 18.06/person
Admin: /send
Bot → each person (DM): Hi! This month: RM 50 (house fund) + RM 16.42 (aircon)
= RM 66.42 [+ Maybank QR image]
Bot → admin: ✅ Sent to 5 people; ledger updated; cycle closed.
Monthly routine (all from your phone)
/newbill— announces the new cycle in the group.- Forward the TNB bill PDF to the bot in your private chat with it (before
or after
/newbill— either works). A PDF sent in the group won't reach the bot (Telegram hides group messages from bots). - Roommates submit their meter reading in the group (see "Submitting readings").
Check progress anytime with
/status. /preview— see everyone's amount./send— each person gets their amount + the payment QR. Done.
The bot also writes the month into House Fund.xlsm so you can open it and
check the history anytime. Each month uses only the PDF you forward that month —
last month's bill is never reused.
Submitting readings
A reading is the room's current meter number (cumulative, e.g. 3448.1).
The latest reading submitted for a room wins, so a typo is fixed by just
sending it again.
Two easy ways:
- Tap
/br,/sr1, or/sr2from the "/" menu. The bot opens your keyboard asking for the number — type3448.1and send. - Or type it in one go:
/sr1 3448.1. A registered roommate can also use/reading 3448.1for their own room.
You (the admin) key in a room the same way — just use /br / /sr1 / /sr2.
Joining — /start
A roommate sends /start in the group. The bot replies with a one‑tap
button that opens its private chat; they press Start there and pick their
room. That single flow does both required things: it lets the bot DM them their
bill (Telegram blocks DMs until a user opens the bot privately) and registers
their room. They only ever do this once.
Commands
Everyone:
/start— join: opens setup and registers your room./br/sr1/sr2— submit a room's reading (tap, then type the number)./reading— submit your own registered room's reading.
Admin (these appear in your "/" menu both in your DM and inside the group):
/newbill— open a new cycle and announce it in the group.- (forward the TNB PDF) — the bot reads the total and kWh from it.
/status— see who has submitted and the headcounts in use./headcount <Room> <number>— set how many people split a room this cycle (type it; intentionally not in the tap menu)./people— manage people and admins with tap buttons (see below)./preview— see everyone's amount before sending./send— DM each person their amount + QR, write the ledger, close the cycle./chatid— show the current chat's id (used once when setting up the group).
Managing people and admins — /people
/people shows everyone who has registered, grouped by room (admins marked 👑),
with two tap buttons per person:
- 👑 Admin / ⬇️ Unadmin
<name>— promote or demote that person. To make yourself a normal user, tap your own ⬇️ Unadmin. - 🗑
<name>— remove that person completely (registration and admin).
The bot refuses to remove the last admin (by either button), so nobody gets locked out. This is the only place you manage admins — no config editing needed once the bot has run the first time.
Where things are visible
/previewand/statusprint in the group, so all members see the amount breakdown (this is intentional — transparent splitting).- The actual payment message + QR from
/sendis a private DM to each person, never posted in the group.
Headcount (people per room)
/preview and /status show how many people each room is split between and
where that number came from:
- "registrations" — how many people tapped
/startfor that room (automatic). - "admin override" — you set it this cycle with
/headcount Big Room 3. - "config default" — the fallback in
config.jsonunderroom_people.
First-time setup with a Telegram group
- Create the bot: message @BotFather →
/newbot→ choose a name and a username ending inbot→ copy the token. - Add the token: copy
.env.exampleto.envand paste the token afterTELEGRAM_BOT_TOKEN=. - Make yourself admin: message @userinfobot to get your numeric id, and
put it in
config.jsonasadmin_user_ids(a list, e.g.[5641818296]). - Install Python 3.11+ from python.org on the host PC ("Add to PATH" is nice but not required).
- Start the bot to test:
python bot.py(later,setup.batmakes it run hidden automatically — see "Running it"). - Create the Telegram group and add your bot to it.
- Get the group id: in the group, send
/chatid. The bot replies with the id (a negative number). Put it inconfig.jsonastelegram.group_chat_id, then restart the bot. Now/newbillannounces in the group and your admin commands appear in the group's "/" menu. - Roommates join: each one sends
/startin the group and follows the one‑tap setup (opens the bot privately, presses Start, picks their room).
Keep the bot's privacy mode on (BotFather default): it still gets commands and replies to its own prompts, so readings work in the group, but it ignores normal chatter.
Running it
The bot runs hidden in the background and starts itself every time you log in. You never start it by hand. It uses very little memory (~50 MB) and negligible battery, and shows no window. If your PC is off when someone submits, Telegram holds the message for ~24h and the bot catches up when the PC is next on.
Setup is double-click, no administrator rights needed — setup.bat installs
the dependencies and drops a small launcher into your Windows Startup folder
so the bot auto-starts at login.
- To set it up the first time, or after moving the folder: double-click
setup.bat. - To stop it and remove auto-start: double-click
uninstall.bat.
Handing this over to the next person
The whole folder is the handover (copy it via USB/drive/zip — a git clone would
miss the private files: config.json, .env, House Fund.xlsm, the QR).
The easy way — keep the same bot, only change who's in charge:
- Copy the folder to the new person's PC (this brings the ledger and its history, which the math needs).
- Install Python 3.11+ on their PC.
- Make them an admin: while you're still admin, have them
/start, then open/peopleand tap 👑 Admin next to their name. When ready, tap your own ⬇️ Unadmin to step down. - Swap the payment QR if they collect the money: replace
assets/maybank_qr.jpegand adjusthouse_fund_amount/ the message inconfig.jsonif needed. - Run
setup.batonce on their PC so the bot auto-starts hidden.
If they want their OWN bot instead: create one with @BotFather, paste the
token into .env, and everyone re-registers with /start.
Project history (why I rebuilt it)
v1 was a WhatsApp Web scraper. Playwright drove a logged-in WhatsApp Web session to read roommates' typed meter readings and send back each person's share. It worked, but it was fragile: every WhatsApp UI change risked breaking both the scraper and the sender, and parsing free-typed readings was error-prone.
v2 (this repo) replaces that with a Telegram bot on the official Bot API:
- Robust — a stable HTTP API instead of browser automation, immune to UI redesigns.
- Structured input — readings come in as commands, so there's no free-text guessing about who/what room.
- Calc ported to Python with a parity gate — the original split logic lived in an Excel VBA macro driven over COM (popups and all). I reimplemented it in pure Python behind a test that asserts it matches the original spreadsheet to the cent.
- Still keeps the Excel ledger — each month is appended to the original
workbook via
openpyxl(no Excel install, no COM).
The original WhatsApp version is preserved at the legacy-whatsapp git tag.
How this was built — AI-orchestrated development
This project was built with Claude (Claude Code), under human orchestration —
I directed the requirements, decisions, and verification while the agent did the
implementation. It follows the Superpowers skill workflow end to end, and the
artifacts of that process are committed in docs/superpowers/:
- Brainstorming — I drove an interactive design exploration of the real
trade-offs (WhatsApp Cloud API vs Telegram vs a web app; keeping the Excel
macro vs porting to Python; privacy-mode vs free-text parsing). Output: the
design spec in
docs/superpowers/specs/. - Writing plans — the agreed design became a detailed, test-driven build
plan in
docs/superpowers/plans/, decomposed into small, independently verifiable tasks. - Subagent-driven development — each task was implemented by a fresh agent and passed spec-compliance and code-quality review gates before the next. The highest-risk piece — porting the bill calculation out of an Excel VBA macro — was gated by a parity test asserting the Python output matches the original spreadsheet to the cent.
The human role throughout was direction, decision-making, and sign-off at each gate — a demonstration of harnessing AI coding tools to ship robust, tested software quickly.
Files
bot.py— the bot (runs automatically; you never start it by hand).calc.py— the split math (bill / total kWh x each room's usage).ledger.py— writes the month intoHouse Fund.xlsm.store.py— remembers who is in which room, the admins, and the current cycle.bill_parser.py— reads the TNB PDF.message_generator.py— builds each person's payment message.setup.bat/uninstall.bat— hidden auto-start (no admin needed).House Fund.xlsm— your running ledger (kept private, not in git).config.json— your settings (kept private).config.example.jsonis the shareable template.