Документация плагина WP Ru-max

WP Ru-max связывает WordPress с мессенджером MAX и социальными сетями. Плагин отправляет публикации и уведомления, планирует автопостинг, добавляет виджет связи с клиентами и сохраняет историю операций.

Документация соответствует интерфейсу WP Ru-max 1.0.54. Названия пунктов могут немного отличаться после обновления плагина.

1. Быстрый старт

Рабочая последовательность для нового сайта:

1. Установите и активируйте плагин в WordPress.
2. Откройте вкладку Активация и активируйте лицензию. Без лицензии часть функций может быть заблокирована.
3. В кабинете MAX для партнёров создайте чат-бота, пройдите модерацию и получите Bot Token.
4. На вкладке Главная вставьте Bot Token, сохраните его и нажмите Проверить подключение.
5. Добавьте канал или чат MAX в настройках публикаций, чтобы плагин знал, куда отправлять записи.
6. Если нужны другие площадки, подключите их на вкладке Социальные сети.
7. Включите только необходимые модули: отправку публикаций, уведомления, автопостинг или виджеты.
8. Создайте тестовую запись и проверьте результат в каждой подключённой сети.

Требования и общие правила

• Работающий WordPress с правами администратора.
• Для WooCommerce-уведомлений должен быть установлен и активен WooCommerce.
• Сервер должен выполнять исходящие HTTPS-запросы к API подключённых платформ.
• Для очередей и отложенных публикаций нужен работающий WP-Cron либо системный cron хостинга.
• После изменения любого раздела нажимайте именно его кнопку Сохранить. Переключение вкладки само по себе не всегда сохраняет данные.

2. Главная

Здесь задаётся основное подключение к MAX. Эти данные используются отправкой публикаций, личными уведомлениями, MAX-виджетом и авторизацией через Mini App.

Токен MAX создаётся в business.max.ru: создайте профиль организации, пройдите верификацию, откройте «Чат-боты», создайте бота, отправьте его на модерацию, затем в разделе «Интеграция» получите токен. В интерфейсе запроса лицензии отдельно указано, что получить токен бота MAX могут ИП или ООО.

3. Отправка публикаций

Модуль автоматически отправляет записи WordPress в один или несколько каналов MAX. Настройки раздела относятся к MAX; публикации в Telegram, VK, Одноклассники и Дзен настраиваются отдельно.

Включение и назначение

Правила отправки

Фильтры категорий и тегов

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

Задержка, повторы и изображения

Отложенные задания обрабатываются очередью WordPress. Для надёжной доставки на сайте с небольшим трафиком настройте системный cron хостинга на обращение к wp-cron.php примерно раз в 1–2 минуты.

Шаблон сообщения

Если поле оставить пустым, используется стандартный формат. В пользовательском шаблоне доступны переменные:

Поля Встроенные кнопки клавиатуры добавляют кнопки под каждой публикацией. Для каждой кнопки укажите видимый текст и полный URL, затем нажмите «Добавить кнопку» и сохраните раздел.

Тестовое сообщение открывает поле ID чата. Укажите тестовый канал или чат и отправьте сообщение, чтобы проверить токен, права и формат.

4. Личные уведомления

Модуль перехватывает письма, которые сайт отправляет через wp_mail(), и дублирует выбранные уведомления в MAX. Исходная отправка писем пользователям сайта не изменяется.

Основные поля

События WordPress и WooCommerce

• Обновления плагинов — уведомляет об обновлениях.
• Критические ошибки сайта — отправляет уведомление о критической PHP-ошибке, если WordPress передаёт такое событие.
• Регистрация пользователя — дублирует письмо о новой регистрации.
• Клиентские письма WooCommerce — включает дублирование писем клиентского контура WooCommerce.

Переключатели уведомлений влияют только на копию в MAX. Они не выключают штатные письма WordPress или WooCommerce.

WooCommerce — фильтр заказов

Включите фильтр WooCommerce, чтобы уведомления отправлялись только при выбранных статусах. Доступны:

Если включённый фильтр не содержит ни одного выбранного статуса, уведомления WooCommerce не отправляются.

Защита от дублей

Опция Блокировать повторные уведомления с одинаковым #ID в теме письма ищет первое число вида #NNNN в теме email. Второе письмо с тем же номером в заданном окне пропускается. Если номера нет, письмо проходит как обычно.

Окно дедупликации (сек) задаёт срок хранения отметки. Допустимы значения 5–3600 секунд; значение по умолчанию — 30 секунд. Эта защита не заменяет WooCommerce-фильтр: для заказов используйте оба механизма по необходимости.

Встроенные кнопки клавиатуры настраиваются так же, как в публикациях: текст кнопки плюс URL.

5. Дополнительные

Технический блок показывает версию WP Ru-max, версию WordPress и PHP, наличие cURL и базовый URL API. Эти сведения полезны при обращении в поддержку.

6. Автопостинг

Автопостинг создаёт задания на публикацию записи в выбранных социальных сетях. Для каждой сети результат и повторные попытки обрабатываются независимо.

Как создать задание

1. Откройте вкладку Календарь внутри раздела «Автопостинг» и нажмите нужную дату.
2. Выберите статью, одну или несколько социальных сетей, дату и время.
3. Нажмите Сохранить. Карточка задания появится в календаре.
4. При необходимости перетащите запланированную карточку на другую дату или время.

Время задания берётся из часового пояса WordPress. Синие карточки обозначают запланированные задания, зелёные — выполненные. Публикации без поддерживаемого подключения или без необходимых прав будут завершаться ошибкой.

Вкладка «Настройки»

Вкладка «Уведомления»

• Включить email-уведомления — включает письма о работе очереди.
• Получатели — один или несколько email через запятую или пробел.
• Успешная публикация — письмо после успешной отправки.
• Ошибка после всех попыток — письмо только после исчерпания повторов.

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

7. Чат-виджет MAX

Виджет показывает плавающий значок MAX и может выводить приветствие, звук, анимацию и окно удержания.

Основные настройки

UTM-метки и Яндекс.Метрика

Поля UTM source, UTM medium, UTM campaign и UTM content добавляются к ссылке виджета. Пример:

utm_source=site&utm_medium=chat_widget&utm_campaign=spring

Включите Яндекс.Метрику, укажите номер счётчика и цель reachGoal. При нажатии на виджет плагин отправляет указанную цель. Убедитесь, что счётчик Метрики уже установлен на сайте.

Показы, скрытие и звук

Звук используйте умеренно: неожиданный сигнал может ухудшить пользовательский опыт. Проверьте работу на мобильных устройствах и учтите, что браузер может блокировать автоматическое воспроизведение.

Анимация и окно удержания

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

Опция Удержание показывает попап при закрытии приветствия. В нём можно задать:

• заголовок и основной текст;
• выравнивание текста и кнопок;
• текст кнопок «Остаться» и «Уйти»;
• радиус скругления кнопок от 0 до 50 px;
• цвет фона и текста обеих кнопок.

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

8. Связь с клиентами

PRO-модуль создаёт единый виджет с дополнительными каналами связи, живым чатом, FAQ и контактной формой.

Каналы и порядок

В разделе «Шаг 1: Выберите свои каналы» доступны:

• Телефон — номер в формате, который можно набрать на устройстве клиента.
• Telegram — username или ссылка.
• ВКонтакте — ссылка на профиль, сообщество или диалог.
• Форма обратной связи — форма, данные которой появляются в админке.
• Email — email для связи.

Перетаскивайте карточки каналов, чтобы изменить порядок. У каждого стандартного канала можно включить отображение на ПК и на мобильных устройствах, а также заполнить его значение. Можно добавить произвольную ссылку: укажите название, URL и URL иконки.

Виджет и внешний вид

Размер, положение и нижний отступ основного значка MAX берутся из вкладки Чат-виджет MAX основного плагина и применяются также к PRO-виджету.

Живой чат

• Показывать значок «Живой чат» — включает канал живого чата.
• Менеджер онлайн — показывает посетителю, что менеджер доступен.
• Чат MAX / идентификатор получателя — куда дублировать обращение менеджеру.
• Название и приветствие — тексты в окне чата.
• Автоответ бота — сообщение, которое посетитель получает автоматически до ответа менеджера.

В расписании включите ограничение рабочими часами, отметьте дни недели и задайте время «С» и «До». Вне расписания значок живого чата не показывается.

FAQ, быстрые кнопки и обращения

Включите Частые вопросы, добавьте пары «Вопрос — Ответ». Быстрые кнопки позволяют заранее создать варианты сообщения, которые посетитель выбирает одним нажатием. Контактная форма собирает обращение и контактные данные.

На вкладке Заявки с формы доступны фильтры «Все», «Открытые» и «Завершённые». В каждой заявке видны переписка, имя, email и телефон; менеджер может написать ответ и завершить обработку. На вкладке Живой чат отображаются входящие сообщения живых диалогов.

9. Социальные сети

Вкладка содержит отдельные настройки Telegram, Одноклассников, ВКонтакте и Яндекс Дзен. Каждая сеть может быть включена независимо. После заполнения нажмите Сохранить настройки.

Telegram

Плагин поддерживает несколько Telegram-ботов. Каждый бот может публиковать в несколько каналов и групп.

Создание бота

1. Откройте Telegram и найдите @BotFather.
2. Отправьте команду /newbot.
3. Задайте отображаемое имя и username, который заканчивается на bot.
4. Скопируйте токен, который выдаст BotFather.
5. Добавьте бота администратором в нужный канал или группу с правом публикации сообщений.

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

Одноклассники

1. Откройте apiok.ru/dev/app/create и войдите в аккаунт владельца нужного сообщества.
2. Создайте приложение для работы с API и сохраните его реквизиты.
3. Получите OAuth Access Token с правами, необходимыми для публикации.
4. Включите публикацию и заполните поля в плагине.

Если API OK принимает приложение, но публикация не появляется, проверьте, что токен принадлежит администратору сообщества и что ID группы указан без ошибки.

ВКонтакте

Часть 1. Приложение сообщества в dev.vk.ru

Что подготовить в кабинете VK

1. Откройте список приложений VK под аккаунтом администратора сообщества.
2. Создайте или откройте приложение сообщества, убедитесь, что оно включено и OAuth не заблокирован.
3. Сохраните числовой ID приложения, защищённый ключ и Community Access Token.
4. Укажите ID сообщества отдельно. Для группы/паблика это отрицательное число, например -123456789.

Часть 2. Web-приложение VK ID в id.vk.ru

1. Откройте кабинет VK ID и откройте Web-приложение.
2. В поле «Базовый домен» укажите домен без протокола и пути, например ваш-сайт.ru.
3. В поле «Доверенный Redirect URL» добавьте адрес https://ваш-сайт.ru/wp-ru-max-vk-callback/, сформированный для вашего сайта.
4. Сохраните настройки. Не добавляйте query-параметры, не заменяйте HTTPS на HTTP, не добавляйте www и не убирайте завершающий слеш, если плагин его показывает.

Поля в плагине

Разница между двумя идентификаторами приложения

Нажмите Авторизовать сообщество VK. Плагин сначала сохраняет введённые настройки, затем запускает OAuth, запрашивая права photos, wall и groups. Пользовательский токен для фото сохраняется отдельно; уже сохранённый токен сообщества не удаляется при отмене авторизации.

Проверка публикации фото VK

1. У записи должна быть миниатюра либо первая картинка в содержимом.
2. URL изображения должен быть доступен серверу WordPress по HTTPS без Basic Auth и ограничений по User-Agent.
3. После авторизации создайте новую тестовую запись или запустите повторную публикацию.
4. Если фото не отправилось, смотрите точную причину в истории: нет изображения, нет пользовательского токена, VK не выдал URL загрузки, WordPress не скачал картинку или VK отклонил сохранение на стене.

Яндекс Дзен

Основной сценарий — публикация через RSS-синдикацию. Это самый простой способ и обычно не требует API-токена.

1. Войдите на dzen.ru под аккаунтом Яндекс.
2. Откройте настройки канала и раздел Внешние источники.
3. Добавьте RSS-ленту сайта, обычно https://ваш-сайт.ru/feed/.
4. Включите публикацию в плагине и укажите тот же URL RSS.
5. Если выбран API-сценарий, укажите ID канала и OAuth-токен из кабинета разработчика Яндекса.

Общие параметры публикаций в социальные сети

Отдельные шаблоны для сетей

В блоке шаблонов выберите нужную сеть и заполните шаблон. Поддерживаются переменные записи, а также HTML-теги <b>, <i>, <u> и ссылка <a href="...">текст</a>, если конкретная сеть принимает такой формат.

Для каждой сети доступны:

• свой шаблон текста;
• переключатель кнопки или ссылки «Читать далее»;
• текст кнопки/ссылки;
• обрезка по лимиту платформы.

Для ВКонтакте настоящая inline-кнопка в записи стены не поддерживается, поэтому плагин добавляет кликабельную ссылку. Если обрезка выключена и текст превышает лимит платформы, публикация может быть пропущена; если включена — текст обрезается до допустимого размера.

10. Прямой доступ

Раздел отправляет произвольное сообщение напрямую в подключённую сеть, без записи WordPress и без очереди публикаций.

1. Сначала подключите хотя бы одну сеть в разделе «Социальные сети» или настройте MAX на вкладке «Главная».
2. Выберите нужную сеть. Отображаются только сети, для которых найдено рабочее подключение.
3. Заполните поля и нажмите кнопку отправки.

11. История

История хранит технические записи работы плагина. Фильтр помогает отделить ошибки разных модулей:

• MAX/API — запросы к MAX API, ответы и ошибки подключения;
• Публикации — отправка записей и отложенная очередь;
• Уведомления — перехваченные и доставленные письма;
• Тесты — результаты тестовой отправки;
• Настройки — операции сохранения;
• Прямой доступ — ручные сообщения;
• Социальные сети — Telegram, VK, OK и Дзен;
• Старый Push — записи прежнего механизма push-уведомлений, если они остались в базе.

Тест подключения создаёт проверочную запись API. Обновить перечитывает список. Очистить журналы удаляет записи истории — перед очисткой сохраните нужные сведения для диагностики. Пагинация используется при большом количестве записей.

Что искать в ошибке

• HTTP-код, код ошибки API и полный текст ответа;
• какая сеть и какой получатель использовались;
• номер попытки и сообщение о повторе;
• не превышен ли лимит текста или изображения;
• не пустой ли Chat ID и не отозван ли токен;
• для VK-фото — на каком именно шаге остановилась загрузка.

12. Инструкция в плагине

Вкладка Инструкция содержит пошаговые справочные вкладки для MAX, Telegram, Одноклассников, ВКонтакте и Яндекс Дзен. Это краткая версия подключения, которую удобно открыть прямо из админки.

В инструкции MAX отдельно описаны создание организации, создание и модерация бота, получение токена, добавление канала и настройка Mini App. В инструкции VK обращайте особое внимание на точный Redirect URL и на разницу между приложением сообщества и Web-приложением VK ID.

13. Обновления

На вкладке Обновления отображается доступность новой версии и история версий. Перед обновлением:

1. сделайте резервную копию сайта и базы данных;
2. сохраните текущие токены и ключи в защищённом менеджере;
3. проверьте, что очередь автопостинга не содержит критичных заданий;
4. после обновления проверьте подключение MAX и выполните тестовую отправку.

14. Активация

Ввод ключа

Введите лицензионный ключ в поле Лицензионный ключ и нажмите Активировать. Плагин проверяет ключ на сервере лицензий и привязывает его к домену сайта. Количество оставшихся попыток отображается рядом с формой.

При большом количестве неверных попыток включается временная блокировка. Не перебирайте варианты ключа: проверьте раскладку, пробелы, домен и источник лицензии.

Статус активной лицензии

После успешной активации отображаются:

• домен привязки;
• дата активации;
• тип лицензии — пожизненная;
• дата последней проверки.

Кнопка Проверить лицензию сейчас запускает внеплановую проверку. Временная недоступность сервера лицензий не должна останавливать уже настроенное подключение MAX и очередь: статус временной недоступности сохраняется отдельно. Если сервер сообщил об отзыве, проверьте сведения и обратитесь к владельцу лицензии.

Запросить лицензионный ключ

Если ключа ещё нет, заполните:

В интерфейсе указаны цены и условия лицензии: бессрочное использование для одного домена и включённые обновления. Сведения о стоимости и скидках уточняйте по текущим условиям поставщика лицензии.

15. WordPress Multisite и поддомены

В сетевой установке WordPress появляется раздел Сеть → Ru-max (Сеть). Он предназначен для управления лицензией и статусами подсайтов на уровне сети.

• При включённой сетевой поддержке лицензия корневого домена может распространяться на поддомены, субдомены и подсайты сети.
• При выключенной поддержке каждый сайт проверяет собственную лицензию независимо.
• Сетевая лицензия и лицензии отдельных подсайтов отображаются раздельно.
• Настройки токенов, каналов и публикаций подсайтов могут оставаться независимыми: распространение лицензии не означает копирование контента и каналов.
• В таблице статусов проверяйте, какой подсайт активен, какой домен используется и нет ли ошибки проверки.

Если сеть построена на поддоменах, включите параметр «Включить поддержку сети и поддоменов» в разделе «Дополнительные» и после этого проверьте статус лицензии из сетевой админки.

16. Диагностика ошибок

Не подключается MAX

1. Перейдите на «Главная» и заново проверьте токен без лишних пробелов.
2. Убедитесь, что бот создан в MAX Partner Platform и допущен к работе.
3. Проверьте исходящие HTTPS-запросы, DNS и наличие cURL на сервере.
4. Включите журнал API, повторите проверку и изучите код ответа.

Сообщение не пришло в канал

• Проверьте Chat ID: публичный канал может использовать username, приватная группа — числовой ID.
• Убедитесь, что бот добавлен в канал и имеет право отправлять сообщения.
• Проверьте, что канал указан в том разделе, который запускает отправку: MAX-публикации используют «Отправку публикаций», другие сети — свои настройки.
• Для теста используйте «Тестовое сообщение» или «Прямой доступ», чтобы отделить проблему API от фильтра записи.

Запись не отправилась автоматически

• Проверьте, включена ли «Отправка публикаций» и отмечено ли событие «новая» или «обновлённая запись».
• Проверьте post type, категорию, тег и наличие фильтра, который мог исключить запись.
• Проверьте задержку и очередь. В «Дополнительные» нажмите «Обработать очередь сейчас».
• Проверьте WP-Cron. При DISABLE_WP_CRON настройте внешний cron.
• Если ошибка временная, проверьте число повторов и интервал.

Не приходит личное уведомление

• Убедитесь, что модуль включён и указан хотя бы один Chat ID.
• Для всех отправителей поставьте any; иначе проверьте точное совпадение email.
• Для WooCommerce включите нужные статусы и проверьте, не оставлен ли фильтр без выбранных статусов.
• Проверьте дедупликацию: одинаковый #ID в теме второго письма может быть пропущен намеренно.
• Отправьте тест на ID из поля «ID чата для теста».

Не работает VK OAuth или фото

• Убедитесь, что ID приложения сообщества взят из dev.vk.ru, а ID для фото — из Web-приложения id.vk.ru.
• Сверьте Redirect URL посимвольно, включая HTTPS, путь, завершающий слеш и отсутствие параметров.
• Проверьте права photos, wall и groups.
• У записи должна быть доступная серверу миниатюра или картинка в содержимом.
• Читайте точное сообщение в «Истории»: оно указывает, сломался ли поиск изображения, скачивание, получение upload URL или сохранение на стене.

Виджет не показывается

• Проверьте главный переключатель и обязательную ссылку на чат.
• Проверьте задержку появления, скрытие и ограничения темы/кэша.
• Очистите кэш страницы и CDN, проверьте консоль браузера.
• Если включён звук, помните об ограничениях автоплея браузера.
• Для PRO проверьте, что хотя бы один канал включён и заполнен; размер и положение берутся из основного MAX-виджета.

Как подготовить обращение в поддержку

Приложите версию WP Ru-max, WordPress и PHP, наличие cURL, название сети, тип операции, время ошибки и фрагмент журнала с кодом ответа. Не отправляйте Bot Token, Access Token, Secret Key, пароль или полный URL с секретными параметрами.