148 lines
5.4 KiB
Markdown
148 lines
5.4 KiB
Markdown
# Home Assistant Telegram Bot
|
||
|
||
Telegram-бот для удалённого доступа к домашнему ассистенту. Работает на отдельном VPS и общается с backend через REST API.
|
||
|
||
Документация backend: [корневой README](../README.md) (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](https://t.me/BotFather))
|
||
- Доступный с VPS URL backend Home Assistant (HTTPS рекомендуется)
|
||
|
||
Backend должен быть доступен по адресу вида:
|
||
|
||
```
|
||
https://your-home-server.example.com/api/v1
|
||
```
|
||
|
||
Если backend за reverse proxy, пробросьте порт `8080` или маршрут `/api/v1` наружу. CORS для бота не нужен.
|
||
|
||
## Быстрый старт (Docker)
|
||
|
||
```bash
|
||
cd telegram-bot
|
||
cp .env.example .env
|
||
# заполните TELEGRAM_BOT_TOKEN и HA_API_BASE_URL
|
||
docker compose up -d --build
|
||
docker compose logs -f
|
||
```
|
||
|
||
## Быстрый старт (без Docker)
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
git clone <repo> && cd Home_assistant/telegram-bot
|
||
cp .env.example .env
|
||
nano .env
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Обновление:
|
||
|
||
```bash
|
||
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
|
||
```
|