Home Assistant: как отправлять сообщения в MAX

Коротко: Готовой интеграции MAX в Home Assistant нет, но это и не обязательно: Home Assistant умеет вызывать HTTP-запросы. Связка собирается из трёх частей: бот и токен на стороне MAX, идентификатор получателя и описание запроса в конфигурации. Рабочий минимум это restcommand с адресом platform-api2.max.ru/messages. Ниже порядок регистрации бота, получение chatid, два способа настройки, лимиты и типичные ошибки.

Уведомления из умного дома это отдельный канал связи с домом, который работает параллельно с приложением Home Assistant. Он не требует держать приложение открытым и не зависит от того, какая экосистема стоит у устройства. Если дома несколько человек, сообщение в общий чат видят все сразу.

Задача этой статьи практическая: превратить событие в доме в короткое сообщение в MAX. Сначала разберём, что для этого нужно со стороны мессенджера, потом два способа описать отправку в Home Assistant, а в конце лимиты и ошибки, из-за которых уведомления чаще всего не приходят.

Зачем дому уведомления в MAX

У многих в доме живут разные люди, которые предпочитают разные мессенджеры. У кого-то Telegram уже стал основным способом связи, а у других MAX стал привычным. Уведомления из Home Assistant не заменяют сирену и не должны быть единственным способом узнать о происшествии. Это короткие сообщения, которые приходят в нужный момент, например о протечке или открытии двери.

Такие сообщения в MAX позволяют держать всех в курсе важных событий без постоянного контроля. Например, когда стирка закончилась или в доме появился дым. Уведомление это дополнительный канал, а не замена основным мерам безопасности. Если нужен более развёрнутый сценарий с реакцией на команды, сначала стоит разобраться с внутренними сценариями: как устроены автоматизации в Home Assistant.

Что такое MAX и его бот-платформа

MAX это российский мессенджер и цифровая платформа, официальный сайт max.ru. Разработчикам доступны ресурсы на dev.max.ru, где есть документация по Bot API. Для управления ботами есть портал business.max.ru/self. Здесь настраивается бот и получается доступ к API.

На GitHub существует официальная организация max-messenger, где размещена схема API. Это основной источник информации для разработчиков. Интеграция возможна через API, но требует точного соблюдения форматов и правил, а актуальность данных стоит проверять по документации платформы.

Регистрация бота и токен доступа

Для подключения Home Assistant к MAX нужно зарегистрировать бота в разделе business.max.ru/self. Там можно создать аккаунт для бота, указав название и описание. После регистрации система выдаст токен доступа, который нужно сохранить. По документации подключение доступно юрлицам, ИП и самозанятым резидентам РФ, поэтому обычному человеку без такого статуса бота не завести.

Токен доступа это секретный ключ, который нельзя публиковать или передавать другим. Его нужно хранить в secrets.yaml Home Assistant. При настройке уведомлений токен используется для авторизации бота в MAX, и его нельзя коммитить в репозитории.

Как получить chatid и userid

Чтобы получить chatid и userid, нужно использовать события бота. Готового метода, который просто вернёт идентификатор, нет: chatid приходит в событиях подписки botadded и bot_started, когда бота добавляют в чат или запускают. Практический путь такой: подписаться на события бота, запустить его в нужном чате и забрать идентификатор из данных события. Ещё один источник это WebApp, где данные чата приходят приложению.

Перед отправкой сообщений стоит проверить, что chatid и userid корректны и что бот активен в нужном чате. Если идентификатор взят из другого чата или бот из него удалён, запрос вернёт ошибку.

Почему в Home Assistant нет готовой интеграции MAX

В официальном каталоге интеграций Home Assistant нет поддержки MAX. Это значит, что для отправки уведомлений в мессенджер придётся использовать сторонние решения или прямые запросы. На GitHub существует community-интеграция max-notify-ha, которую можно установить через HACS. Она не поддерживается разработчиками Home Assistant и может перестать обновляться.

Основной способ это HTTP-запросы к API MAX. Они не зависят от сторонних компонентов: даже если community-интеграция прекратит работу, прямые запросы останутся действующими. Если вы только начинаете, сначала полезно пройти базовую настройку: с чего начать в Home Assistant.

Отправка через rest_command

restcommand в Home Assistant позволяет отправлять HTTP-запросы. Для MAX используется адрес https://platform-api2.max.ru/messages, метод POST. В заголовке указывается Authorization с токеном и Content-Type application/json. В теле запроса нужно указать поле text с текстом сообщения, а в URL добавляется параметр userid или chat_id для указания получателя.

Токен сохраняется в secrets.yaml, чтобы он не был виден в конфигурации. В конфигурации используется синтаксис !secret, например в заголовке Authorization подставляется !secret max_token. В примере из документации MAX в этом заголовке передаётся сам токен доступа.

Пример тела запроса: { "text": "Внимание, утечка воды!" }. Перед отправкой проверьте, что URL содержит нужный userid или chatid. Если запрос уходит в общий чат, идентификатор берётся из chatid, а не из userid.

Отправка через notify на базе REST

В Home Assistant есть платформа notify rest, которая удобна для автоматизации. Она вызывается как обычное уведомление, что упрощает использование. Для MAX нужно указать resource с адресом platform-api2.max.ru/messages, метод POST_JSON и заголовок Authorization. Поле text будет содержать текст сообщения.

Разница между двумя способами видна в таблице.

Если структура запроса сложнее, например нужны дополнительные параметры или вложения, лучше использовать rest_command. Для простого текстового уведомления хватит платформы notify.

Формат сообщения, вложения и кнопки

MAX принимает текст длиной до 4000 символов. Поле format позволяет выбрать оформление, markdown или html. Поле notify отключает push-уведомление, если сообщение не должно будить ночью. Вложения добавляются в массив attachments, где можно указать типы image, video, audio, file, sticker, contact, inline_keyboard, share и location. Для дома обычно достаточно текста и изображения с камеры, например при обнаружении движения.

Кнопки добавляются через inline_keyboard в attachments. Нажатие на кнопку возвращается боту событием, и чтобы оно привело к действию, нужна отдельная обработка этого события. Для большинства домашних задач это лишняя сложность: чаще достаточно текста и понятного описания того, что произошло.

Автоматизации дома с уведомлениями в MAX

Уведомления в MAX помогают отслеживать ключевые события в доме. Например, при срабатывании датчика протечки система отправляет сообщение с указанием места и времени. Так же работают датчик дыма или датчик открытия входной двери. Уведомления не заменяют сирену или автоматическое перекрытие воды, но позволяют вовремя узнать о происшествии.

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

Ещё один довод в пользу мессенджера: сообщение приходит всем, кто есть в чате, и не требует установки отдельного приложения. Это удобно, когда дома есть пожилые родственники или когда кто-то приезжает на дачу по выходным.

Лимиты, безопасность и типичные ошибки

Лимиты и безопасность важны при настройке. MAX допускает не больше 2 сообщений в секунду в одном диалоге и до 30 запросов в секунду к платформе. Токен храните в secrets.yaml и не пересылайте его в чат. Для дома создайте отдельный диалог под уведомления, чтобы не смешивать их с личной перепиской.

Типичные ошибки: токен указан в неправильном заголовке, из-за чего приходит отказ в авторизации; неверный идентификатор получателя; бот не подписан на нужные события; токен истёк или перевыпущен. Проверяйте, подписан ли бот на события и соответствует ли токен формату. Если бот запускается, но сообщения не приходят, начните проверку с идентификатора получателя.

Частые вопросы

Есть ли официальная интеграция MAX для Home Assistant

Нет. В официальном каталоге интеграций Home Assistant интеграции MAX нет. Есть community-компонент max-notify-ha для HACS, но он не является официальным и может перестать обновляться.

Как получить токен бота MAX

Бот создаётся в кабинете на business.max.ru/self, там же выдаётся токен доступа. По документации подключение доступно юрлицам, ИП и самозанятым резидентам РФ.

Где взять chat_id для уведомлений

Отдельного метода, который просто вернёт chatid, нет. Идентификатор приходит в событиях подписки botadded и bot_started, а также может быть получен через WebApp.

Чем отправка в MAX отличается от Telegram-бота

В Telegram у Home Assistant есть официальная интеграция telegrambot, поэтому там достаточно ввести токен в интерфейсе. Для MAX такой интеграции нет, и запрос описывается вручную через restcommand или notify. Подробнее про этот путь: Telegram-бот для Home Assistant.

Что делать, если сообщение не приходит

Проверьте четыре вещи: правильный ли заголовок Authorization, корректный ли chatid или userid, подписан ли бот на события и не истёк ли токен. Ошибка авторизации указывает на токен, а неверный идентификатор получателя даёт ошибку по адресу запроса.