convez.ai
PluginAutomaçãoIntermediário
goldeen802

Bot de Conta de Energia para Telegram

goldeen802/electricity-bill-telegram-bot

Divida contas de energia entre colegas direto pelo Telegram

Ver no GitHub
InicialPluginScore · de 0 a 100

Bot 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-bot

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

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)

  1. /newbill — announces the new cycle in the group.
  2. 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).
  3. Roommates submit their meter reading in the group (see "Submitting readings"). Check progress anytime with /status.
  4. /preview — see everyone's amount.
  5. /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 /sr2 from the "/" menu. The bot opens your keyboard asking for the number — type 3448.1 and send.
  • Or type it in one go: /sr1 3448.1. A registered roommate can also use /reading 3448.1 for 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

  • /preview and /status print in the group, so all members see the amount breakdown (this is intentional — transparent splitting).
  • The actual payment message + QR from /send is 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 /start for that room (automatic).
  • "admin override" — you set it this cycle with /headcount Big Room 3.
  • "config default" — the fallback in config.json under room_people.

First-time setup with a Telegram group

  1. Create the bot: message @BotFather → /newbot → choose a name and a username ending in bot → copy the token.
  2. Add the token: copy .env.example to .env and paste the token after TELEGRAM_BOT_TOKEN=.
  3. Make yourself admin: message @userinfobot to get your numeric id, and put it in config.json as admin_user_ids (a list, e.g. [5641818296]).
  4. Install Python 3.11+ from python.org on the host PC ("Add to PATH" is nice but not required).
  5. Start the bot to test: python bot.py (later, setup.bat makes it run hidden automatically — see "Running it").
  6. Create the Telegram group and add your bot to it.
  7. Get the group id: in the group, send /chatid. The bot replies with the id (a negative number). Put it in config.json as telegram.group_chat_id, then restart the bot. Now /newbill announces in the group and your admin commands appear in the group's "/" menu.
  8. Roommates join: each one sends /start in 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:

  1. Copy the folder to the new person's PC (this brings the ledger and its history, which the math needs).
  2. Install Python 3.11+ on their PC.
  3. Make them an admin: while you're still admin, have them /start, then open /people and tap 👑 Admin next to their name. When ready, tap your own ⬇️ Unadmin to step down.
  4. Swap the payment QR if they collect the money: replace assets/maybank_qr.jpeg and adjust house_fund_amount / the message in config.json if needed.
  5. Run setup.bat once 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 into House 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.json is the shareable template.
Ver o original no GitHub

Bom para