MAX Bot API changes on July 19, 2026: how to transfer a bot to platform-api2.max.ru

If you already have a MAX bot running for tickets, support, recording or notifications, you need to check it before July 19, 2026. A critical change has appeared in the MAX documentation: requests to the old domain platform-api.max.ru needs to be translated to platform-api2.max.ru, and the token can no longer be passed in query parameters.

Briefly: a working MAX bot after July 19 may begin to crash not because of business logic, but because of transport. The most common reasons are an old API domain, a token in the URL, an unsupported Webhook-endpoint certificate, a dependency on GET /chats and Long Polling in production.

If the bot is associated with leads, CRM or customer support, postponing the check is dangerous: the failure will look like “the bot is silent”, “messages do not go through”, “webhook does not arrive” or “chat chats are missing”.

What exactly is changing in the MAX Bot API

As of July 16, 2026, the official MAX documentation lists four changes that directly impact combat integrations:

• HTTP requests must be directed to https://platform-api2.max.ru.
• The token must be passed through the header Authorization: <token>.
• Webhook can no longer rely on HTTP and self-signed certificates.
• Method GET /chats as of June 2026 no longer supported.

Separately, MAX recommends using Webhook for a production environment. Long Polling remains convenient for development and testing, but for a combat bot it is a weak point: there are limitations on speed and event storage.

Quick migration checklist

Check out the bot using this list. If at least one point is not met, there is a risk that the integration will fall off or begin to lose events.

1. There are no calls to platform-api.max.ru.
2. All API requests go to https://platform-api2.max.ru.
3. The token is not transferred as ?access_token=..., ?token=... or similar query parameter.
4. All requests have a header Authorization: {access_token}.
5. Webhook is available over HTTPS on port 443.
6. The endpoint certificate was issued by a trusted center or a Ministry of Digital Development certificate.
7. The server issues the complete chain of certificates.
8. Webhook responds 200 OK faster than 30 seconds.
9. Subscription uses secret, and the server checks X-Max-Bot-Api-Secret.
10. Receiving logic chat_id does not depend on GET /chats.
11. For chats and channels chat_id saved from events bot_added, bot_started and other webhook events.
12. There is a queue or reprocessing log if the CRM, ERP or database is temporarily unavailable.

For businesses, the main question is simple: if the bot accepts applications, can it be proven that after a failure, not a single lead will be lost? If not, the migration should include not only URL replacement, but also an architectural audit.

How it was before and how it should be now

A bad option is the token in the URL:

curl -X POST "https://platform-api.max.ru/messages?user_id=123&access_token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Проверка связи"}'

Working option after migration - new domain and Authorization header:

curl -X POST "https://platform-api2.max.ru/messages?user_id=123" \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Проверка связи"}'

If your project has an SDK, wrapper class, or general API client, start there. In a good architecture, the domain and authorization method change in one place. If the URL is spread across controllers, workers and cron tasks, you should first build a single client for the MAX API.

What to check in Webhook

Webhook is not just a URL in the settings. MAX validates TLS and expects a quick successful response from your endpoint. Therefore, verification should be carried out not only on the code, but also on the infrastructure.

Minimum production endpoint:

https://your-domain.ru/webhook

What's important:

• HTTPS only;
• port 443;
• the domain in the URL matches the CN or SAN of the certificate;
• the server issues the complete chain of certificates;
• endpoint responds 200 OK within 30 seconds;
• heavy business logic is not executed inside the webhook controller.

The correct pattern for production is:

1. Webhook receives the event.
2. Checks X-Max-Bot-Api-Secret.
3. Places an event in a queue or log.
4. Returns quickly 200 OK.
5. A separate worker processes an event, goes to CRM, ERP, LLM or database.

This approach protects the bot from cascading failures. If CRM temporarily responds 502, the webhook still receives the event, and the worker will repeat the processing later.

How to update a subscription via POST /subscriptions

For production, MAX recommends Webhook. A subscription is created via POST /subscriptions.

Example:

curl -X POST "https://platform-api2.max.ru/subscriptions" \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.ru/webhook",
    "update_types": ["message_created", "message_callback", "bot_started"],
    "secret": "your_secret"
  }'

secret It's always better to ask. Then each webhook request can be checked by header X-Max-Bot-Api-Secretrather than accepting any POST requests from the Internet.

If the bot processes personal data, applications, phone numbers or order statuses, lack of verification secret - this is no longer a technical detail, but a security risk.

What to do with GET /chats

From June 2026 GET /chats no longer supported. If the bot previously periodically received a list of chats through this method, this logic needs to be replaced.

New scheme:

1. Subscribe to events via POST /subscriptions.
2. Receive chat_id from events, for example bot_added or bot_started.
3. Save chat_id in your database.
4. Update the storage when a bot is added, repeated, or removed from the chat.
5. Use saved chat_id for sending messages and other API calls.

Important: Maintaining the chat list now becomes the responsibility of your system. It is necessary to provide for deduplication, processing of repeated webhook events and removal of irrelevant ones chat_id.

Why is it better to remove Long Polling from production?

Long Polling looks simpler: the server itself goes for events, there is no need to open the endpoint to the outside. But for production this is a bad compromise.

Risks of Long Polling:

• restrictions on the speed of receiving events;
• risk of losing context if handled incorrectly marker;
• complex horizontal scaling;
• conflict with active webhook subscription;
• poor visibility during failures.

For a test bot, Long Polling is normal. For a bot that accepts leads, reservations, support requests or order statuses, it is better to switch to Webhook with a queue, logs and retrays.

We discussed the architectural difference in more detail in the article Webhook vs Long Polling in Production.

Typical symptoms after unsuccessful migration

If your bot starts to behave unstable after July 19th, check these signs:

Symptom	Probable Cause
401 Unauthorized	The token is still being passed to the URL or is not going to Authorization
404 or network errors	The old domain remains in the code platform-api.max.ru
Webhook not receiving events	TLS, port 443, certificate chain, or invalid subscription URL
Events come again	No idempotency update_id or message_id
Chats "disappeared"	The code depended on GET /chats
Bot responds with delay	Heavy CRM/LLM logic is executed in the webhook controller
Leads are not included in CRM	There is no queue or retry mechanism if the external API fails

The most annoying error is when the webhook responds 200 OK, but the business process inside is already broken. Therefore, in addition to the server uptime, you need to look at the event queue, CRM errors, DLQ, processing time and the number of unsent messages.

Mini migration plan in one day

If time is short, follow this scenario:

1. Find your old domain

According to the project, you need to find all occurrences of:

platform-api.max.ru
access_token=
token=
/chats
/updates

You need to check not only the application, but also cron scripts, worker processes, environment variables, CI/CD, support documentation and old SDK configs.

2. Update the shared API client

Place the base URL and authorization in one module:

const MAX_API_BASE_URL = "https://platform-api2.max.ru";

async function maxApi(path, options = {}) {
  return fetch(`${MAX_API_BASE_URL}${path}`, {
    ...options,
    headers: {
      Authorization: process.env.MAX_BOT_TOKEN,
      "Content-Type": "application/json",
      ...(options.headers || {}),
    },
  });
}

This is a simplified example. In the combat code, add timeouts, logging, processing 429, retrays and masking of tokens in logs.

3. Recreate or update the Webhook subscription

Create a subscription to the new endpoint via POST /subscriptions, specify the required events and secret. After this, check that the webhook actually receives the test event and that the header X-Max-Bot-Api-Secret is checked on your side.

4. Remove dependency on GET /chats

If the bot needs to work with group chats or channels, start storing chat_id on your own. It is better to migrate old data to a table with fields:

• chat_id;
• the type of event from which it is derived;
• date of first receipt;
• date of last confirmation;
• activity status;
• service metadata.

5. Do a smoke test

Minimum set of checks:

1. The user writes to the bot.
2. Webhook receives the event.
3. The server validates secret.
4. The event is saved to a queue or log.
5. Worker handles the event.
6. The bot sends a response via platform-api2.max.ru.
7. If there is a CRM, a test lead is created.
8. There is no clear token in the logs.

What does this mean for business?

For businesses, migrating the MAX Bot API is not just a “change domain” task. If the bot is built into sales or support, you need to check the entire event path:

Пользователь -> MAX -> Webhook -> очередь -> обработчик -> CRM/ERP -> ответ пользователю

A weak point in any area can result in lost applications. Especially if the bot:

• accepts requests from advertising;
• registers clients for services;
• creates transactions in Bitrix24 or amoCRM;
• gives order statuses;
• acts as the first line of support;
• uses AI/RAG for knowledge base answers.

If you already have such a bot, a reasonable minimum is a technical audit before July 19 and monitoring in the first days after the migration.

When is it worth redesigning a bot, not just migrating the API?

A simple search-and-replace domain is only suitable for small bots without integrations. If the bot is related to CRM, payments, orders or personal data, it is better to immediately check the architecture.

Red flags:

• there is no single MAX API client;
• the token is stored in the code;
• webhook writes directly to CRM without queuing;
• no idempotency;
• no retry/backoff;
• no DLQ;
• errors are visible only in the console;
• it is impossible to quickly understand how many events are lost;
• no test circuit.

In such cases, migration to platform-api2.max.ru - a good reason to bring the bot to the production level. This usually requires an API client, a queue, monitoring, logging, an event table, duplicate control, and a clear runbook for support.

Internal linking on the topic

If you are just planning a launch, start with the guide how to create a bot in MAX: business requirements, security and architecture.

If the bot must withstand the load, analysis is useful API MAX limits and highload bot architecture.

If you need to choose a business scenario, take a look typical MAX bot scenarios: lead generation, support and recording.

If you need an audit or development of a production bot for sales, support and CRM, the specialized service is here: development of MAX bots.

FAQ

What needs to be done before July 19, 2026? Translate MAX API requests to platform-api2.max.ru, transfer the token via Authorization, check TLS/Webhook-endpoint certificates and remove dependency on GET /chats.

Is it possible to leave Long Polling? For development and testing - yes. For production, MAX recommends Webhook, because Long Polling is limited in speed and event storage period.

Why might MAX bot stop responding? Most often due to an old API domain, incorrect authorization, problems with TLS in the webhook, unsupported GET /chats or lack of handling of repeated events.

Do I need to change the bot's business logic? Not always. But if the bot writes to CRM, accepts requests or works with orders, it is better to combine migration with checking queues, retrays, idempotency and monitoring.

How do you know if the migration was successful? Run a test: the user writes to the bot, the webhook receives the event, the server checks the secret, the worker processes the task, the bot responds via platform-api2.max.ru, and CRM receives a test record without errors.

Sources

• MAX API: general description
• MAX API: history of changes
• MAX API: POST /subscriptions
• MAX API: POST /messages
• MAX API: GET /updates
• MAX API: GET /chats