Подготовка и настройка бота

Подключение к платформе MAX для партнёров и сервисам платформы — чат-ботам, мини-приложениям, каналам — пока доступно для ограниченного списка юрлиц и ИП

Уровень сложности: продвинутый

С навыками разработки вы можете создавать чат-ботов с неограниченным потенциалом и возможностью размещать мини-приложения в MAX

В этом разделе разберём, как создаётся бот, как настроить его взаимодействие с API MAX, как управлять ботом и подключить к нему готовое мини-приложение

Подготовка

Бот создаётся при подключении к платформе MAX для партнёров

Для одной организации доступно создание 5 ботов

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

У бота в MAX есть следующие поля или настройки:

Имя, которое отображается в MAX в чате с вашим ботом, — задаётся при создании бота в поле Название
Аватар (фото профиля) — загружается в виде логотипа при создании бота
Ник, который отображается в публичной ссылке, например для max.ru/idИНН_bot ником является idИНН_bot. Он генерируется автоматически при создании бота по шаблону idИНН_bot
Описание для пользователя, где указано, какие задачи решает бот: что умеет, чем полезен, как связаться с его владельцем или поддержкой. Всё это указывается при создании бота в поле Описание

Имя, аватар и описание можно изменить. Отредактировать ник пока нельзя. При изменении настроек обратите внимание на требования к полям

Профиль бота

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

При необходимости токен можно обновить. Также вы можете добавить ссылку на мини-приложение, которое хотите подключить к чат-боту

Пример токена

AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

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

Собрать сценарий для бота можно без кода, для этого есть конструкторы с набором готовых решений. Подробнее в разделе «Бот без разработки»

Отправляем API-запросы

API — это сервис, который позволяет взаимодействовать с платформой от имени бота. Бот отправляет запросы с токеном к API MAX и получает обновления с сервера в формате JSON

Передача токена через query-параметры больше не поддерживается — используйте заголовок Authorization: <token>

Вот так выглядит базовый запрос к API MAX.

Код

Скопировать

https://platform-api.max.ru/me?
Authorization: <token>

В ответ вернётся информация о боте — его имя, токен или ник

Если вы отправляете запросы на домен botapi.max.ru, перейдите на новый домен platform-api.max.ru до 1 октября. Это важно для стабильной работы ботов

Подробнее о работе с сервером, методах и параметрах запросов читайте в разделе «API»

Если вы пишете ботов на TypeScript или JavaScript, рекомендуем использовать нашу официальную библиотеку — она содержит разные стандартные методы и утилиты. Читайте подробнее в разделе «Библиотека MAX Bot API» здесь или на GitHub

Перейти в репозиторий библиотеки на Typescript

Перейти в репозиторий библиотеки на GO

Настраиваем уведомления

API MAX поддерживает два типа уведомлений о действиях пользователей с ботом — через Webhook и Long Polling. Использовать одновременно их нельзя — выберите один из типов

Технологии отправки уведомлений отличаются способом взаимодействия с сервером и продолжительностью отклика. Webhook после новых действий в чат-боте сам отправляет запрос на сервер, а Long Polling работает методом периодических запросов без триггера в боте

Чтобы подключить уведомления, отправьте к API POST-запрос /subscriptions. В запросе укажите URL, на который должна приходить информация о новых событиях с ботом

Webhook
Чтобы получить уведомления, выполните GET-запрос /subscriptions

Обратите внимание: для отправки вебхуков поддерживается только протокол HTTPS, включая самоподписанные сертификаты. HTTP не поддерживается

Long Polling
Чтобы получить уведомления, выполните GET-запрос /updates

Управляем ботом в MAX

Как изменить настройки бота

Изменить можно все настройки, кроме ника

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

Где посмотреть токен бота

Перейдите на платформу MAX для партнёров
Если у вас несколько ботов, в левом верхнем углу выберите нужный
Перейдите в раздел Чат-бот и мини-приложение → Настроить — токен находится в поле с одноимённым названием

Как обновить токен бота

Перейдите на платформу MAX для партнёров
Если у вас несколько ботов, в левом верхнем углу выберите нужный
Перейдите в раздел Чат-бот и мини-приложение → Настроить
Справа от поля с токеном нажмите на значок обновления

Как удалить бота

После удаления ваши клиенты не смогут пользоваться ботом. Удалённого бота нельзя восстановить

Чтобы удалить:

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

Добавляем мини-приложение в MAX

Подробнее о добавлении мини-приложений читайте в документации мини-приложений

Если у вас возникли вопросы, посмотрите раздел с ответами