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

Токен бота MAX связывает профиль бота с конструктором и позволяет обращаться к Bot API от его имени. Это не username, не ссылка на диалог и не код из SMS. Токен является секретом доступа, поэтому его нельзя публиковать или пересылать без необходимости.

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

1. Подготовьте профиль и владельца доступа

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

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

• Имя соответствует задаче бота.
• Username пригоден для публичной ссылки.
• Токен хранится в менеджере паролей.
• Доступ есть только у ответственных.

2. Получите токен после модерации

Откройте платформу MAX для партнёров либо «MAX для бизнеса», пройдите предусмотренную верификацию и создайте карточку чат-бота. По официальной документации подключение доступно юридическим лицам, ИП и самозанятым, являющимся резидентами РФ.

1. Заполните профиль бота.
2. Отправьте его на модерацию.
3. После одобрения откройте расширенные настройки.
4. Скопируйте токен целиком.
5. Сразу сохраните секрет в защищённом месте.

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

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

3. Подключите токен к MAXorg

Откройте кабинет MAXorg, перейдите в раздел ботов и добавьте проект. Вставьте токен. Рабочее название можно оставить пустым, тогда сервис возьмёт имя из профиля MAX.

После сохранения MAXorg обращается к методу /me Bot API. Успешный ответ возвращает идентификатор, имя, username и аватар. Сервис создаёт активную карточку и показывает токен только в маскированном виде. Тот же токен или тот же профиль нельзя незаметно подключить повторно.

Проверьте совпадение имени, username и аватара. Затем запустите бота с другого аккаунта. Новый диалог должен появиться в кабинете, если подключение и обработка событий настроены правильно.

4. Разберите ошибку по её типу

Ошибка «Укажите токен» означает пустое поле или строку без допустимых символов. Сообщение «Неверный токен» либо код 401 указывает на опечатку, отозванный секрет или значение от другого продукта. Скопируйте актуальный токен на стороне MAX, не пытаясь исправлять его вручную.

Сообщение «Этот бот уже подключён» означает конфликт токена или MAX user ID с существующей карточкой. Найдите проект и его владельца. Создание дубля не решит проблему и может привести к конкурирующей обработке сообщений.

• 401: проверьте актуальность и точность токена.
• 429: сократите частоту запросов и дождитесь указанной паузы.
• Нет связи с API: проверьте сеть, DNS и сертификаты.
• Профиль не совпал: убедитесь, что скопирован токен нужного бота.

При недоступности platform-api2.max.ru повторный выпуск токена нужен не всегда. Это может быть транспортная или временная проблема. Не меняйте одновременно токен, воронку и тексты: так будет сложно определить причину.

5. Замените токен при утечке

Ротация нужна после публикации секрета, ухода сотрудника с доступом, отзыва токена или устойчивой ошибки проверки. Сначала обновите секрет в настройках бота MAX. Затем откройте существующую карточку в MAXorg, вставьте новое значение и сохраните.

Сервис повторно вызывает /me и сверяет профиль. При успешной проверке подключение снова становится активным. Воронки, диалоги и настройки проекта не требуется создавать заново, поскольку меняется секрет существующего бота.

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

6. Проверьте работу и закрепите правила

Для минимального теста создайте воронку со стартом и одним сообщением. Активируйте её, откройте бота с тестового аккаунта и запустите диалог. Сообщение должно прийти один раз, а контакт должен появиться в аудитории.

1. Отправьте боту свободный текст.
2. Найдите сообщение в диалогах.
3. Ответьте оператором из кабинета.
4. Проверьте ссылочную кнопку.
5. Перезагрузите кабинет и проверьте статус.

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

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