Уведомления в MAX

Компонент отправляет уведомления сайта в мессенджер MAX через вашего чат-бота. Пользователи подключают MAX в профиле и сами выбирают, какие уведомления получать. Администраторы получают служебные события сайта. Новые записи сайта можно автоматически публиковать в ваши каналы MAX.

Что делает компонент

Дублирует уведомления сайта в MAX: комментарии, ответы, личные сообщения, подписки, оценки и уведомления других компонентов, которые используют штатную систему уведомлений InstantCMS.
Присылает администраторам служебные события: новый пользователь, материал или комментарий на модерации, новый комментарий, отправленная форма, новый материал, удаление пользователя.
Публикует новые записи в каналы MAX: заголовок, обложка, краткое описание и кнопка «Читать на сайте» — см. «Автопостинг в каналы».
Даёт пользователю управлять подпиской: подключение одной кнопкой, выбор уведомлений галочками, команды /stop и /start в боте.
Не мешает работе сайта: сообщения уходят через штатную очередь, ядро CMS не изменяется.

Уведомление получает только тот, кто сам подключил MAX и не выключил этот тип уведомлений.

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

Требование	Пояснение
InstantCMS 2.18.2 или новее
PHP с расширениями cURL и OpenSSL	Есть почти на любом хостинге. Работа проверена на PHP 8.4
Сайт на HTTPS с действующим сертификатом	Нужен, чтобы MAX мгновенно передавал сайту нажатия «Старт» и команды. Без HTTPS тоже работает — см. «Сайт без HTTPS»
Планировщик: cron раз в минуту	Уведомления уходят через штатную очередь InstantCMS
Свой чат-бот в MAX	Создаётся на business.max.ru. Доступно юрлицам, ИП и самозанятым — резидентам РФ. Бот проходит модерацию MAX, обычно за сутки

Сертификаты Минцифры

Ничего устанавливать не нужно. API MAX работает с сертификатом Национального удостоверяющего центра Минцифры. В компонент уже встроен набор корневых сертификатов, в том числе Минцифры, и подключается он автоматически. На сервере и в браузере ничего настраивать не нужно.

Проверить можно на странице Компоненты → Уведомления в MAX → Состояние: в строке «Сертификаты» должно быть «встроенный набор». Поле Опции → Путь к CA bundle оставьте пустым. Оно нужно, только если администратор сервера просит использовать свой файл сертификатов.

Бот и токен в MAX

Создайте бота на business.max.ru и дождитесь, когда он пройдёт модерацию.
В чате с ботом платформы нажмите «Получить токен» и скопируйте его.

Токен — это пароль к боту: не публикуйте его и не передавайте третьим лицам. Один бот обслуживает один сайт, для нескольких сайтов нужны отдельные боты.

Установка и обновление

Сделайте резервную копию файлов и базы данных сайта.
Откройте Дополнения → Установить пакет дополнения, выберите ZIP-архив и нажмите «Продолжить».
Для обновления с предыдущей версии используйте архив с пометкой update. Настройки и подключённые пользователи сохранятся.

При установке создаются шесть таблиц {префикс}maxnotify_* и две задачи планировщика. Ядро CMS не изменяется.

Обновление с 0.1.x. Если webhook был подключён, установщик сам переподпишет его на новые события — о добавлении бота в каналы. Если на странице «Состояние» появилось предупреждение о подписке, нажмите «Подключить webhook» ещё раз.

Настройка за 5 минут

Откройте Компоненты → Уведомления в MAX. На странице «Состояние» есть список шагов, выполненные отмечаются галочкой.

Опции → Бот: вставьте токен в поле «Токен бота» и сохраните.
Состояние → «Проверить подключение». Должно появиться «Подключение работает: бот „…“».
Состояние → «Подключить webhook». Должно появиться «Webhook подключён».
Подключите MAX себе: Профиль → Настройки → Уведомления → «Подключить MAX» → в чате с ботом нажмите «Старт». Бот ответит «Аккаунт … подключён».
Состояние → «Отправить тест себе». В MAX придёт тестовое сообщение.

Опции

Пользователи

Разрешить пользователям подключать MAX. Выключите, если MAX нужен только администраторам.
Группы, которым доступно подключение.
Уведомления, включённые сразу после подключения. Если ничего не выбрано, включаются все. Пользователь потом меняет набор у себя в профиле.
Срок действия ссылки подключения — по умолчанию 15 минут.

Администраторам

Служебные события получает каждый администратор сайта, который подключил MAX в своём профиле. Чтобы добавить других получателей, например группу «Администраторы» или «Модераторы», выберите её в поле «Дополнительные группы получателей».
Для каждого события есть отдельный переключатель.
О собственных действиях администратор уведомление не получает: например, если он сам добавил материал или оставил комментарий, сообщение уйдёт только другим администраторам.

«Копия всех уведомлений пользователей» и «Копия всех исходящих писем» нужны только для отладки. Первая пересылает администраторам в том числе начало личных сообщений пользователей, вторая — все письма сайта. На рабочем сайте держите обе выключенными.

Формат и доставка

Заголовок сообщения — первая строка каждого уведомления жирным, например название сайта.
Отправлять через очередь — оставьте включённым: страницы сайта не ждут ответа MAX.
Хранить журнал — сколько дней хранить журнал отправок. Старые записи удаляет задача планировщика.

Автопостинг в каналы

Кто видит галочку «Не публиковать в MAX» в форме добавления записи. «Все» — любой, кто может добавлять записи. Администраторы видят её всегда. Сами каналы и правила публикации настраиваются во вкладке «Автопостинг».

Сайт без HTTPS или тестовый сайт

MAX отправляет события только на HTTPS-адрес с доверенным сертификатом (порт 443). Для тестового сайта выберите Опции → Получение событий от MAX → Опрос раз в минуту. Тогда компонент сам забирает события через планировщик, и подключение пользователя срабатывает в течение минуты.

Если раньше был подключён webhook, сначала нажмите «Отключить webhook»: пока он активен, опрос не работает.

Что видит пользователь

Профиль → Настройки → Уведомления → блок «Уведомления в MAX»: кнопка «Подключить MAX», после подключения — галочки, какие уведомления присылать.
В MAX уведомление приходит в том же виде, что и на сайте, с кнопками «Открыть» и «⚙ Настроить».
Команды бота: /stop — приостановить уведомления, /start — возобновить, любое другое сообщение — узнать текущее состояние.
Отключение — ссылка «Отключить MAX» в профиле. Если пользователь остановит или удалит бота, отправка ему прекратится автоматически.

Уведомление приходит в MAX, если этот тип уведомлений не выключен у пользователя в стандартных настройках сайта.

Автопостинг в каналы MAX

Новые записи сайта — новости, статьи, дополнения, любые типы контента — публикуются постами в ваши каналы MAX через того же бота. Пост состоит из заголовка жирным, обложки записи, краткого описания и кнопки «Читать на сайте». Всё настраивается во вкладке Компоненты → Уведомления в MAX → Автопостинг.

Подключить канал

Откройте свой канал в MAX → настройки канала → «Администраторы». Добавьте бота сайта администратором и включите право публиковать посты.
Откройте вкладку Автопостинг. Канал появится в списке сам, вводить его ID не нужно. Администраторам сайта, подключившим MAX, бот пришлёт сообщение «Бот добавлен в канал».
Нажмите «Проверить права». Должно появиться «Бот может публиковать».
Нажмите «Настроить», выберите типы контента и включите «Публиковать новые записи в этот канал».
По желанию нажмите «Тестовый пост». Его увидят все подписчики канала.

Сайт узнаёт о новом канале из событий MAX, поэтому webhook должен быть подключён (или включён опрос). Если бота добавили в канал раньше, чем подключили webhook, уберите бота из администраторов канала и добавьте снова.

Добавить бота в канал может любой владелец канала, но публиковать туда сайт начнёт только после того, как вы включите канал в настройках. Лишний канал уберите из списка кнопкой ✕ — из самого канала бот при этом не выйдет.

Точно так же подключается групповой чат: в списке он отмечен как «группа».

Настройки канала

Поле	Что делает
Публиковать новые записи в этот канал	Главный выключатель. Выключенный канал остаётся в списке, но ничего не получает
Типы контента	Записи каких типов публиковать. Можно выбрать несколько; у каждого канала свой набор
Длина краткого описания	По умолчанию 300 символов, одна для всех типов. Текст обрезается по границе слова
Текст кнопки	По умолчанию «Читать на сайте». Кнопка открывает запись. Пусто — пост без кнопки

Настройки по типам контента. Для каждого отмеченного типа ниже появляется свой блок, потому что у типов разные поля:

Поле	Что делает
Обложка	Из какого поля-изображения брать картинку. «Автоматически» — штатное поле «photo», а если его нет — первое поле-изображение типа. Можно выбрать другое поле, например «Обложка» вместо «Иконки», или «Без обложки»
Размер обложки	Пресет изображения из настроек сайта. «Автоматически» — «Большой». Если у записи нет картинки выбранного размера, берётся ближайший доступный. Для MAX подходит 600–1200 пикселей по ширине. MAX скачивает картинку по адресу на сайте, поэтому сайт должен быть доступен из интернета
Краткое описание	Из какого поля брать текст. «Автоматически» — штатное «teaser», затем «content», затем SEO-описание. Можно выбрать любое текстовое поле типа, SEO-описание или «Без описания». Если у записи выбранное поле пустое, описание подбирается автоматически

Какие записи публикуются

Публикуются новые записи выбранных типов, как только они появились на сайте: сразу после добавления, после одобрения модератором, после публикации черновика или в дату отложенной публикации.
Не публикуются правки уже опубликованных записей, записи на модерации и в черновиках, скрытые, удалённые и доступные не всем (например, «только друзьям»).
Одна запись попадает в один канал только один раз.
Правка или удаление записи на сайте пост в канале не меняет.

Галочка «Не публиковать в MAX». В форме добавления записи, в блоке «Настройки публикации», появляется переключатель: с ним запись не уйдёт ни в один канал. Он виден, только если запись этого типа действительно попадёт хотя бы в один включённый канал. Кому он доступен, задаётся в опциях.

Отложенные записи. InstantCMS публикует их задачей планировщика «Публикация контента по расписанию», и пост в канал уходит в тот же момент. По умолчанию задача запускается раз в сутки. Чтобы посты выходили вовремя, откройте Настройки → Планировщик и поставьте этой задаче период 5–10 минут.

Журнал публикаций

Под списком каналов — последние публикации: запись, канал и состояние.

В очереди — пост уйдёт при следующем запуске планировщика (обычно в течение минуты).
Опубликовано — пост вышел в канале.
Ошибка — MAX не принял пост; под статусом виден ответ MAX. Временные ошибки очередь повторяет сама.
Пропущено — публикацию в канал выключили, у бота нет прав, запись скрыли до отправки или автор отключил публикацию галочкой.

Кнопка «Опубликовать» у ошибки или пропуска отправляет запись ещё раз. Для записи, где автор включил «Не публиковать в MAX», она снимает эту отметку и публикует запись во все подходящие каналы.

Если что-то не так

Признак	Что проверить
«Проверить подключение»: ошибка 401	Токен скопирован не полностью или бот ещё не прошёл модерацию
«Проверить подключение»: Connection error	Хостинг не пропускает исходящие HTTPS-запросы к `platform-api2.max.ru`. Обратитесь в поддержку хостинга
«Webhook работает только на сайте с HTTPS»	Адрес сайта в настройках CMS начинается с `http://`. Включите HTTPS или используйте опрос
Бот пишет «Ссылка устарела»	Прошло больше 15 минут. Нажмите «Подключить MAX» ещё раз
Бот не отвечает на «Старт»	На странице «Состояние» webhook должен быть «подключён». При опросе проверьте, что работает cron
Уведомления не приходят	Проверьте счётчики «Отправлено» и «Ошибок за 24 ч» на странице «Состояние», а также что задача планировщика «Выполняет задачи системной очереди» активна
Канал не появился во вкладке «Автопостинг»	Проверьте, что webhook подключён и на «Состоянии» нет предупреждения о подписке. Затем уберите бота из администраторов канала и добавьте снова
Канал: «Нет права публиковать»	Сделайте бота администратором канала с правом публиковать посты и нажмите «Проверить права»
Пост ушёл без картинки или не с той картинкой	Проверьте в настройках канала поле «Обложка» для этого типа контента. Если поле выбрано верно, значит у записи нет картинки или MAX не смог её скачать: сайт должен открываться из интернета
Отложенная запись вышла в канал позже	Уменьшите период задачи «Публикация контента по расписанию» — см. «Какие записи публикуются»
Публикация долго «В очереди»	Проверьте, что работает cron и активна задача «Выполняет задачи системной очереди»
«Сертификаты: системные»	Файл `system/controllers/maxnotify/libs/certs/ca-bundle.pem` не загрузился. Переустановите пакет

Правила MAX

Правила платформы MAX ограничивают массовые рассылки и рекламу через ботов. Компонент отправляет сообщения только тем, кто сам подключил MAX, и не делает рассылок «всем». Не отправляйте через бота рекламу. Если на сайте тысячи подписчиков, уточните условия у MAX.

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

Удаление

Сначала нажмите «Отключить webhook», затем Компоненты → Уведомления в MAX → Удалить. Таблицы с привязками, каналами и журналом публикаций остаются в базе, чтобы после повторной установки пользователям не пришлось подключаться заново, а записи не опубликовались в каналы повторно.

Установщик покажет список файлов компонента для ручного удаления. Папку docs/_shared удалять не нужно: это общее оформление руководств других дополнений автора.