lordraw/hassgram repository overview

⁠hassgram

A Telegram bot that drives Home Assistant — lights, temperatures and voice notes — speaking both Italian and English.

Ask it in whatever language you happen to be typing in: "turn on the light in the study" or "accendi la luce dello studio". It follows you, and answers in the same language, voice notes included.

• Source: https://github.com/lordraw77/hassgram⁠
• Image: lordraw/hassgram
• Tags: latest, plus one immutable tag per release (1.0.0, …)
• Architectures: linux/amd64, linux/arm64, linux/arm/v7

⁠Quick start

docker run -d --name hassgram --restart unless-stopped \
  -e HOME_ASSISTANT_API_URL="http://homeassistant.local:8123/api/" \
  -e HOME_ASSISTANT_API_ACCESS_TOKEN="<long-lived access token>" \
  -e TELEGRAM_BOT_TOKEN="<token from @BotFather>" \
  -e TELEGRAM_CHAT_ID="123456789" \
  lordraw/hassgram:latest

⁠docker compose

services:
  hassgram:
    image: lordraw/hassgram:latest
    container_name: hassgram
    restart: unless-stopped
    env_file: .env

The bot only makes outbound connections (Telegram long polling, plus the Home Assistant REST API), so there is no port to publish and no volume to mount. It keeps nothing on disk; all state is a small in-memory cache. It runs as an unprivileged user (uid 10001).

⁠Configuration

Get the access token from your Home Assistant profile page → Security → Long-lived access tokens. Get your chat id by messaging the bot and reading the log line it prints for unauthorised chats.

⁠Commands

Every command has an Italian alias: /luci, /accese, /accendi, /spegni, /temperatura, /stato, /lingua. The name you use is itself a language signal: /lights answers in English, /luci in Italian.

Plain sentences work too — "turn everything off", "how warm is it in the bedroom?", "which lights are on" — and so does "home" as a stand-in for every room at once.

⁠Voice notes

Send a voice message (or an audio file, or a video note) saying the same thing you would type. The bot transcribes it, echoes back what it understood, and runs it.

Transcription uses the speech-to-text engine already configured in Home Assistant (POST /api/stt/<entity_id>) — no extra service, no extra API key. Telegram's ogg/opus voice notes are passed through untouched, so no ffmpeg and no conversion are needed. Voice is transcribed in the chat's current language, so switch with /language (or just write a message in the other language) before recording.

If your Home Assistant has no stt. entity, typed commands keep working and voice notes get a polite explanation instead.

⁠How it works

Room names are not exposed by the Home Assistant REST API, so the entity_id → area map is rendered by a Jinja template on the Home Assistant side and cached. Entity states are cached for 5 seconds and invalidated on every service call. Name matching is fuzzy across friendly name, entity id and room, so "luciCucina", "kitchen" and "cucina lights" all land on the same place.

⁠Security notes

• Set TELEGRAM_CHAT_ID. An empty allow-list means anyone who finds your bot can switch your lights.
• The access token is a full-privilege Home Assistant credential — pass it via env_file/secrets rather than baking it into an image or a compose file in version control.
• The container needs no privileges, no host network and no volumes.

⁠Tags

• latest — the current release.
• X.Y.Z — built from the git tag of the same name, never overwritten.

Full documentation, the source and the issue tracker live at https://github.com/lordraw77/hassgram⁠.