MaxNotify для Home Assistant

MaxNotify подключает мессенджер Max к Home Assistant: можно отправлять сообщения, фото, файлы и видео в чаты и (по желанию) реагировать на входящие сообщения и нажатия кнопок в сценариях. Настройка выполняется через интерфейс Home Assistant, без правки конфигурационных файлов для самой интеграции.

Интеграция умеет работать двумя способами: с официальным API платформы Max и через сервис notify.a161.ru (упрощённый вариант для тех, кто им пользуется). Оба варианта настраиваются в мастере при добавлении записи.

Текущая версия интеграции: 2.0.0. Поддерживается Home Assistant не ниже 2026.2.0 (более старые выпуски могут работать некорректно).

Содержание

Сообщество и поддержка
Важно знать про Max и про notify.a161.ru
Поведение уведомлений и каналы
Что умеет интеграция
Что понадобится заранее
Установка
Первичная настройка
Приём сообщений и сценарии
Кнопки под сообщением
Действия Home Assistant (сервисы)
Удаление сообщений (подробно)
Подробные примеры автоматизаций
Краткий журнал возможностей (по истории коммитов)
Если что-то не работает: журнал
Где взять токен и ID чата
Для разработчиков
Полезные ссылки

Сообщество и поддержка

Новости, обновления и помощь по теме:

Telegram — @kai_zer_ru_ha
Max — kai_zer_ru_ha
Дзен — kai_zer_ru_ha
VK — kai_zer_ru_ha
Обсуждение - Чат в Max
Поддержка автора - Т-Банк

Важно знать

Регистрация бота в Max

Сейчас регистрация разработчика и выпуск бота на платформе Max ориентированы на ИП и организации. Это правила самой платформы, а не интеграции. Для работы через официальный API вам нужен бот и токен из кабинета разработчика.

Сервис notify.a161.ru

Интеграция может работать через прокси notify.a161.ru и бота в Max — те же идеи (отправка, приём, кнопки), но с ограничениями этого сервиса и без ответственности автора MaxNotify за стабильность чужого сайта. Подключение такого режима — на ваше усмотрение и риск.

Кратко, как этот режим устроен в MaxNotify (это единственное место, где перечислены все отличия; дальше по тексту — только отсылки сюда, без повторов):

Чаты: поддерживаются личные (положительный ID) и групповые и каналы (отрицательный ID), как в мессенджере Max: отправка и приём — если это позволяет сервис. Несколько получателей к одной записи — через Добавить чат (как у официального API). Другой токен или полностью отдельная связка настроек — отдельная запись MaxNotify.
Slash-команды: добавить команды бота через API Max в этом режиме нельзя; входящие сообщения вида /команда всё равно обрабатываются — в событии max_notify_received поле command без ведущего / (как при работе через официальный API).
Приём входящих — только опрос сервера (Polling), не WebHook.
Перед отправкой файлов интеграция проверяет размер до 10 МБ на файл.
Если долго не было ни входящих сообщений, ни исходящих с кнопками, интеграция может сама переключить приём на «только отправка» (чтобы снова слушать чат, включите приём в настройках записи).
Между исходящими запросами к одной записи выдерживается пауза около 1 секунды.
Удаление сообщений: по message_id или списку message_ids — поддерживается. Удаление по дате, по интервалу «начало / конец периода для поиска» и действие «удалить последнее исходящее» для notify.a161.ru не поддерживаются (эти режимы есть только у официального API). При вызове недоступной операции Home Assistant покажет переведённую ошибку, запрос к сервису уходит не будет.

Шаги мастера — в разделе Первичная настройка → notify.a161.ru.

Токен

Токен вы получаете у выбранного способа подключения (официальный кабинет Max или бот notify.a161.ru). В описании интеграции считается, что это долгоживущий токен: отдельные сценарии смены пароля и срока жизни здесь не расписываются.

Что умеет

Отправка текста, фото, документов и видео в Max через службу MaxNotify (действия max_notify.send_message, send_photo, send_document, send_video и т.д. в сценариях или вручную в Инструментах разработчика).
Одно сообщение с несколькими вложениями — в интерфейсе действий можно передать список файлов; на стороне интеграции действует общий лимит платформы (до 12 вложений на сообщение, включая inline-клавиатуру), как у официального API Max.
Приём (если включён): новые сообщения и нажатия кнопок попадают в Home Assistant как событие max_notify_received — на него можно повесить сценарии.
Сообщения вида /команда (slash): из текста входящего сообщения в событии заполняется поле command (без ведущего /), плюс args — остаток строки; так можно строить сценарии на команды в чате. Для записи с официальным API в настройках интеграции дополнительно можно задать список slash-команд бота и синхронизировать его с платформой Max. У notify.a161.ru синхронизации команд с бэкендом Max нет, но разбор /команда в пришедшем тексте при включённом приёме сохраняется.
Кнопки под сообщением: задаются в настройках записи и/или в действии отправки; по нажатию можно запускать автоматизации.
Рассылка одним действием всем добавленным чатам во всех записях MaxNotify — действие max_notify.send_text_to_all.
Настройка через Настройки → Устройства и службы; YAML нужен только если вы сами пишете сценарии.

У официального API есть Long Polling и WebHook; у notify.a161.ru вместо них только Polling для приёма. Группы и каналы (отрицательный ID чата) поддерживаются в обоих типах подключения в рамках возможностей платформы; остальные ограничения notify.a161.ru — в разделе Сервис notify.a161.ru.

Поведение уведомлений и каналы

Каналы

Отправка в канал настраивается так же, как в группу: у канала в Max отрицательный идентификатор чата — по тому же принципу, что и у группы. В MaxNotify отдельного режима «канал» не требуется: добавьте получателя с этим ID через Добавить чат, как для группы. Дополнительных параметров интеграции для канала нет; на стороне Max у бота должны быть права администратора в канале (иначе отправка или приём могут работать некорректно — аналогично группам).

Уведомления (push) на разных клиентах

Замечено при тестах (зависит от версии клиента Max и политики платформы, не от Home Assistant):

При отправке в личный чат с ботом уведомления показывают все клиенты Max, даже если отправлять с notify: false.
При отправке в группу или канал с notify: false веб-клиент и десктопное приложение всё равно могут показать уведомление, а мобильное приложение уведомление не показывает. Сообщение при этом доставляется и видно в ленте чата.

Имеется в виду именно системное уведомление / push клиента Max; доставка сообщения в чат через API при этом не гарантирует одинаковое поведение уведомлений на всех платформах.

Что понадобится

Установленный Home Assistant не ниже 2026.2.0.
Для официального API: бот в Max и токен из раздела интеграции (например business.max.ru / документация разработчика).
Для notify.a161.ru: user_id и токен (36 символов), как выдаёт сервис notify.a161.ru.

Установка

Через HACS (рекомендуется)

Если кнопка не сработала: HACS → Интеграции → вверху списка откройте меню (⋯) → Пользовательские репозитории → URL https://github.com/kai-zer-ru/max-notify-ha, категория Интеграция. Установите MaxNotify и перезапустите Home Assistant.

Вручную

Скопируйте папку custom_components/max_notify из этого репозитория в каталог config/custom_components/ вашего Home Assistant и перезапустите систему.

После установки: Настройки → Устройства и службы → Добавить интеграцию → найдите MaxNotify.

Первичная настройка

При добавлении записи сначала выберите тип подключения в списке.

Официальный API Max (platform-api.max.ru)

Укажите токен бота — интеграция проверит его через сеть.
Выберите формат текста: обычный текст, Markdown или HTML (как позволяет API Max).
Выберите режим приёма:
- Только отправка — входящие сообщения не обрабатываются.
- Длинный опрос (Long Polling) — Home Assistant сам опрашивает сервер Max, внешний адрес не нужен.
- WebHook — сервер Max вызывает URL вебхука вашего Home Assistant по HTTPS (входящие запросы к интеграции). Нужен доступный из интернета адрес (не только «домашний» http://192.168.…). Его задают в Настройки → Система → Сеть; часто используют облачный доступ Home Assistant или обратный прокси с сертификатом. В карточке интеграции показывается адрес вебхука; при желании задаётся секрет (проверка заголовка запроса).
Если включён приём не «только отправка», можно настроить кнопки клавиатуры (ряды, подписи, ссылка или «callback» для сценариев).
Добавьте чат: укажите номер получателя. Положительное число — личный диалог, отрицательное — группа или канал. Дополнительные чаты добавляются через меню записи (Добавить чат).

Позже токен и формат можно изменить в Перенастроить; список чатов — в настройках записи.

notify.a161.ru

Получите на notify.a161.ru user_id и токен (36 символов).
Введите токен, формат сообщений и режим: только отправка или Polling (опрос очереди входящих).
Для Polling укажите интервал опроса и период неактивности (1–3 суток); правило автопереключения на «только отправка» — в блоке про сервис.
Укажите ID получателя: положительный — личный чат, отрицательный — группа или канал (как у официального API). Дополнительные чаты — Добавить чат в карточке записи. Чтобы полностью сменить токен или «основную» связку, используйте Перенастроить или новую запись.

Приём сообщений

Когда приём включён, Home Assistant получает событие max_notify_received. Его можно использовать в Сценариях с триггером Событие.

Основные поля (для ответа в тот же чат удобны config_entry_id и recipient_id):

Поле	Зачем нужно
`update_type`	Тип: новое сообщение или нажатие кнопки
`config_entry_id`	Какая запись MaxNotify
`recipient_id`	Куда отвечать (тот же номер, что при добавлении чата): положительный — личный чат, отрицательный — группа или канал
`text`	Текст сообщения
`command`	Если сообщение похоже на команду (например `/start`)
`callback_data`	Данные нажатой кнопки
`message_id`	Номер сообщения (удобно для удаления или правки)
`event_id`	Уникальный ключ события (в т.ч. чтобы не сработать дважды)

Дополнительно в событии могут быть поля вроде user_id и chat_id в формате API Max; для новых сценариев ориентируйтесь на recipient_id.

Официальный API: пока у бота активна подписка WebHook, Long Polling со стороны Max недоступен — в интерфейсе это учтено: сначала переключите режим, если нужно сменить способ приёма. Несколько записей с одним и тем же токеном не могут одновременно конфликтовать (например WebHook в одной и Long Polling в другой) — мастер настройки это блокирует.

На стороне платформы Max для long polling действуют ограничения (в т.ч. не более 2 запросов в секунду к очереди обновлений, таймаут long poll 30 с, размер выборки до 100 событий; подробности — в документации подписок). Интеграция выдерживает паузу между запросами long polling и использует согласованный таймаут; для стабильной работы в продакшене по-прежнему рекомендуется WebHook, если у Home Assistant есть публичный HTTPS (см. Сеть в документации HA). Переключение на WebHook не ломает существующие сценарии на событие max_notify_received, если внешний URL корректно указан в настройках системы.

Если пропал внешний HTTPS для WebHook: при загрузке интеграция может снять подписку в Max и перевести запись в безопасный режим, а в Home Assistant появится заметка о проблеме с подсказкой проверить сеть.

notify.a161.ru: входящие только через Polling; остальные ограничения — в блоке про сервис.

Группы и каналы (официальный API и notify.a161.ru): бота добавляют в группу или канал и по правилам Max выдают нужные права (часто администратор), иначе события или отправка могут работать неполно. ID группы и канала — отрицательный recipient_id (подробнее — Поведение уведомлений и каналы). Для notify.a161.ru дополнительные нюансы — в блоке про сервис.

Кнопки

В настройках записи задаётся постоянная клавиатура (если включён приём не «только отправка» — для официального API это Long Polling или WebHook, для notify.a161 — Polling).
В действии отправки сообщения можно добавить свои кнопки или отключить прикрепление сохранённой клавиатуры.
Тип ссылка открывает сайт; адрес должен начинаться с http:// или https://.
Для кнопок «callback» в сценарии фильтруйте событие по callback_data.

Действия Home Assistant

Все действия начинаются с max_notify. (в интерфейсе — в списке действий службы MaxNotify).

Формат сообщений — в расширенных параметрах действия (блок обычно свёрнут): поле format — text, markdown или html, как при настройке записи. Оно задаёт разметку текста сообщения, подписи к фото/файлу/видео и текста при правке сообщения (edit_message). Если не указать, используется формат, выбранный в настройках интеграции.

Уведомления — в расширенных параметрах отправки есть поле notify (по умолчанию включено). Оставьте true, если нужно обычное сообщение с уведомлением; поставьте false, если нужно попросить Max отправить сообщение без уведомления. Параметр доступен для текста, рассылки всем, фото, документов и видео. Он влияет на тело запроса к Max API, но не гарантирует одинаковое поведение во всех клиентах: по тестам, при notify: false личные чаты всё равно уведомляют везде, а для групп и каналов мобильный клиент уведомление не показывает, тогда как веб и десктоп могут показать.

Пользовательские кнопки — тоже в расширенных параметрах:

send_keyboard — прикладывать ли к этому отправлению клавиатуру из настроек записи (по умолчанию вкл.). Выключите, если нужен только текст или только свои кнопки.
buttons — своя inline-клавиатура только для этого вызова: ряды кнопок (тип callback / message / link с URL http/https). Можно комбинировать с сохранённой клавиатурой, если send_keyboard включён. Готовые примеры структуры — в AUTOMATIONS.md и в подсказке к полю в UI.

Действие	Назначение
send_message	Текст, при необходимости заголовок; в расширенных — формат, `notify`, `send_keyboard`, `buttons`. Получателя указывают сущностью чата Max (создаётся интеграцией) либо вручную: запись MaxNotify + `recipient_id` в расширенных полях.
send_text_to_all	Тот же текст во все добавленные чаты всех записей MaxNotify (записи без ни одного чата пропускаются). В расширенных — формат, `notify`, `send_keyboard`, `buttons`.
send_photo	Фото: файл на диске Home Assistant или ссылка; можно несколько файлов; подпись; в расширенных — формат, `notify`, клавиатура, `buttons`, повторы при обработке вложения на стороне Max.
send_document	Один файл-документ за вызов (только поле `file`, не `files`); подпись, формат, `notify`, клавиатура и `buttons` — как у фото.
send_video	Видео (форматы вроде mp4, mov, webm, mkv); в расширенных — формат, `notify`, клавиатура и `buttons`.
delete_message	Удаление по ID, списку ID, дате (календарный день) или интервалу периода. Подробно — ниже.
delete_last_outgoing_message	Найти и удалить последнее исходящее сообщение бота в групповом чате. Только официальный API Max; у notify.a161.ru недоступно. В личных чатах официальный API не отдаёт историю по `recipient_id` — используйте явный `message_id`.
edit_message	Изменить текст (в т.ч. формат в расширенных), кнопки сообщения или снять их (`remove_buttons`).

В расширенных параметрах у медиа-действий дополнительно при необходимости задаются авторизация для скачивания по ссылке (Basic / Digest / Bearer), отключение проверки SSL (только если понимаете риск), число повторов отправки, пока вложение «готовится» на сервере.

Удаление сообщений (подробно)

Действие max_notify.delete_message объединяет несколько режимов. Ошибки валидации выводятся в интерфейсе Home Assistant с переводом (русский / английский и др., см. translations/ интеграции).

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

Приоритет полей (сверху вниз)

Если задано несколько способов, используется только верхний по списку, остальные игнорируются:

message_id (один или несколько через запятую в одном поле)
message_ids
date — один календарный день в локальной зоне Home Assistant (00:00:00–23:59:59)
Пара полей периода: from и to (в UI: «Начало периода для поиска» / «Конец периода для поиска»)

Период и дата

Интервал: нужно указать оба поля начала и конца или ни одного (если удаляете только по ID / дате). Одна граница без второй — ошибка.
Поле «Дата»: только дата без времени (или Unix timestamp — берётся календарный день момента). Если в значении указано время — ошибка.
Форматы даты и времени (для from / to и для «Даты» как даты): 2026-10-23, 2026.10.23, 2026/10/23, 23.10.2026, 23-10-2026, 23/10/2026; с временем — через пробел или T, время с : или - (например 2026-10-23 00:00:00, 23.10.2026 00-00-00). Допускается Unix timestamp. Неверный формат — ошибка.

Официальный API и notify.a161.ru

Возможность	Официальный API	notify.a161.ru
Удаление по `message_id` / `message_ids`	Да	Да
Удаление по дате или интервалу (поиск в API, затем удаление по одному `message_id` на запрос)	Да	Нет (будет сообщение об ошибке)
Действие `delete_last_outgoing_message`	Да (группы)	Нет

У официального API при запросе списка сообщений за период в query передаётся count (не дублируется запрос с limit).

Лимит частоты: на экземпляр Home Assistant действует общее ограничение не более 30 исходящих HTTP-запросов в секунду ко всем конечным точкам API Max и notify.a161.ru (отправка, удаление, правка, опрос /updates, подписки WebHook и т.д.). Скачивание медиа по произвольным URL в настройках вложений в это ограничение не входит.

Ответ действия

При вызове из UI в ответе может быть объект deleted — сколько сообщений успешно удалено.

Пример вызова вручную (notify.a161.ru, только по ID)

DELETE https://notify.a161.ru/messages?message_id=mid.<ваш_id>
Authorization: <токен из настроек записи>

Подробные YAML-примеры — в AUTOMATIONS.md.

Подробные примеры автоматизаций

Готовые фрагменты YAML (ответ на команду, нажатие кнопки, все параметры действий) собраны в файле AUTOMATIONS.md.

Если что-то не работает: журнал

Чтобы в журнале появлялись подробные сообщения интеграции, в configuration.yaml можно добавить:

logger:
  default: warning
  logs:
    custom_components.max_notify: debug

Перезагрузите Home Assistant и откройте Настройки → Система → Журнал; при необходимости используйте просмотр полного журнала из меню журнала.

Где взять токен и ID

Токен официального бота: кабинет разработчика Max → ваш бот → раздел про интеграцию / API.
User ID и Chat ID: например бот CHECK ID в Max (по пересланному сообщению) или API со списком чатов в документации Max.

Для разработчиков

Описание данных от операторов API и оформление изменений в репозитории: docs/README.md.

Способности бэкенда по типу интеграции задаются в IntegrationCapabilities (см. docs/PROVIDER_SPEC.md), в том числе:

supports_delete_message — удаление по известному message_id;
supports_delete_message_by_period — поиск по дате/интервалу и удаление найденных сообщений (по одному HTTP DELETE на сообщение);
supports_delete_last_outgoing_message — служба «последнее исходящее».

Для notify.a161.ru последние два флага выключены.

Сенсоры ID сообщений: при появлении нескольких чатов на запись идентификаторы сообщений привязаны к чату; старые сенсоры с прежним unique_id могут остаться в системе помеченными как устаревшие — см. журнал и карточку устройства.

Краткий журнал возможностей (по истории коммитов)

Ниже — то, что по смыслу добавлялось в ветке 2.x и релизах 1.4.x, если это не продублировано выше по тексту:

Версия 2.0.0 — архитектура по провайдерам (официальный API и notify.a161.ru), общий код исходящих запросов.
Сенсоры ID сообщений: перестали создаваться устаревшие дубликаты по каждому чату (отдельный unique_id на получателя); остаются актуальные сенсоры по чату и два глобальных устаревших на запись интеграции (для совместимости с прошлыми версиями). Ранее созданные лишние сущности при желании удалите из реестра объектов вручную.
Удаление — по ID/списку; по дате и интервалу (список через GET /messages, затем удаления по одному id) и удаление последнего исходящего в группе — для официального API; ограничения a161 — в таблице выше; глобально до 30 исходящих запросов/с к API.
Несколько вложений в одном сообщении (лимит платформы, до 12 с учётом клавиатуры); исправления приёма и отправки вложений.
Slash-команды — поля command / args в max_notify_received; синхронизация команд с Max — только официальный API.
send_text_to_all — рассылка текста во все чаты всех записей.
Формат текста (text / markdown / html) в сервисах отправки и правки.
notify.a161.ru — polling GET /updates, интервал опроса и период неактивности (автопереход в «только отправка»); пауза ~1 с между исходящими запросами; лимит файла 10 МБ; при сбоях polling — запись в ремонты и подсказки в логах (в т.ч. curl на уровне debug).
Медиа по URL — опциональная авторизация (Basic, Digest, Bearer) и опция отключения проверки SSL для загрузки по ссылке.
WebHook vs Long Polling — взаимное исключение на один токен; WebHook только при HTTPS в настройках HA; при потере HTTPS подписка может быть снята.
Групповые чаты a161 — исправления добавления и работы с отрицательным recipient_id.
Порядок полей в UI сервисов, format в edit_message как выпадающий список, единый стиль services.yaml.
SSL — доработки проверки (в т.ч. wildcard).
Совместимость — при загрузке проверяется минимальная версия Home Assistant (см. в начале README).
Сеть и таймауты — улучшена обработка обрывов при вызовах API Max; для загрузки медиа по URL заданы согласованные таймауты чтения.

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.github		.github
.images		.images
custom_components/max_notify		custom_components/max_notify
docs		docs
tests		tests
.gitignore		.gitignore
AUTOMATIONS.md		AUTOMATIONS.md
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
pytest.ini		pytest.ini
requirements-test.txt		requirements-test.txt

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

MaxNotify для Home Assistant

Содержание

Сообщество и поддержка

Важно знать

Регистрация бота в Max

Сервис notify.a161.ru

Токен

Что умеет

Поведение уведомлений и каналы

Каналы

Уведомления (push) на разных клиентах

Что понадобится

Установка

Через HACS (рекомендуется)

Вручную

Первичная настройка

Официальный API Max (platform-api.max.ru)

notify.a161.ru

Приём сообщений

Кнопки

Действия Home Assistant

Удаление сообщений (подробно)

Приоритет полей (сверху вниз)

Период и дата

Официальный API и notify.a161.ru

Ответ действия

Пример вызова вручную (notify.a161.ru, только по ID)

Подробные примеры автоматизаций

Если что-то не работает: журнал

Где взять токен и ID

Для разработчиков

Краткий журнал возможностей (по истории коммитов)

Полезные ссылки

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 27

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages