Telegram-бот для Home Assistant: управление домом из чата

Коротко: Telegram-бот превращает Home Assistant в чат, из которого видно состояние дома и можно им управлять. Интеграция Telegram bot поддерживает три режима: только отправка уведомлений, опрос серверов Telegram и вебхуки. Для квартиры достаточно опроса: он не требует выставлять сервер в интернет. Чат нужно заранее добавить в белый список, иначе бот молчит.

Зачем управлять домом из мессенджера

Home Assistant даёт веб-интерфейс и мобильное приложение. Оба работают, но есть три сценария, где мессенджер удобнее.

Уведомления, которые не потеряются. Push-уведомления приложения легко пропустить. Сообщение в чате остаётся и его видно на любом устройстве, где открыт Telegram.

Управление без установки приложения. Гостю или члену семьи достаточно открыть чат. Ничего настраивать не нужно.

Кнопки прямо в сообщении. Интеграция умеет отправлять сообщения с встроенной клавиатурой. Пришло уведомление о протечке, под ним две кнопки: перекрыть воду и закрыть. Нажатие отправляет команду обратно в Home Assistant.

Три режима работы бота

Это первый выбор при настройке, и он определяет требования к сети.

| Режим | Что умеет | Нужен доступ из интернета |

|, -|, -|, -|

| Broadcast | только отправка сообщений | нет |

| Polling | отправка и приём команд | нет |

| Webhooks | отправка и приём, мгновенная доставка | да, HTTPS обязателен |

Broadcast подходит, если нужны только оповещения: температура, движение, открытая дверь. Сервер может стоять за роутером без проброса портов.

Polling это режим для большинства домашних установок. Home Assistant сам раз в несколько секунд спрашивает Telegram, есть ли новые сообщения. Опрос идёт с тайм-аутом в десять секунд: если сообщений нет, запрос завершается и начинается заново. Внешний доступ не нужен.

Webhooks быстрее, потому что Telegram сам присылает событие на сервер. Цена: Home Assistant должен быть доступен из интернета по HTTPS, а самоподписанные сертификаты интеграция не поддерживает.

Для квартиры берите Polling. Вебхуки оправданы, если команд много и задержка в пару секунд раздражает.

Создание бота и получение идентификаторов

Настройка начинается не в Home Assistant, а в Telegram.

1. Откройте чат с @BotFather и отправьте команду /newbot.
2. Задайте имя и адрес бота. BotFather вернёт ссылку на бота и токен API.
3. Сохраните токен: он понадобится при настройке интеграции.
4. Отправьте любое сообщение боту @id_bot. В ответе будет ваш chat ID.
5. Перейдите по ссылке на своего бота и отправьте ему /start. Боты не могут написать первыми, поэтому первый контакт обязателен.

Chat ID это числовой идентификатор: у личного чата он положительный, у группы отрицательный. Для семейного чата каждый участник получает тот же идентификатор группы, и команды от любого из них приходят боту.

Настройка интеграции

1. Откройте Настройки, затем Устройства и службы.
2. Нажмите Добавить интеграцию и выберите Telegram bot.
3. Укажите тип бота: Broadcast, Polling или Webhooks.
4. Вставьте токен API.
5. Если нужен прокси, укажите его адрес в отдельном поле. Поддерживается схема socks5 с логином и паролем.
6. Добавьте разрешённый chat ID через меню из трёх точек на карточке интеграции.

Пункт про белый список пропускают чаще всего. Пока chat ID не добавлен, бот не отвечает и не отправляет сообщения в этот чат, и это выглядит как поломка интеграции.

Что можно отправлять

Интеграция даёт набор действий, и большинство из них доступны из автоматизаций.

• Текст. Основное действие для уведомлений.
• Фото. Снимок с камеры при движении.
• Документ. Файл из разрешённой папки: например, журнал или архив.
• Локация. Координаты, если устройство их передаёт.
• Опрос. Кнопки-варианты прямо в чате.
• Стикер, видео, голосовое сообщение.
• Правка и удаление отправленного сообщения.
• Ответ на нажатие кнопки. Нужен, чтобы убрать «часики» с нажатой кнопки.

Чтобы бот мог отправлять файлы из локальной папки, эту папку надо разрешить в настройках Home Assistant. По умолчанию доступ закрыт.

Приём команд и событий

Входящие сообщения попадают в сущность события. У неё есть атрибуты, по которым строится автоматизация.

| Событие | Когда срабатывает |

|, -|, -|

| Текст получен | пришло обычное сообщение |

| Команда получена | пришло сообщение вида /команда аргументы |

| Нажата кнопка | пришло нажатие на встроенную клавиатуру |

| Вложение получено | прислали файл |

| Сообщение отправлено | бот отправил сообщение любого типа |

Автоматизация строится так: триггер это изменение состояния сущности события, условие это тип события, действие это то, что нужно сделать.

Для команд удобно ловить событие «команда получена» и проверять атрибут команды. Аргументы приходят отдельным атрибутом, поэтому /свет кухня разбирается на команду и параметр.

Кнопки в сообщениях

Встроенная клавиатура это самая полезная часть интеграции. Она позволяет превратить уведомление в пульт.

Как это устроено:

1. Автоматизация отправляет сообщение с клавиатурой, где каждая кнопка несёт свой код данных.
2. Пользователь нажимает кнопку, и Telegram присылает событие с этим кодом.
3. Вторая автоматизация ловит событие, отвечает на нажатие и выполняет действие.

Практические примеры: подтверждение закрытия клапана воды, снятие сигнализации, выбор сценария освещения, ответ на вопрос «выключить ли кондиционер».

Нажатие кнопки нужно подтверждать отдельным действием. Без подтверждения Telegram продолжает показывать индикатор загрузки на кнопке.

Полезные сценарии для дома

• Протечка. Сообщение с кнопкой «Перекрыть воду».
• Дверь. Уведомление с фото с камеры и кнопкой «Открыть».
• Уход из дома. Отчёт о том, что осталось включённым, и кнопка «Выключить всё».
• Климат. Ежедневная сводка температуры и влажности, кнопка для запуска увлажнителя.
• Отпуск. Проверка, все ли устройства в нужном состоянии, по команде из чата.
• Стирка. Сообщение об окончании цикла.

Про то, как связать сценарии между собой, есть статья Сценарии умного дома: 20 готовых решений, которые работают.

Безопасность: о чём стоит подумать

Бот даёт доступ к дому через интернет, поэтому несколько правил обязательны.

• Белый список чатов. Не добавляйте бота в чужие группы. Открытый бот с правами на устройства это дыра.
• Токен это пароль. Если он попал в чужие руки, бота нужно пересоздать у BotFather. Отозвать токен можно командой /revoke.
• Не давайте боту прямых полномочий на критичное. Клапан воды лучше открывать отдельным кодом с подтверждением, а не одним словом в чате.
• Ограничьте права. Делайте отдельные скрипты для опасных действий и отдельные для безопасных.
• Резервные копии. Если бот перестанет работать, управление домом должно остаться доступным другим способом.

Отдельно подумайте про гостей и детей: то, что можно делать из чата, можно сделать с чужого телефона, если он оказался в руках.

Частые проблемы

Бот не отвечает. Проверьте, добавлен ли ваш chat ID в разрешённые, и написали ли вы боту /start.

Сообщения приходят с задержкой. Это нормально для режима опроса. Вебхуки доставляют событие сразу.

Не получается отправить фото. Вероятно, не разрешена папка с файлами в настройках Home Assistant.

Команды не работают. Скорее всего автоматизация слушает событие текста, а не событие команды. Сообщение с косой чертой приходит как команда.

Вебхуки не запускаются. Проверьте сертификат: интеграция не поддерживает самоподписанные. Также нужно указать доверенные сети Telegram.

Нужен ли бот, если есть приложение

Не вместо, а вместе. Приложение Home Assistant удобнее для управления устройствами и настроек. Telegram выигрывает в уведомлениях и в быстрых командных сценариях, особенно когда в доме несколько человек и приложение установлено не у всех.

Если сервер Home Assistant только настраивается, начните с материала Home Assistant: с чего начать. Про автоматизации есть отдельная статья Автоматизации в Home Assistant: как построить логику.

Часто задаваемые вопросы

Нужен ли статический IP для Telegram-бота?

Нет, в режиме опроса бот сам обращается к серверам Telegram. Внешний доступ нужен только для вебхуков.

Можно ли использовать бота в групповом чате?

Да, для группы нужен отдельный chat ID, он будет отрицательным. Бота надо добавить в группу и разрешить ему читать сообщения.

Что будет, если токен утечёт?

Посторонний сможет отправлять сообщения от имени бота и, если настроены команды, управлять устройствами. Пересоздайте токен у BotFather и обновите интеграцию.

Работает ли бот без интернета?

Нет. Telegram требует соединения. Локальные автоматизации продолжают работать, но уведомления не приходят.

Можно ли отвечать боту голосом?

Можно, но Home Assistant получит файл, а не текст. Для распознавания нужна отдельная обработка.

Сколько чатов можно подключить?

Ограничение задаёт сам Home Assistant и ваш сервер, а не интеграция. На практике добавляют личный чат, семейную группу и чат для уведомлений.