Как создать бота в MAX в 2026 году: пошаговая инструкция

Допустим, у вас мастерская по ремонту техники. Вечером, когда сотрудник уже ушёл, клиент пишет про кофемашину: вода течёт под корпус, модель такая-то, можно ли привезти завтра. В этот момент бот мог бы собрать сведения о поломке и передать их сотруднику, чтобы утром тот начал разговор уже с понятной заявки. Для этого боту не требуется ставить диагноз или обещать стоимость ремонта, которую мастер ещё не оценивал.

На таком примере и разберём весь путь. Клиент выбирает услугу, описывает проблему, проверяет сведения и подтверждает отправку. После этого сотрудник должен увидеть одну заявку, а клиент получить сообщение о том, когда ему ответят. Если сохранить обращение не получилось, бот должен объяснить, как повторить попытку или связаться с мастерской, иначе человек будет ждать ответа на заявку, которую никто не получил.

Чтобы это заработало, сначала нужно получить доступ к платформе MAX и зарегистрировать карточку бота, а затем подключить программу, которая будет обрабатывать сообщения. Карточка задаёт название и описание, токен позволяет программе обращаться к API, а сценарий определяет, что происходит в разговоре. Пройдём эти части последовательно: так будет проще понять, что уже готово и что ещё нужно настроить, если после регистрации бот пока молчит.

Прежде чем собирать диалог, проверьте, сможете ли вы зарегистрировать бота от своего имени. По официальным правилам, проверенным 7 октября 2026 года, такая возможность есть у юридических лиц, ИП и самозанятых — резидентов РФ. Самозанятому регистрировать ИП для этого не требуется. А вот личного аккаунта без подходящего бизнес-статуса пока недостаточно; нерезиденты РФ также не могут пройти верификацию на платформе для партнёров.

Это удобно выяснить до покупки конструктора, чтобы не обнаружить ограничение после того, как вы уже настроили половину диалога. Учтите также, что подтверждение владельца и проверка карточки проходят отдельно. Сначала MAX должен верифицировать бизнес-профиль, после чего вы сможете отправить конкретного бота на модерацию. Подтверждённый профиль сам по себе ещё не означает, что карточку одобрят без замечаний.

Регистрация начинается на платформе MAX для бизнеса. Подготовьте рабочий номер телефона и доступ к способу подтверждения своего статуса, затем пройдите шаги ниже. Если профиль уже верифицирован, заново подтверждать его ради каждой карточки не потребуется.

В описании мастерской можно написать: «Принимаем заявки на ремонт техники. Опишите поломку, сотрудник свяжется с вами в рабочее время». Клиенту будет понятно, зачем открывать бота и когда ждать человека. При заполнении карточки MAX допускает до 59 символов в названии и до 200 в описании; для аватара указаны 500 × 500 пикселей, JPG/JPEG/PNG и размер до 5 МБ. Требования стоит сверить прямо в форме, прежде чем готовить изображение.

Никнейм бот получит автоматически: для организации или ИП он имеет вид idИНН_bot, а для самозанятого — se(orgid)_bot. Выбрать или изменить его пока нельзя, хотя отображаемое название вы задаёте сами. После отправки карточки оставьте время на проверку: в документации указан срок до 48 часов по рабочим дням. Если вы отправили её в пятницу вечером, рассчитывать на запуск к воскресному утру поэтому не стоит.

Когда карточка пройдёт модерацию, откройте «Чат-боты», выберите своего бота и перейдите в ⋮ → «Настройки», где можно скопировать токен. Он понадобится серверному приложению или конструктору для запросов от имени бота. Если интеграцию помогает написать агент, в задаче достаточно указать имя секрета, например MAX_BOT_TOKEN, а само значение сохранить в серверном окружении или специальном поле конструктора.

Начнём проверку с небольшого запроса GET /me: он позволяет узнать, принимает ли API ваш токен и относится ли тот к нужному боту. На дату проверки адрес API — https://platform-api2.max.ru, а заголовок Authorization должен содержать сам токен, без слова Bearer. Передавать токен в query-параметре уже нельзя. Если ответ содержит данные вашего бота, можно переходить к получению сообщений и обработчику диалога.

curl --fail-with-body \
  --request GET 'https://platform-api2.max.ru/me' \
  --header "Authorization: $MAX_BOT_TOKEN"

Перед запуском этой команды сохраните токен в переменной MAX_BOT_TOKEN на сервере, откуда выполняется запрос. Если соединение завершится ошибкой TLS, сверьте настройку доверенных сертификатов с документацией MAX: она требует добавить сертификат Минцифры. Отключать проверку сертификата для обхода ошибки не стоит, поскольку тогда вы уберёте проверку соединения вместо её настройки. Если токен случайно стал доступен посторонним, обновите его в MAX, замените серверный секрет и повторите GET /me.

Теперь можно расписать сам разговор. Для начала бот спросит, какая техника сломалась, затем предложит описать проблему и выбрать способ связи. Перед отправкой он покажет собранные сведения, чтобы человек мог проверить их целиком. Телефон стоит запрашивать только тогда, когда сотрудник действительно собирается звонить: если ответ придёт в этот же диалог, лишнее поле лишь добавит клиенту работы.

Представьте, что на этапе проверки клиент заметил ошибку в модели кофемашины. Ему должно быть понятно, как вернуться к этому полю, не заполняя всё сначала. Он может также отвлечься и продолжить через час или дважды нажать подтверждение, потому что ответ не появился сразу. Поэтому ответы нужно связывать с текущим черновиком, завершённую заявку учитывать один раз, а состояние разговора хранить так, чтобы оно переживало перезапуск приложения.

Для такого разговора обычно достаточно заранее заданного сценария: бот знает, какое поле ждёт, и после ответа переходит к следующему. Языковая модель может пригодиться позже, например чтобы сократить длинное описание поломки для сотрудника, оставив рядом оригинал. Если решите её добавить, определите, какие сведения можно передавать модели и что бот сделает при её ошибке, чтобы сбор заявки от этого не останавливался.

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

Собственное приложение становится полезным, если мастерская уже принимает заявки с сайта или распределяет их между несколькими филиалами. Тогда бот можно подключить к общей очереди: сервер получит сообщение MAX, определит текущий шаг разговора, сохранит ответ и отправит следующее сообщение. Сотрудники будут работать с этими же заявками в кабинете, где сервер проверяет их права доступа.

Выбирать между этими вариантами проще по конкретному диалогу. Если конструктор умеет собирать нужные поля, сохранять их и передавать в вашу систему, начните с него. Если в важном месте приходится переносить данные руками или невозможно корректно повторить неудачное действие, имеет смысл продумать собственный обработчик. Написать его может помочь агент, но проверить сохранение, исправления и повторную доставку всё равно нужно на вашем сценарии.

Для работающего бота MAX требует получать события через Webhook: вы публикуете HTTPS-адрес обработчика, а платформа отправляет на него сообщения о действиях пользователей. Во время разработки можно использовать Long Polling, при котором программа сама ждёт события через API; при активной webhook-подписке этот способ недоступен. Для webhook нужен адрес, доступный извне на порту 443, и корректный TLS-сертификат с полной цепочкой. Поэтому локального запуска приложения на ноутбуке для приёма сообщений от MAX недостаточно.

Когда создаёте подписку, задайте отдельный secret и добавьте в обработчик проверку заголовка X-Max-Bot-Api-Secret. Так он сможет отклонить запрос с неподходящим секретом до обработки содержимого. Это другой секрет, чем токен бота: токен вы отправляете в MAX при своих вызовах API, а webhook secret проверяете у себя, когда событие приходит извне.

После получения события серверу нужно вернуть HTTP 200 за 30 секунд. Если ответ потерялся, пришёл с ошибкой или не уложился в срок, MAX может повторить доставку; при длительном отсутствии успешных ответов подписка автоматически отключается. Для мастерской это означает вполне обычную ситуацию: заявка уже сохранена, но MAX об этом не узнал и прислал то же событие ещё раз. Обработчик должен узнать повтор, иначе сотрудник получит два одинаковых обращения.

Чтобы отличать такие повторы, выберите устойчивый ключ по официальной структуре каждого типа события, который поддерживает ваш бот. Если вы раньше работали с Telegram, не переносите update_id по привычке: универсального поля с таким смыслом в MAX предполагать нельзя. Саму проверку тоже нужно связать с записью данных так, чтобы два параллельных обработчика не приняли один повтор одновременно. Одной последовательности «проверил, что записи нет, затем добавил» без защиты от такой гонки недостаточно.

Если обработка занимает долгое время, сначала надёжно сохраните событие в очереди, верните MAX ответ и продолжайте работу в фоне. HTTP 200 сообщает платформе, что событие принято, тогда как фраза «Заявка принята» обещает клиенту, что его обращение уже сохранено. Отправлять её нужно после успешной записи. А если сломалась только отправка ответа, повторяйте отправку для той же заявки, чтобы ошибка связи не создавала ещё одно обращение. Такой порядок нужно заложить в приложение при разработке обработчика.

Если бот не отвечает, полезно пройти путь одного сообщения и найти место, на котором оно остановилось. Сначала проверьте GET /me, затем появление события в обработчике, сохранение заявки и результат отправки ответа. Для этого можно присвоить тестовому обращению внутренний идентификатор и записывать его на каждом этапе. Контакты клиента и токены для такой диагностики в журнал не нужны.

После устранения ошибки откройте бота с обычного клиентского аккаунта и пройдите разговор целиком. Попробуйте исправить поле, дважды подтвердить отправку и воспроизвести отказ сохранения в тестовой среде. Затем прервите разговор, перезапустите тестовое приложение и вернитесь к черновику. Так вы увидите, сможет ли человек продолжить обращение после сбоя и появится ли у сотрудника одна понятная заявка.

Перед запуском стоит посчитать, сколько будет стоить вся работа бота. У MAX действуют свои условия платформы, у конструктора — тарифы и лимиты, а собственному приложению нужны сервер, хранилище и обслуживание. Если вы добавили языковую модель, её использование также учитывается отдельно. Поэтому по одному обещанию бесплатного конструктора нельзя определить, сколько будет стоить весь сценарий после запуска.

Посмотрите, что произойдёт, когда закончится пробный период, будет превышен лимит сообщений или заполнится хранилище. Сможете ли вы открыть старые заявки, принять новые и вовремя узнать о проблеме? Эти условия лучше соотнести с ожидаемым числом обращений до публикации ссылки. На случай сбоя оставьте клиенту другой способ связаться с мастерской, чтобы его обращение не зависело только от доступности бота.

Размещать ссылку и QR-код удобно после проверки уже опубликованного приложения. Откройте бота тем же способом, которым придёт клиент, отправьте тестовую заявку и найдите её в очереди сотрудника. Затем убедитесь, что клиент получил ответ. Этот проход свяжет всё, что вы настроили отдельно: карточку, программу, хранение и отправку сообщения.

Если вы собираете приложение в Agnostic, заявки можно хранить в Data, вход сотрудников настроить через App Auth, а связанные процессы организовать через Automations. Для разработки подключите к проекту внешнего агента из Cursor, Codex или Claude Code через MCP: он сможет прочитать контекст и предложить план интеграции. Обработчик MAX API при этом нужно разработать отдельно, включая получение событий, сохранение и защиту от повторов. Ниже можно взять за основу задание, которое учитывает эти части.

Подготовь в Agnostic приложение для заявок мастерской из MAX.
Назови выбранные проект и окружение. Проверь Agnostic MCP.
Если подключения нет, помоги получить инструкцию из меню MCP
нужного проекта, покажи план настройки и дождись авторизации
в браузере. Инструкция: https://agn0.ru/blog/connect-cursor/.
Прочитай контекст и доступные действия.
Для кода используй workspace проекта из Agnostic CLI;
если его нет, помоги получить его до редактирования кода.
Если App ещё нет, новый стартовый App создавай только в Live,
сначала покажи состав этого шага. Это не публикация приложения.
Затем отдельно готовь код, сборку и проверку в нужном окружении.

Сначала покажи модель данных и план серверной интеграции MAX
по актуальной официальной документации. Не предполагай наличие
готового MAX-коннектора или нужной атомарности записей Data.
Объясни надёжное хранение события и защиту от параллельных повторов.

Клиент выбирает услугу, описывает задачу и способ связи.
До подтверждения он может исправить сведения.
Сохраняй заявки в Data Agnostic. Подтверждай клиенту сохранение
только после успеха. Состояние диалога должно переживать рестарт.
Сделай кабинет сотрудников с App Auth и серверной проверкой прав.
Для Data и Automations используй текущий Runtime SDK на сервере.
Токен MAX и webhook secret читай из серверных секретов,
не выводи их и контакты в логи. Для проверки подготовь тестовые данные без настоящих контактов.

Подготовь Preview в Agnostic, покажи его адрес
и ссылку на кабинет в выбранном окружении.
Покажи, какие проверки действительно выполнены: новая заявка,
исправление поля, повтор события, ошибка записи, рестарт.
Для внешней доставки MAX отдельно проверь требования к HTTPS
и доступность выбранного адреса; не считай Preview доказательством.
Недостающие доступы и непроверенные части перечисли явно.
Изменения ресурсов выполняй через доступные действия с нужными
подтверждениями. Live обсудим после проверки и оценки расходов.

Для первого прохода выберите одну услугу и одного сотрудника. Когда тестовая заявка появится в кабинете, проследите её по журналу от входящего события до ответа клиенту и сохраните шаги проверки рядом с проектом. После изменения вопросов или серверной интеграции вы сможете повторить тот же разговор и убедиться, что клиент по-прежнему доходит до отправки, а сотрудник получает обращение.