Токен бота MAX
Чтобы подключить чат-бота MAX к Меркурий-ИИ, сначала нужно создать бота в кабинете MAX, пройти модерацию и получить токен доступа. Затем токен указывается в Меркурии, после чего программа регистрирует подключение и настраивает обмен сообщениями. Ниже подробно разобраны все этапы: от регистрации до проверки подключения.
Официальная документация MAX для разработчиков находится в справке MAX по чат-ботам. Если интерфейс кабинета или порядок действий изменится, ориентируйтесь также на актуальные инструкции MAX.
Поля в Меркурий-ИИ
Настройки находятся в разделе Розница → Дисконтная программа → Боты → Бот MAX.
Здесь выполняется подключение уже созданного бота. Саму регистрацию бота и получение токена нужно предварительно выполнить в кабинете MAX.
Токен бота
Поле «Токен бота» предназначено для ввода токена, который вы получили в кабинете MAX. Токен подтверждает право Меркурия обращаться к вашему боту и выполнять необходимые операции от его имени.
Токен вводится целиком, без дополнительных слов и пояснений. Поскольку это секретные данные, поле отображает значение в скрытом виде.
Если вы ещё не получили токен, воспользуйтесь ссылкой «Как получить токен» рядом с настройкой. Она открывает эту инструкцию.
Webhook secret (опционально)
Поле «Webhook secret (опционально)» предназначено для дополнительного секрета, связанного с регистрацией Webhook — механизма, через который MAX передаёт события и сообщения бота на сервер Меркурия.
Заполнять это поле необязательно. Если оставить его пустым, секрет будет сгенерирован автоматически при регистрации Webhook. Поэтому, если у вас нет отдельной причины задавать собственное значение, просто оставьте поле пустым.
Статус
В строке «Статус» отображается состояние подключения:
- «не подключён» — бот ещё не подключён к Меркурию;
- ссылка на бота — подключение выполнено, по ссылке можно открыть вашего бота в MAX.
После подключения используйте ссылку, чтобы проверить, что подключён именно тот бот, который вы создавали в кабинете MAX.
Кнопки подключения
- «Подключить MAX» — запускает подключение бота. Меркурий использует указанный токен и регистрирует Webhook для получения сообщений и событий от MAX.
- «Отключить» — отключает ранее подключённого бота. Кнопка появляется, когда подключение уже существует.
Если вы изменили токен или перевыпустили его в кабинете MAX, укажите новое значение в поле и снова выполните подключение.
WebApp для MAX
После успешного подключения появляется дополнительный блок со ссылкой «WebApp для MAX». Это адрес мини-приложения, которое может открываться внутри MAX.
Адрес доступен для просмотра и копирования. Используйте кнопку «Копировать», чтобы перенести его в настройки MAX без ошибок при ручном вводе.
Для облачной версии Меркурия используется домен rus.mercury-erp.ru. Сам адрес мини-приложения формируется программой.
Чтобы MAX открывал мини-приложение из вашего бота, скопированный URL нужно указать в кабинете MAX: Чат-боты → Расширенные настройки → Настроить, поле URL мини-приложения.
Подробная инструкция: «WebApp MAX».
Сообщение об ошибке
Если при подключении возникла проблема, в блоке может появиться строка с сообщением об ошибке. Не игнорируйте её: она помогает понять, почему подключение не завершилось. Проверьте токен и настройки бота в кабинете MAX, затем повторите подключение.
Регистрация и создание бота
Бот создаётся не в Меркурии, а в официальном кабинете MAX для бизнеса. Для этого понадобится профиль организации, индивидуального предпринимателя или самозанятого, прошедший верификацию.
Шаг 1. Откройте кабинет MAX
Перейдите на сайт business.max.ru и войдите в свой аккаунт.
Если профиль организации или предпринимателя ещё не создан либо не прошёл проверку, сначала завершите необходимые действия в кабинете. Без верифицированного профиля создание и подключение бота может быть недоступно.
Шаг 2. Перейдите к чат-ботам
В кабинете найдите раздел «Чат-боты». В нём находятся созданные боты и инструменты для управления ими.
Выберите действие «Создать», чтобы зарегистрировать нового бота.
Шаг 3. Заполните сведения о боте
При создании MAX предложит указать основные сведения:
- Название — имя, по которому пользователи будут узнавать бота. Лучше использовать название магазина, компании или сервиса.
- Описание — короткое объяснение, для чего нужен бот и что пользователь сможет через него делать.
- Аватар — изображение, которое будет отображаться в профиле бота. Обычно используют логотип компании или магазина.
Постарайтесь заполнить карточку понятно для будущих покупателей. Например, если бот предназначен для интернет-магазина, в описании можно указать, что через него покупатели смогут открыть каталог, оформить заказ и получать сообщения о заказах.
Шаг 4. Сохраните бота и дождитесь модерации
После заполнения карточки сохраните её. Созданный бот должен пройти модерацию MAX.
Пока модерация не завершена, получение токена может быть недоступно. Не пытайтесь подключить такого бота в Меркурии раньше времени: сначала дождитесь, когда MAX разрешит дальнейшую настройку и выдаст доступ к токену.
Получение токена после модерации
Токен выдаётся в кабинете MAX после того, как бот создан и прошёл необходимые проверки.
- Откройте кабинет MAX.
- Перейдите в раздел «Чат-боты».
- Выберите созданного бота, которого собираетесь подключить к Меркурию.
- Откройте раздел «Интеграция» или перейдите в «Расширенные настройки» → «Настроить» — расположение нужного действия зависит от интерфейса кабинета.
- Найдите действие «Получить токен» либо поле «Токен».
- Скопируйте токен целиком.
Токен — это не название бота и не ссылка на его страницу. Это специальная строка доступа, с помощью которой внешняя программа может взаимодействовать с ботом. Именно эту строку нужно перенести в Меркурий.
Важно: не публикуйте токен в открытом доступе, не отправляйте его покупателям и не размещайте в общедоступных документах. Любой, кто получил токен, может получить возможность управлять ботом через программный интерфейс.
Подключение бота в Меркурии
Когда токен получен, можно вернуться в Меркурий и завершить настройку.
- Откройте Розница → Дисконтная программа → Боты → Бот MAX.
- Вставьте скопированный токен в поле «Токен бота».
- Поле «Webhook secret (опционально)» оставьте пустым, если не собираетесь задавать собственный секрет.
- Нажмите «Подключить MAX».
- Дождитесь завершения операции и проверьте строку «Статус».
При успешном подключении Меркурий зарегистрирует Webhook — адрес, на который MAX будет передавать сообщения и события вашего бота. Благодаря этому бот сможет взаимодействовать с Меркурием.
После подключения в блоке также появится URL мини-приложения «WebApp для MAX». Скопируйте его и укажите в кабинете MAX в настройках мини-приложения:
Чат-боты → выберите бота → Расширенные настройки → Настроить → URL мини-приложения.
Это отдельная настройка: подключение токена связывает бота с Меркурием, а URL WebApp указывает MAX, какое мини-приложение открывать пользователю.
Подробная инструкция по настройке адреса: «WebApp MAX».
Если токен не отображается или подключение не работает
Если в кабинете MAX нет возможности получить токен или Меркурий не принимает его, проверьте наиболее распространённые причины.
Бот ещё проходит модерацию
После создания бота MAX может потребоваться время на проверку. Пока модерация не завершена, получение токена может быть недоступно. Дождитесь завершения проверки и снова откройте карточку бота.
Профиль организации не верифицирован
Для работы с чат-ботами требуется верифицированный профиль организации, ИП или самозанятого. Если профиль не прошёл проверку, завершите верификацию в кабинете MAX.
Используется старый токен
Если вы перевыпускали токен, прежнее значение больше не следует использовать. Скопируйте последний выданный токен и замените им значение в Меркурии. После этого снова нажмите «Подключить MAX».
Проверьте, того ли бота вы подключаете
Если в кабинете создано несколько ботов, убедитесь, что токен скопирован именно от того бота, которого вы собираетесь использовать в Меркурии. Название и ссылка в статусе после подключения помогут проверить результат.
Посмотрите сообщение об ошибке в Меркурии
Если подключение не удалось, прочитайте текст в строке ошибки под настройками MAX. Проверьте токен и состояние бота в кабинете, затем повторите подключение.
Безопасность токена
Токен следует считать паролем от управления ботом. Его нужно хранить так же внимательно, как пароль от рабочего аккаунта.
- Не отправляйте токен покупателям и не публикуйте его в сообщениях, на сайте или в открытых файлах.
- Не вставляйте токен в общедоступные примеры кода и инструкции.
- Если есть подозрение, что токен стал известен посторонним, перевыпустите его в кабинете MAX.
- После перевыпуска замените старый токен в Меркурии и снова нажмите «Подключить MAX».
При перевыпуске токена обязательно используйте новое значение. Старый токен не подходит для дальнейшего подключения.