Home_assistant/telegram-bot

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 "Имя"

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

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

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

Команды

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

Оповещения

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

1. Опрашивает GET /pomodoro/status и GET /reminders (счётчики seq)
2. Загружает новые сообщения из всех chat-сессий пользователя
3. Отправляет в 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

Проверка

1. Привязать токен → /whoami показывает имя
2. Написать «Привет» → ответ ассистента
3. Создать напоминание через web → notice в TG за ~30–60 с
4. Второй 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