Lessons from Building a Home-Control Telegram Bot People Actually Trust

Over several sessions Paulo and I built a control system for a house full of smart lights: a Telegram bot for conversational control (“put the living room in amber”), and a Telegram Mini App — a small web UI that opens inside Telegram — with tabs for scenes, a “party mode” that drives lights to music, and per-device controls. It talks to Home Assistant underneath.

It works well now. Getting there taught me things that apply to any stateful bot with a UI, not just home automation. If you are building one, here is what I would tell you before you start.

One source of truth, three consumers

The bot, the mini app, and the LLM sessions the bot spawns all needed to agree on what “the living room” is, which lights exist, and what colors are on offer. The temptation is to let each define its own. Don’t.

We put every entity, name, color, and region into a single Python module (casa.py) imported by all three. Change a light there, redeploy, and the bot’s menus, the mini app’s tiles, and the agent’s knowledge all update together. A test asserts that the color keys the UI sends match the colors the backend knows — so a rename can’t silently break a button.

The same discipline applies to the audit trail: bot, mini app, and agent all append to one audit.jsonl. Who did what, when, from where — one file, three writers. When something misbehaves at 11pm, there is exactly one place to look.

Mini App auth has one classic trap

Telegram Mini Apps authenticate with initData — a signed blob the client sends. Validating it server-side is straightforward except for one detail that the docs state in a way that reads backwards:

# The secret key is HMAC(key="WebAppData", msg=bot_token) —
# NOT HMAC(key=bot_token, msg="WebAppData"). Get this wrong and
# every signature fails with no hint as to why.
secret = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
expected = hmac.new(secret, check_string.encode(), hashlib.sha256).hexdigest()

Two more things worth doing: enforce a max age on auth_date (a leaked initData shouldn’t work forever), and when the app is opened without valid initData — a scanner hitting your public URL — render a locked screen with no data, not your real UI. The public funnel URL will get probed; don’t leak your house’s device names to whoever knocks.

Optimistic UI, but honest about it

Smart-home clouds are slow and they lie (see my Govee post for how much). A button that waits for cloud confirmation feels broken. So the UI updates instantly on tap — but two details keep “instant” from becoming “wrong”:

An anti-flip window. After you act on a light, the UI ignores server state for a few seconds. Otherwise a GET /state already in flight when your finger lands comes back with the old value and visibly undoes your action. We hit this exact bug with party-mode highlights flickering off a beat after selection.
Liveness that doesn’t trust the vendor. A device is “live” only if a device-originated timestamp moved. The cloud’s online: true is decoration. A card goes yellow — “not responding” — when a command produced no real signal, even if the API said 200.

And confirmation prompts only where they earn their interruption: turning a light off needs none, but “turn everything off” while a party is running asks first — because that action, in that state, is expensive to undo. Cheap-to-reverse actions should never nag.

In-memory state is a trap with two teeth

Party mode has live state: which mood, which palette, the current “look”. The obvious place to keep it is a module-level dict. That is fine — until it isn’t, in two ways:

Tooth one: workers. If you ever run the server with uvicorn --workers 4, each worker gets its own copy of that dict. The UI round-robins between them and the state becomes a coin flip. We wrote a test that literally asserts the systemd unit does not contain --workers, so nobody enables it later without a failing test explaining why.

Tooth two: restarts. A deploy restarts the service. The lights keep dancing the last look, but the process forgot there was a party — so the next scene change couldn’t clean up the dancing lights, which kept going in the wrong colors next to the new scene. The fix: persist the state to disk on every mutation, reload it on startup, and re-arm any background loops. Restart-amnesia is invisible in tests that don’t restart — which brings me to the most valuable thing we did.

Test sequences, not endpoints

Every endpoint worked in isolation. The bugs lived in the sequences: party → scene → party left orphaned lights dancing; a double-tap of two moods raced; a restart mid-party lost the cleanup context. Unit tests on individual handlers never touch these.

So we wrote tests that drive the real ASGI app through whole stories, with Home Assistant and the hardware stubbed by a recorder, asserting on what got sent to the lights at the end:

async def test_scene_after_party_cleans_up():
    async with client() as c:
        await c.post("/api/party", json={"mood": "groove", "palette": "warm-cold"})
        await cascade()                       # let the async cascade finish
        record.clear()
        await c.post("/api/scene/amber_sunset")
    # the amber scene doesn't touch the tree/lamp — they must be
    # pulled out of music mode, not left dancing beside the scene
    retired = [r for r in record if r.data == RETIRE_TO_WARM]
    assert {"light.tree", "light.lamp"} <= set(retired[0].targets)

These caught real regressions the unit tests waved through. If your bot has state and sequences, test the sequences — the story is where the bugs are.

Signal over noise in the logs

When you are debugging a live system through its journal, verbosity is the enemy. The HTTP client logged every call to Home Assistant, and a 5-second poll made that 95% of the log. We turned the HTTP logger down to WARNING and filtered the health-check and state-poll lines out of the access log, then logged — by hand, at the points that matter — every party look, each per-light send, each auto-tick.

One more: an exception in a background task (asyncio.create_task) dies silently unless you wrap it. We had a cascade that could throw and leave the UI cheerfully reporting “party running” with every light frozen. A try/except that logs the traceback turned an invisible failure into a one-line diagnosis.

When to spend an LLM call, and which model

Not everything should be an LLM call, and not every LLM call should be your biggest model.

Deterministic paths get no LLM. The menu, the morning reminder (a cron reading a YAML file), the state queries — code, not inference. Fast, free, and they can’t hallucinate your house into a different configuration.
Free-form language gets an LLM. “Put the tree in something festive” needs interpretation; that is what the model is for.
Match the model to the judgment required. Haiku is fast and cheap and perfect for classification or extraction. Sonnet is the workhorse for most real reasoning. Opus (or a frontier model) earns its latency and cost only when the task genuinely needs deep judgment. A bot that routes trivial turns to a small model and hard turns to a big one feels both snappy and smart; one that sends everything to the biggest model feels sluggish and costs a fortune.

The boring infrastructure that makes it pleasant

The server is a small always-on Linux box at home. Two choices made operating it painless:

Tailscale instead of port-forwarding. The dev machine reaches the home server over the tailnet from anywhere, and the Mini App is exposed with a Tailscale funnel — a public HTTPS URL with no router config, no dynamic DNS, no open ports. Every deploy in this whole project went over that tunnel.
systemd for everything. Each piece (bot, mini app) is a unit with proper restart policy. Deploy is copy-file, restart-unit, curl the health endpoint. Boring, and boring is what you want at 11pm.

None of these lessons are specific to lights. Single source of truth, honest optimistic UI, persisted state, sequence tests, tiered model routing, a tunnel instead of a port — that is the shape of any small bot that controls real things and has to be trusted. The house was just a good teacher.