Интеграция Max с Contact form 7

Интеграция Max с Contact form 7

Краткое описание

Плагин отправляет успешные заявки с форм Contact Form 7 в мессенджер MAX через API чат-бота (platform-api.max.ru). Подходит для уведомлений менеджеров в групповом чате или для личных сообщений пользователю.

Плагин работает только в одну сторону: исходящие уведомления о новых заявках. Входящие сообщения и события бота требуют отдельной настройки Webhook на стороне MAX и в данной версии не обрабатываются.

Требования

— WordPress 5.8 и выше
— PHP 7.4 и выше
— Установленный и активный плагин Contact Form 7
— Чат-бот MAX на платформе для партнёров и токен access_token
— Активная лицензия PluginHub для продукта «MAX for Contact Form 7»

Документация API MAX: https://dev.max.ru/docs-api
Справочник методов: https://dev.max.ru/docs

Установка

1. Скопируйте папку max-cf7-integration в каталог wp-content/plugins/ на сервере.
2. В админке WordPress откройте раздел «Плагины» и активируйте «MAX for Contact Form 7».
3. Убедитесь, что активен Contact Form 7. Если его нет, установите плагин из каталога WordPress.
4. Перейдите в Контакты → MAX и выполните настройку по инструкции ниже.

Где находятся настройки

Страница плагина: Контакты → MAX (подменю Contact Form 7).

На странице две вкладки:
— «Настройки» — лицензия, токен бота, chat_id, общие параметры сообщений;
— «Инструкция» — краткая справка внутри админки.

Настройка отдельных форм: Контакты → Контактные формы → откройте нужную форму → блок «Уведомление в MAX».

Ссылка «Настройки» также доступна в списке плагинов на экране «Плагины».

Часть 1. Лицензия PluginHub

1. Откройте Контакты → MAX → вкладка «Настройки».
2. В блоке «Лицензия PluginHub» введите ключ лицензии, полученный на сайте pluginhub.pro после покупки продукта.
3. Нажмите «Сохранить» внизу формы.

Ключ лицензии вводится только на этой странице плагина, не в общих настройках WordPress.

После сохранения под заголовком блока отображается статус:
— «Лицензия активна» — можно пользоваться отправкой в MAX;
— сообщение об ошибке — ключ неверный, истёк, отозван, не совпадает домен сайта или нет связи с сервером лицензий.

Пока лицензия не активна, плагин не отправляет сообщения в MAX. Проверка токена бота также недоступна.

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

Часть 2. Подготовка чат-бота в MAX

1. Подключите организацию на платформе MAX для партнёров (для юрлиц и ИП — резидентов РФ).
2. Создайте чат-бота и дождитесь прохождения модерации.
3. Получите токен доступа: раздел «Чат-боты» → «Интеграция» → «Получить токен». Это значение access_token.
4. Добавьте бота в групповой чат, куда должны приходить заявки, либо подготовьте user_id для личных сообщений.
5. Узнайте идентификатор чата (chat_id) или пользователя (user_id). Способ получения зависит от инструментов платформы MAX и документации API.

Важно по безопасности:
— передавайте токен только в заголовке Authorization при запросах к API, не в URL и не на публичных страницах сайта;
— не публикуйте токен в открытых репозиториях, скриншотах и логах с полным текстом запросов.

Часть 3. Глобальные настройки плагина

Откройте Контакты → MAX → «Настройки».

Поле «Токен бота (access_token)»
Вставьте токен из платформы MAX. После первого сохранения поле показывает маску: оставьте его пустым, если менять токен не нужно. Для замены введите новый токен и сохраните настройки.

Поле «Chat ID»
Числовой идентификатор группового чата, куда добавлен бот. Рекомендуется для командных уведомлений о заявках.

Поле «User ID (необязательно)»
Идентификатор пользователя MAX. Используется, если chat_id не указан: сообщение уйдёт этому пользователю.

Приоритет адресации: если указан chat_id, отправка идёт в чат; иначе используется user_id. Должен быть заполнен хотя бы один из них.

Поле «Формат текста»
— Markdown — форматирование звёздочками и подчёркиваниями (по умолчанию);
— HTML — теги разметки;
— Без форматирования — обычный текст.

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

Чекбокс «Уведомлять участников чата (notify)»
Если включён, участники чата получают уведомление о новом сообщении согласно правилам MAX.

Чекбокс «Отключить превью ссылок»
Если включён, ссылки в сообщении не показывают превью.

После заполнения полей нажмите «Сохранить».

Кнопка «Проверить токен»
Отправляет запрос GET /me к API MAX и показывает результат рядом с кнопкой. Для проверки нужна активная лицензия. Если токен уже сохранён, проверка выполняется по сохранённому значению даже при пустом поле ввода.

Часть 4. Настройка каждой формы Contact Form 7

1. Откройте Контакты → Контактные формы.
2. Выберите форму и откройте её на редактирование.
3. Найдите блок «Уведомление в MAX» под редактором формы.

Параметры блока:

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

«Текст сообщения»
Имя одного поля формы CF7 — в сообщение попадёт только его значение.
Либо укажите специальное значение __all__ (два подчёркивания с обеих сторон) — тогда в сообщение попадут все поля формы списком с подписями.

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

Подстановки в префиксе (в фигурных скобках):
— {form_title} — название формы;
— {form_id} — числовой ID формы в WordPress;
— {site} — адрес главной страницы сайта;
— {имя-поля} — значение поля CF7, например {your-name}, {your-email}, {tel}.

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

«Добавлять адрес сайта»
В конец сообщения добавляется URL главной страницы сайта.

4. Нажмите «Сохранить» у формы CF7.

Часть 5. Как формируется сообщение в MAX

Порядок частей сообщения:
1. Префикс (из настроек формы или глобальный).
2. Пустая строка.
3. Основной текст: одно поле или все поля (__all__).
4. При включённых опциях — адрес сайта и URL страницы отправки.

При формате __all__ заголовок сообщения содержит название формы в квадратных скобках, далее каждое поле с именем и значением. Служебные поля (начинающиеся с подчёркивания), reCAPTCHA и hCaptcha в список не попадают.

Максимальная длина текста по API MAX — 4000 символов. Плагин обрезает слишком длинный текст до допустимого размера.

Часть 6. Проверка работы

1. Убедитесь, что лицензия активна (блок «Лицензия PluginHub»).
2. Сохраните токен, chat_id или user_id и нажмите «Проверить токен».
3. Включите отправку в MAX для тестовой формы в метабоксе.
4. Откройте страницу сайта с этой формой и отправьте тестовую заявку так, как это сделал бы посетитель.
5. Проверьте чат MAX: должно появиться новое сообщение.

Успешная отправка формы на сайте не прерывается, даже если MAX временно недоступен: посетитель по-прежнему видит стандартное сообщение CF7 об успехе. Ошибка отправки в MAX не блокирует письма и другие действия CF7, если они настроены отдельно.

Ограничения API MAX

— длина текста сообщения до 4000 символов;
— ориентировочно до 30 запросов в секунду на platform-api.max.ru (при большой нагрузке возможны ограничения со стороны API);
— для работы нужен действующий токен и права бота в целевом чате;
— плагин использует метод отправки сообщений POST /messages, без обработки входящих событий.

Устранение неполадок

Заявки не приходят в MAX

— проверьте статус лицензии на вкладке «Настройки»;
— нажмите «Проверить токен» и устраните ошибку, если она есть;
— убедитесь, что указан chat_id или user_id;
— бот должен быть добавлен в групповой чат (для chat_id);
— в метабоксе формы включена отправка в MAX;
— форма на сайте отправляется без ошибок CF7 (красные сообщения об ошибке валидации);
— на хостинге разрешены исходящие HTTPS-запросы к platform-api.max.ru и pluginhub.pro.

Лицензия не активируется

— проверьте правильность ключа без лишних пробелов;
— домен сайта в адресной строке должен совпадать с доменом, привязанным к лицензии на pluginhub.pro;
— при ошибке связи проверьте доступ сервера к интернету и SSL.

«Проверить токен» выдаёт ошибку

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

Сообщение приходит, но без нужных полей

— в поле «Текст сообщения» указано __all__ или точное имя поля как в разметке CF7 (your-email, tel и т.д.);
— имена полей в подстановках префикса совпадают с именами в форме.

Contact Form 7 не установлен

На экране «Плагины» и в админке появится уведомление с предложением установить Contact Form 7. Без него интеграция не работает.

Дополнительно для разработчиков

Идентификатор продукта PluginHub по умолчанию задан в коде плагина. Его можно переопределить в wp-config.php:

define( 'MAX_CF7_PLUGINHUB_PLUGIN_ID', 'ваш-uuid-продукта' );

Фильтр прав доступа к настройкам: max_cf7_capability (по умолчанию совпадает с правом редактирования форм CF7 или manage_options).

Фильтр идентификатора продукта: max_cf7_pluginhub_plugin_id.

Удаление плагина

При удалении плагина через админку WordPress (не просто деактивация) файл uninstall.php удаляет настройки плагина и кэш статуса лицензии для этого продукта. Общий ключ pluginhub_license_key на сайте при этом не удаляется, если он используется другими плагинами PluginHub.

Поддержка и ссылки

PluginHub: https://pluginhub.pro
Документация MAX: https://dev.max.ru/docs
Справочник API MAX: https://dev.max.ru/docs-api