Max integration with Contact form 7

Max integration with Contact form 7

Short description

The plugin sends successful requests from Contact Form 7 forms to the MAX messenger via the chatbot API (platform-api.max.ru ). It is suitable for notifying managers in a group chat or for private messages to the user.

The plugin only works one way: outgoing notifications about new applications. Incoming messages and bot events require separate Webhook settings on the MAX side and are not processed in this version.

Requirements

— WordPress 5.8 and above
— PHP 7.4 and higher
— The Contact Form 7 plugin is installed and active
— MAX chatbot on the partner platform and access_token token
— Active PluginHub license for the "MAX for Contact Form 7" product

API MAX documentation: https://dev.max.ru/docs-api
The reference of methods: https://dev.max.ru/docs

Installation

1. Copy the max-cf7-integration folder to the wp-content/plugins/ directory on the server.
2. In the WordPress admin panel, open the "Plugins" section and activate "MAX for Contact Form 7".
3. Make sure that Contact Form 7 is active. If it is not, install the plugin from the WordPress directory.
4. Go to Contacts → MAX and follow the instructions below.

Where are the settings located

Plugin page: Contacts → MAX (Contact Form 7 submenu).

There are two tabs on the page:
— "Settings" — license, bot token, chat_id, general message parameters;
— "Instructions" — a brief reference inside the admin panel.

Setting up individual forms: Contacts → Contact forms → open the required form → the "Notification in MAX" block.

The "Settings" link is also available in the list of plugins on the "Plugins" screen.

Part 1. PluginHub License

1. Open Contacts → MAX → Settings tab.
2. In the "PluginHub License" block, enter the license key you received on the website pluginhub.pro after purchasing the product.
3. Click "Save" at the bottom of the form.

The license key is entered only on this plugin page, not in the general WordPress settings.

After saving, the status is displayed under the block header:
— "License is active" — you can use sending to MAX;
— error message — the key is incorrect, expired, revoked, the site domain does not match or there is no connection to the license server.

While the license is not active, the plugin does not send messages to MAX. Verification of the bot's token is also unavailable.

A single PluginHub key can be used for multiple PluginHub plug-ins on the same site, if provided by the terms of purchase.

Part 2. Preparing a chatbot in MAX

1. Connect the organization on the MAX platform for partners (for legal entities and sole proprietors — residents of the Russian Federation).
2. Create a chatbot and wait for moderation.
3. Get an access token: section "Chatbots" → "Integration" → "Get a token". This is the access_token value.
4. Add the bot to the group chat where applications should be sent, or prepare a user_id for private messages.
5. Find out the chat ID (chat_id) or the user (user_id). The method of getting it depends on the MAX platform tools and API documentation.

Important for security:
— pass the token only in the Authorization header when making API requests, not in the URL or on the public pages of the site;
— do not publish the token in open repositories, screenshots, or logs with the full text of requests.

Part 3. Global Plugin Settings

Open Contacts → MAX → "Settings".

The "Bot token (access_token)" field
Insert the token from the MAX platform. After the first save, the field shows a mask: leave it empty if you do not need to change the token. To replace it, enter a new token and save the settings.

The "Chat ID"
field is the numeric identifier of the group chat where the bot has been added. It is recommended for team notifications about applications.

The "User ID (optional)"
field is the MAX user ID. Used if the chat_id is not specified: the message will be sent to this user.

Addressing priority: if chat_id is specified, sending goes to the chat; otherwise, user_id is used. At least one of them must be filled in.

The "Text format"
field — Markdown — formatting with asterisks and underscores (by default);
— HTML markup tags;
— Without formatting — plain text.

The "Default prefix" field
The text at the beginning of each message, if no prefix is specified for the specific form. Example: "New application from the website."

The "Notify chat participants" checkbox
is enabled, and chat participants receive notification of a new message according to the MAX rules.

The "Disable link previews" checkbox
is enabled, but the links in the message do not show previews.

After filling in the fields, click "Save".

The "Verify token" button
Sends a GET/me request to the MAX API and shows the result next to the button. An active license is required for verification. If the token has already been saved, the verification is performed on the saved value even if the input field is empty.

Part 4. Setting up each Contact Form 7 form

1. Open Contacts → Contact forms.
2. Select the form and open it for editing.
3. Find the "Notification in MAX" block under the form editor.

Block Parameters:

"Send applications of this form to MAX"
Enable it so that when the form is successfully submitted on the website, the data goes to MAX.

"Text of the message"
The name of one CF7 form field — only its value will be included in the message.
Alternatively, specify a special value __all__ (two underscores on both sides), in which case all fields of the form with signatures will be included in the message.

"Message prefix"
The text before the main body of the message. If left blank, the global prefix from the plugin settings is used.

Substitutions in the prefix (in curly brackets):
— {form_title} — name of the form;
— {form_id} — numeric ID of the WordPress form;
— {site} - the address of the main page of the site;
— {field name} is the value of the CF7 field, for example {your-name}, {your-email}, {tel}.

"Add the URL of the sending page"
The address of the page from which the form was submitted is added to the end of the message.

"Add website address"
The URL of the main page of the website is added to the end of the message.

4. Click "Save" on the CF7 form.

Part 5. How a message is generated in MAX

The order of the message parts:
1. Prefix (from form settings or global).
2. An empty line.
3. Main text: one field or all fields (__all__).
4. With the options enabled, the website address and the URL of the sending page.

In the __all__ format, the message header contains the name of the form in square brackets, followed by each field with a name and value. The service fields (starting with an underscore), reCAPTCHA and hCaptcha are not included in the list.

The maximum text length according to the MAX API is 4000 characters. The plugin truncates text that is too long to the acceptable size.

Part 6. Job verification

1. Make sure that the license is active (the "PluginHub License" block).
2. Save the token, chat_id, or user_id and click "Verify token".
3. Enable sending to MAX for the test form in the metabox.
4. Open the website page with this form and submit the test application the way a visitor would do.
5. Check the MAX chat: a new message should appear.

The successful submission of the form on the site is not interrupted, even if MAX is temporarily unavailable: the visitor still sees the standard CF7 success message. Sending error in MAX does not block emails and other CF7 actions if they are configured separately.

API MAX Limits

— the length of the message text is up to 4000 characters;
— approximately up to 30 requests per second for platform-api.max.ru (API restrictions are possible under heavy load);
— you need a valid token and bot rights in the target chat to work.;
— the plugin uses the method of sending messages POST / messages, without processing incoming events.

Troubleshooting issues

Applications are not received at MAX

— check the license status on the Settings tab;
— click "Verify Token" and fix the error if there is one.;
— make sure that the chat_id or user_id is specified;
— the bot must be added to the group chat (for chat_id);
— sending to MAX is enabled in the form's metabox.;
— the form on the website is sent without CF7 errors (red validation error messages);
— the hosting allows outgoing HTTPS requests to platform-api.max.ru and pluginhub.pro .

The license is not activated

— check the correctness of the key without unnecessary spaces;
— the site's domain in the address bar must match the domain linked to the pluginhub license.pro;
— if the connection fails, check the server's access to the Internet and SSL.

"Verify token" returns an error

— the token is copied in full, without spaces at the beginning and end;
— the bot has not been deleted or blocked on the MAX platform;
— the token has not expired (if necessary, issue a new one on the platform).

The message arrives, but without the required fields

— the "Message text" field contains __all__ or the exact name of the field as in the CF7 markup (your-email, tel, etc.);
— the names of the fields in the prefix substitutions match the names in the form.

Contact Form 7 is not installed

A notification will appear on the Plugins screen and in the admin panel with a suggestion to install Contact Form 7. Integration does not work without it.

Additionally for developers

The PluginHub product ID is set in the plugin code by default. It can be redefined in wp-config.php:

define( 'MAX_CF7_PLUGINHUB_PLUGIN_ID', 'your-product-uuid' );

The filter for access rights to settings is max_cf7_capability (by default, it matches the right to edit CF7 or manage_options forms).

Product ID filter: max_cf7_pluginhub_plugin_id.

Removing the plugin

When deleting a plugin through the WordPress admin panel (not just deactivation), the file uninstall.php deletes the plugin settings and the license status cache for this product. The shared pluginhub_license_key on the site is not deleted if it is used by other PluginHub plugins.

Support and links

PluginHub: https://pluginhub.pro
MAX documentation: https://dev.max.ru/docs
The MAX API Reference: https://dev.max.ru/docs-api