Как создать чат-бот в MAX: доступ к платформе, сценарий и проверка запуска

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

Главный принцип запуска: сообщение пользователя, сохранённый запрос и созданная заявка — три разных состояния. Бот может сказать «Заявка создана» только после подтверждения от подключённой системы. Это защищает клиента от ложного результата, а бизнес — от потерянных и задублированных обращений.

Что проверить перед созданием бота MAX

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

Проверьте до начала работ:

1. Статус владельца профиля. Организация, ИП или самозанятый должны быть резидентами России. Не переносите сюда порядок регистрации из Telegram или другого мессенджера: у MAX свои условия доступа и модерации.
2. Данные профиля. Название и сведения владельца должны соответствовать данным бизнеса. Из профиля организации или ИП в карточку бота автоматически попадает связь с этой организацией.
3. Количество ботов. На дату проверки документация указывает до пяти ботов для организации или ИП и до двух для самозанятого. Перед созданием очередного бота сверьте лимит ещё раз: правила платформы могут измениться.
4. Способ управления. Создавать и редактировать бота, а также получать его токен можно в веб-версии платформы MAX для партнёров или в мини-приложении «MAX для бизнеса». Документация указывает, что последовательность действий в этих вариантах совпадает.
5. Назначение и содержание. Заранее подготовьте название, логотип и краткое описание реальных функций. Нельзя использовать сведения другой компании или вводить пользователя в заблуждение относительно назначения бота.
6. Юридическую информацию. Определите, какие сведения о владельце, правила использования, политика обработки персональных данных и контакты поддержки нужны именно вашему сценарию. Эти требования проверяет ответственный специалист заказчика.

Для проекта недостаточно узнать, что API существует. До выбора конструктора или собственной разработки отдельно подтвердите доступный тариф, права, операции API и способ получения событий. Упоминание CRM или платформы ботов в документации MAX не доказывает совместимость с конкретным продуктом.

Как создать профиль бота и пройти модерацию

После верификации профиля откройте раздел чат-ботов и создайте карточку. Документированная последовательность выглядит так:

1. Откройте профиль на платформе MAX для партнёров или мини-приложение «MAX для бизнеса».
2. Перейдите в раздел чат-ботов и выберите создание нового бота.
3. Загрузите логотип, укажите название и опишите назначение. В описании полезно обозначить доступные операции, способ связи с поддержкой и время работы оператора.
4. Проверьте карточку до отправки. Никнейм формируется платформой автоматически, поэтому не стройте сценарий запуска вокруг возможности выбрать произвольное имя.
5. Отправьте карточку на модерацию. Пока действует статус «На модерации», настройки изменить нельзя.
6. Если появился статус «Нужны исправления», прочитайте причину в карточке, исправьте конкретные поля и отправьте данные повторно. Исправление не гарантирует одобрение: результат определяет следующая проверка.
7. После успешной модерации проверьте опубликованный профиль, доступ к настройкам и получение токена. Только затем подключайте сценарии и внешние системы.

На дату проверки официальная документация указывает срок модерации до 48 часов по рабочим дням. Это условие платформы, а не обещание срока запуска проекта: повторная модерация, разработка и проверка интеграции занимают отдельное время. Перед подачей снова сверьте срок и требования в карточке MAX.

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

Как выбрать конструктор или разработку через API

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

Это критерии выбора, а не подтверждение совместимости какого-либо конструктора с MAX. Для сравнения дайте обоим вариантам один сценарий: собрать объект, описание проблемы и контакт, создать не более одной заявки и корректно пережить отказ CRM.

MAX публикует официальную библиотеку MAX Bot API для JavaScript и TypeScript. В документации примеры относятся к Node.js и передают токен через переменную окружения. Библиотека позволяет назначать обработчики событий, включая начало диалога, новое сообщение и message_callback, а также отправлять ответы через методы API.

Это описание документированной последовательности, а не отчёт о выполненном запуске. Если команда выбирает этот путь, разработчик сам создаёт проект, устанавливает пакет @maxhub/max-bot-api, передаёт токен безопасным способом и добавляет нужные обработчики. Ничего устанавливать на устройство читателя для понимания статьи не требуется.

Способ доставки обновлений — постоянное подключение, вебхук или другой поддерживаемый механизм — нужно выбрать по актуальному разделу API и условиям размещения. Не называйте любой callback вебхуком: callback-кнопка создаёт событие действия пользователя, а транспорт доставки событий — отдельное техническое решение.

Если вы ещё сравниваете назначение и формат решения, начните с критериев выбора чат-бота. Коммерческий запрос на разработку относится к услуге создания чат-ботов, а не к этой инструкции.

Как спроектировать диалог и передачу сотруднику

Сначала сформулируйте результат одной фразой: «Пользователь передаёт данные для заявки на обслуживание и получает подтверждённый статус». Затем оставьте только поля, без которых сотрудник не сможет начать обработку.

Для учебного сценария нужны:

• объект обслуживания;
• описание проблемы;
• контакт для обратной связи;
• подтверждение сводки перед отправкой.

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

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

Заранее задайте состояния диалога:

• Черновик: бот собрал часть полей, но пользователь ещё не подтвердил отправку.
• Принято ботом: подтверждение пользователя получено, началась обработка.
• Сохранено для повтора: запрос записан в устойчивую очередь, но CRM пока не подтвердила заявку.
• Создано во внешней системе: CRM вернула идентификатор заявки.
• Нужно участие сотрудника: автоматическое продолжение невозможно или пользователь выбрал оператора.

Такая модель не позволяет ответить «Готово» сразу после входящего сообщения. Она связывает каждую реплику с наблюдаемым результатом.

Как защитить токен и проверить интеграцию

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

Не обещайте «минимальные права токена», пока платформа не подтверждает нужную модель разрешений. Ограничьте то, чем управляете сами: доступ сотрудников к секрету, права процесса и сервера, сетевые подключения, содержимое журналов и доступ интеграции к CRM.

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

Проверяйте цепочку по отдельным фактам:

1. MAX передал событие обработчику.
2. Обработчик проверил формат и ключ повтора.
3. Запрос записан в устойчивую очередь или передан в CRM.
4. CRM вернула подтверждение и идентификатор заявки.
5. Только после четвёртого шага бот сообщил, что заявка создана.

Если CRM недоступна, возможны два честных ответа. При успешной записи в устойчивую очередь: «Запрос сохранён и будет отправлен повторно». Если сохранить запрос не удалось: «Не удалось подтвердить сохранение. Попробуйте позже или обратитесь к оператору».

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

Учебный пример заявки на обслуживание в MAX

Ниже — синтетический пример, а не клиентский кейс и не результат живого теста. Он показывает ожидаемые реплики и события для будущей разработки.

Исходные данные: объект «Офис на Лесной», проблема «не включается кондиционер», контакт «+7 900 000-00-00».

Диалог:

• Бот: «Выберите объект обслуживания».
• Пользователь: «Офис на Лесной».
• Бот: «Коротко опишите проблему».
• Пользователь: «Не включается кондиционер».
• Бот: «Подтвердите контакт для обратной связи: +7 900 000-00-00».
• Пользователь: «Подтверждаю».
• Бот: «Проверьте заявку: Офис на Лесной; не включается кондиционер; +7 900 000-00-00. Отправить, исправить или позвать оператора?»
• Пользователь: «Отправить».

После подтверждения обработчик получает событие evt-101 и вычисляет ключ операции service-request:user-42:dialog-17. Допустим, MAX доставил evt-101 дважды. В обоих сообщениях ключ одинаковый, поэтому число заявок определяется так: COUNT(DISTINCT idempotency_key). Для двух доставок одного ключа результат равен одной заявке, а не двум.

Теперь рассмотрим сбой: пользователь подтвердил один запрос, CRM не вернула ни одного идентификатора, но обработчик записал один элемент в устойчивую очередь. Результат состоит из двух показателей:

• подтверждённые заявки CRM: 0;
• запросы, сохранённые для повторной отправки: 1.

Бот отвечает: «Запрос сохранён и будет отправлен повторно». Он не пишет «Заявка создана» и тем более не сообщает, что ремонт выполнен. После успешного повтора и ответа CRM бот может показать номер заявки или другой согласованный идентификатор.

Вывод из примера: проверять нужно не красивый диалог сам по себе, а переход между состояниями. У принятого сообщения, записи в очереди и заявки CRM разные доказательства и разные ответы пользователю.

Как принять запуск и поддерживать бота

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

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

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

Switch On AI может разобрать одну операцию, спроектировать бота или интеграцию и согласовать прототип после проверки данных, API и доступов. Это не означает готовую совместимость с любой CRM или тарифом MAX. Опишите сценарий и подключаемую систему на странице контактов — проверим условия MAX, обязательные поля, исключения и объём разработки. Прототип помогает согласовать логику, но не заменяет полноценное внедрение и приёмку.