What you need before you start
Bots in MAX are created on the MAX platform for partners. Legal entities, individual entrepreneurs and self-employed people who are residents of Russia can join it. A private person or a non-resident cannot yet pass the profile check.
The profile is checked through Gosuslugi, the Russian state services portal. You must log in with the role “Head” or “Administrator”: with the role of an employee the check fails. If the company data in the state registers (EGRUL or EGRIP) is out of date, update it in the organization profile; this usually takes from a few minutes to 1 hour.
An organization or an entrepreneur can create up to 5 bots, a self-employed person up to 2. You need several bots if you have several branches or different dialog scenarios.
For an AI agent you need two more things. The first is a server with a domain and an HTTPS certificate where n8n runs; n8n is a tool for building automation scenarios. The second is a model. Ollama runs open models on your computer or server and is distributed under the MIT license.
Step 1: profile and bot on the MAX platform
1. Open the web version of the MAX platform for partners and log in with your phone number and the code from a text message. The documentation advises a company number you always have access to.
2. On the “Choose profile type” screen, choose organization, entrepreneur or self-employed, and pass the check through Gosuslugi. The “MAX for business” bot will tell you when the check succeeds.
3. In the “Chatbots” section, click “Create” and fill in the card: a 500x500 pixel logo, a name of up to 59 characters and a description of up to 200 characters. The platform creates the nickname by itself from id, your tax number and _bot, and you cannot change it for now.
4. Click “Create” again. The bot gets the status “In moderation”; the check takes up to 48 hours on working days, and you cannot change the settings during this time.
5. After the check the status changes to “Published”, and the bot appears in MAX search. If the status is “Needs fixes”, look for the reason in the bot card.
Step 2: token and webhook
A token is a key that lets a program control the bot on your behalf. A webhook is an address on your server where MAX itself sends every new message. The second method, Long Polling, where the program asks MAX for updates, is allowed by the documentation only for development and testing.
1. On the platform, in the “Chatbots” section, choose the bot, click “⋮” and “Settings”. To the right of the “Access token” field, click the copy icon. Never share the token: with it, a stranger controls your bot. If it leaks, renew the token in the same place.
2. In n8n, create a scenario with a “Webhook” node and choose POST in the “HTTP Method” field. In the “Respond” field choose “Immediately”: MAX waits for an HTTP 200 reply for no longer than 30 seconds, and the model may think longer.
3. Make up a secret, a long random string. In the “Webhook” node, choose “Header auth” in the “Authentication” field, and in the credentials enter the header name X-Max-Bot-Api-Secret and this secret. This way n8n accepts only requests from MAX.
4. Publish the scenario and copy the node’s “Production URL”. Send a POST request to https://platform-api2.max.ru/subscriptions with an Authorization header that holds the token, and a body with three fields: “url” with the webhook address, “update_types” with the value message_created, and “secret” with your secret.
The webhook address must work over HTTPS on port 443 with a certificate from a trusted authority or from Russia’s Ministry of Digital Development; a self-signed one will not work. If the server does not respond for 8 hours, MAX unsubscribes the bot from the webhook.
Step 3: the model and the reply to the client
1. After the “Webhook” node, add an “AI Agent” node. In the “Prompt” parameter choose “Define below”, and in the “Prompt (User Message)” field insert the client’s message text from the message_created event.
2. In the node options, add “System Message” and write the rules: on whose behalf the agent answers, what it may talk about and what it passes to a manager. This is the system prompt, the instruction to the agent for every conversation.
3. Connect a model to the node. For an open model this is the “Ollama Chat Model” node. If n8n and Ollama run in different containers, enter an address the n8n container can reach. By default, the “Base URL” field in its credentials is http://localhost:11434.
4. The n8n documentation requires you to connect at least one tool to the agent, for example a search in the price list or in a base of answers. A tool gives the agent an action, not only text.
5. Add an “HTTP Request” node last: method POST, address https://platform-api2.max.ru/messages with the sender’s user_id parameter, and an Authorization header with the token. Turn on “Send Body”, choose JSON in “Body Content Type” and pass the “text” field with the model’s answer.
MAX sets two limits on a reply: text of up to 4,000 characters and no more than two messages a second in one chat. Cut a long model answer into parts or ask the model to answer shorter.
Step 4: testing and client data
1. Send the bot in MAX ten typical client questions. Check the answers on the “Executions” tab of the scenario in n8n: it shows what came from MAX and what the model answered.
2. Fix the instruction where the agent promises too much or invents prices, and ask the same questions again. We explain how to build a question set and which metrics to use to accept the agent in our article on agent testing.
Clients write names, phone numbers and addresses in MAX, and this is personal data. Under 152-FZ, Russia’s personal data law, data of Russian citizens is collected and stored in databases in Russia, and since 1 March 2023 an operator must notify Roskomnadzor, the Russian data protection regulator, before transferring data abroad.
So keep n8n and the model on a server in Russia, and do not connect a foreign cloud model to such conversations. How we store client data is described on our page on data security.
When you need a developer
The build above answers questions, but it does not remember the client between messages and does not write to the CRM. Conversation memory, deal records, handover to a person in the same chat and one agent for MAX, Telegram and the website need programming and testing on real conversations.
We connect such an agent turnkey: a pilot in 14 days from $1,499 with the metric in the contract. What the agent does in MAX is described on the page about our AI agent for MAX, and we cover a do-it-yourself build for Telegram separately.
n8n is distributed under the Sustainable Use License (fair-code): you may install it on your own server and change it, but you may not resell it as a cloud service. For your own company’s agent, that is enough.