Files

T

Grigo 8f3ac70b20 refactor

2026-06-16 09:19:32 +03:00

5.4 KiB

Raw Blame History

Home Assistant Telegram Bot

Telegram-бот для удалённого доступа к домашнему ассистенту. Работает на отдельном VPS и общается с backend через REST API.

Документация backend: корневой README (auth, PostgreSQL, RAG, nginx client_max_body_size для фото).

Возможности

Привязка API-токена Home Assistant через чат Telegram
Отдельная chat-сессия «Telegram» на каждого пользователя
Диалог с ассистентом (SSE-стриминг ответа)
Дублирование оповещений (notice, character) из всех сессий пользователя

Требования

Python 3.12+ или Docker
Telegram Bot Token (@BotFather)
Доступный с VPS URL backend Home Assistant (HTTPS рекомендуется)

Backend должен быть доступен по адресу вида:

https://your-home-server.example.com/api/v1

Если backend за reverse proxy, пробросьте порт 8080 или маршрут /api/v1 наружу. CORS для бота не нужен.

Быстрый старт (Docker)

cd telegram-bot
cp .env.example .env
# заполните TELEGRAM_BOT_TOKEN и HA_API_BASE_URL
docker compose up -d --build
docker compose logs -f

Быстрый старт (без Docker)

cd telegram-bot
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# заполните .env
python -m bot.main

Переменные окружения

Переменная	Описание
`TELEGRAM_BOT_TOKEN`	Токен от BotFather
`HA_API_BASE_URL`	Base URL API, например `https://home.example.com/api/v1`
`POLL_INTERVAL_SEC`	Интервал polling оповещений (по умолчанию 30)
`DATA_DIR`	Каталог для SQLite (`./data`)
`ALLOWED_TELEGRAM_IDS`	Опционально: whitelist Telegram user id через запятую

Создание API-токена на домашнем сервере

Через веб-интерфейс

Settings → Пользователи → создать пользователя. Токен показывается один раз — сохраните его.

Через CLI

cd ~/to_services/Home_assistant
docker compose exec backend python scripts/create_user.py myuser --display-name "Имя"

Токен будет выведен в консоль.

Использование бота

/start — инструкция
Отправьте API-токен одним сообщением
После успешной привязки удалите сообщение с токеном из истории Telegram
Пишите ассистенту обычным текстом

Команды

Команда	Описание
`/start`	Приветствие и инструкция
`/help`	Справка
`/whoami`	Текущий пользователь HA
`/logout`	Отвязать токен
`/newchat`	Новая сессия «Telegram»

Оповещения

Фоновый worker каждые POLL_INTERVAL_SEC секунд:

Опрашивает GET /pomodoro/status и GET /reminders (счётчики seq)
Загружает новые сообщения из всех chat-сессий пользователя
Отправляет в Telegram сообщения с ролями notice и character

Это покрывает напоминания, помидоро, homelab, fitness и другие системные оповещения без изменений backend.

Безопасность

API-токен хранится в SQLite на VPS (DATA_DIR/bot.db)
Токен виден в истории Telegram при отправке — удалите сообщение после привязки
Используйте ALLOWED_TELEGRAM_IDS, чтобы ограничить доступ к боту
Не коммитьте .env с реальными токенами

Деплой на VPS

git clone <repo> && cd Home_assistant/telegram-bot
cp .env.example .env
nano .env
docker compose up -d --build

Обновление:

git pull
docker compose up -d --build

Проверка

Привязать токен → /whoami показывает имя
Написать «Привет» → ответ ассистента
Создать напоминание через web → notice в TG за ~30–60 с
Второй Telegram-аккаунт с другим HA-токеном → изолированные чат и оповещения

Структура

telegram-bot/
  bot/
    main.py           # entrypoint
    config.py         # env
    ha_client.py      # REST + SSE клиент
    sse.py            # парсер SSE
    storage.py        # SQLite
    notify_worker.py  # polling оповещений
    handlers/         # команды и чат
  Dockerfile
  docker-compose.yml
  requirements.txt

5.4 KiB Raw Blame History Unescape Escape