Bots
MAX messenger bot hosting: how to keep a MAX bot running 24/7
In short
A bot for the MAX messenger has to run continuously on a server or hosting platform, and for production MAX recommends receiving updates through a webhook on an HTTPS address. The bot and its token are created on the MAX partner platform, which is open to companies, sole proprietors and self-employed residents of Russia with a verified profile. The bot code, with the token in environment variables, is then published to a host: on Netrun there is no server to configure, and the HTTPS link for the webhook is issued right away. Running the bot around the clock requires the Pro plan.
- MAX bots are created on the MAX partner platform, which is available to companies, sole proprietors and self-employed residents of Russia.
- A MAX bot token is sent in the Authorization header, and passing the token as a URL query parameter is no longer supported.
- The MAX documentation describes Long Polling as unsuitable for production and recommends webhooks instead.
- A MAX webhook only accepts an HTTPS address on port 443 and does not work with self-signed certificates.
- Official MAX bot libraries exist for JavaScript/TypeScript and Go, while maxapi is a popular library for Python.
MAX is a Russian messenger with its own bot platform, and the question of where to run a bot is the same as for Telegram or VK: a bot is a program that has to run all the time. While it runs on your laptop the bot replies, and once you close the lid it goes silent. That is why bot code is moved to a server or hosting platform where it runs without you.
MAX has two quirks worth knowing in advance. First, not everyone can create a bot, only a verified company, sole proprietor or self-employed person. Second, the docs explicitly recommend a webhook for production, and a webhook needs an HTTPS address on the standard port. Below is the path from registration to a working bot. If you have built a bot for another platform before, much of it will feel familiar: compare it with the guide on a VK bot.
| Criterion | Long Polling | Webhook |
|---|---|---|
| How the bot learns about messages | The bot keeps asking MAX for new events | MAX pushes every event to your address |
| What hosting has to provide | Just an always-running program | A running server with an HTTPS address on port 443 |
| What the MAX docs say | For development and testing, not production | The recommended way for production |
| What happens on failure | Speed and event retention are limited | MAX retries delivery up to 10 times with growing intervals |
| When to choose it | While you write and test the bot locally | Once the bot serves real users |
Verify your profile on the MAX partner platform#
Bots, channels and mini apps in MAX are connected through the partner platform at dev.max.ru. Under the MAX rules it is open to companies, sole proprietors and self-employed people who are residents of Russia, and the organization profile has to be verified. If you are building a bot for a client, it is easier for the client to create the bot in their own profile and give you the token.
Create the bot and save the token#
Once the bot is created on the partner platform you get a token, a long string MAX uses to identify your bot in every request. The token goes into the Authorization header, and the old way of putting it into the request URL no longer works. Treat the token like a password, because whoever has it can post as your bot. Users get access to the bot after moderation, and its status is shown next to the bot name.
Pick a library#
MAX publishes official libraries for JavaScript/TypeScript (the @maxhub/max-bot-api package) and for Go. There is no official Python library, but there is the popular maxapi, designed in the spirit of aiogram, and its fork has been reviewed by the MAX team. You can also write a bot with plain API requests, but a library saves you the routine of parsing events.
Develop with Long Polling, run in production on a webhook#
While you write the bot locally, Long Polling is convenient: the bot asks MAX for new events itself and needs no public address. For production the MAX docs recommend a webhook, where MAX pushes events to your address. The address must open over HTTPS on port 443 with a real certificate, and your server must answer each event with status 200 within 30 seconds, otherwise MAX retries the delivery.
Move the token to secrets and publish the bot#
Read the token from an environment variable instead of keeping it in code, so it never ends up in an archive or a repository. A webhook bot is effectively a web app, so it must listen on 0.0.0.0 and on the port from the PORT variable. On Netrun you upload the code as an archive, a folder or from GitHub, put the token into the Secrets tab and get an HTTPS link you can give to MAX as the webhook address.
Subscribe the webhook and check the logs#
The webhook address is registered with a POST /subscriptions request to the MAX API, and you can set a secret at the same time: MAX then sends it in the X-Max-Bot-Api-Secret header, and your server can reject requests without it. After subscribing, message the bot and watch the live project logs: if the event arrived, you will see it there. If the bot stays silent, first check that the address opens over HTTPS and that the token was picked up from secrets.
A MAX bot runs into the same questions as any other bot: where it runs continuously, where the token is stored and how you notice that it crashed. The difference is that MAX strongly recommends a webhook, which means an HTTPS address on the standard port. On Netrun that address is issued automatically, the token sits in encrypted secrets, logs are visible in the dashboard and a crashed project restarts on its own. The free plan lets you check that the bot builds and replies, but it only runs there for a limited time, and around-the-clock operation needs Pro. Try Netrun.
Common questions
Can a private person create a bot in MAX?
Under the rules of the MAX partner platform, no: it is open to companies, sole proprietors and self-employed people who are residents of Russia, and the profile has to be verified. An independent developer can register as self-employed or build the bot inside a client profile. The platform may change its rules, so check the documentation at dev.max.ru before you start.
Where do I get a MAX bot token?
The token is issued on the MAX partner platform after you create the bot. It is required in every API request and is sent in the Authorization header. If the token leaks, replace it and update the value in your hosting settings.
Can I port my Telegram bot to MAX?
The logic, yes: scenarios, texts and database code can stay. But MAX has its own API, so the code that receives and sends messages has to be rewritten for a MAX library. The maxapi library for Python is designed similarly to aiogram, which makes the move easier.
Why does MAX reject my webhook address?
Most often the address opens over http instead of https, uses a non-standard port, or has a self-signed certificate. MAX accepts only HTTPS on port 443 with a certificate from a trusted authority. Make sure the link opens in a browser without warnings and give it without a port number.
Can I keep my MAX bot on Long Polling?
Technically a Long Polling bot works, but the MAX documentation explicitly calls this method unsuitable for production because speed and event retention are limited. It is handy for development and testing, while real users are better served by a webhook.
Where do I set tokens and other secret values?
Every project has a Secrets tab where you set the values from your code — for example the token from BotFather. We store them encrypted: you can see the variable names, but the values are shown to no one, including you.
What happens to my bot after 3 hours on the free plan?
The bot switches off, but your code, settings and secrets stay where they are — we delete nothing. Shortly before it switches off we send you a warning. The three hours only count while the bot is actually running: while it is stopped, still building or crashed with an error, the clock stands still — you can fix the code and start it again without losing time. Switch to the Pro plan, and the bot starts again from the same place and runs around the clock. A new bot uploaded after that is built too, but it will not start: free time is counted per account, not per project.
What happens if my app crashes?
We watch over projects and restart them if they fail. The status and the logs appear in your account straight away, and we send a notification only if the app has not come back within an hour: short interruptions are not worth disturbing you over.