Бот MAX

max bot работает с ботом через официальный Bot API MAX по токену бота. С личным аккаунтом он не связан: у бота своё имя, свои чаты и свой токен, а max … без слова bot — это ваш личный аккаунт (usage.md).

Бота создают на business.max.ru. MAX выдаёт ботов только подтверждённым организациям, ИП и самозанятым, и каждый бот проходит модерацию.

Полный список команд и опций — commands.md.

Первая минутаCopy Anchor Link

max sales bot auth set                                  # токен — в скрытом вводе
max sales bot me                                        # какой это бот

auth set сначала спрашивает у MAX, чей это токен, и только потом сохраняет его. Опечатка не затрёт токен, который уже работает.

Где взять номер чатаCopy Anchor Link

У MAX нет списка чатов бота, поэтому номер чата узнают из того, что бот уже делал или получил.

• Диалог с человеком. Пишите ему как user:<номер>. Отправка печатает номер чата, куда ушло сообщение, — поле chatId.

• Группа или канал. Добавьте туда бота, потом попросите у MAX последние обновления:

  Copy Text

  max sales bot api get-updates --limit 10

  Номер чата — в поле chat_id. Если нового нет, команда ждёт до 30 секунд; --poll-timeout 0 — не ждать. Полученные так обновления MAX второй раз не отдаёт. Пока у бота задан вебхук, эта команда не работает.

Откройте чат командой max sales bot chats get с этим номером: после этого бот знает его название, и в командах ниже чат можно называть по названию. chats list показывает все чаты, которые бот уже видел.

• У группы и канала номер отрицательный.
• Положительный номер — почти всегда человек. Человеку пишут как user:<номер>: номер без user: MAX примет за чат и ответит «чат не найден» (код 6), а max подскажет, как надо.

Несколько ботовCopy Anchor Link

Бот хранится под именем, которое вы выбираете, и это имя — первое слово команды, как профиль у личного аккаунта:

max sales bot auth set
max support bot auth set
max support bot messages send user:4815162342 "Ваша заявка принята"
max bot list --check          # все имена с токеном бота и какой бот за каждым

Без имени — профиль из настройки defaultProfile, а без неё default: max bot me. MAX_PROFILE задаёт имя на всю сессию оболочки.

ТокенCopy Anchor Link

Токен лежит в системном хранилище паролей, в записи bot:<имя>, отдельно от токена личного аккаунта. Если хранилища нет, он ложится в файл с правами 0600, как токен личного аккаунта.

max sales bot auth show       # откуда взят токен и какой это бот
max sales bot auth remove     # забыть токен

MAX_BOT_TOKEN важнее хранилища: если переменная задана, берётся она — так это работает в CI. auth set токен из этой переменной не сохраняет.

СообщенияCopy Anchor Link

Чат указывается номером, человек — как user:<номер>, а чат, который бот уже видел, — ещё и названием:

max sales bot messages send "Команда продаж" "Сборка готова"
max sales bot messages send user:4815162342 "Здравствуйте"
max sales bot messages send "Команда продаж" "**Итоги недели** в закрепе" --format markdown
max sales bot messages send "Команда продаж" "Принято" --reply-to mid.0000019a7f3c21de
echo "Текст из трубы" | max sales bot messages send "Команда продаж" -

--silent отправляет без уведомления. Текст — до 4000 символов. Номера user:4815162342 и mid.0000019a7f3c21de здесь и ниже выдуманы — подставьте свои.

ФайлыCopy Anchor Link

--file прикладывает файл с диска. Картинка, видео и звук узнаются по расширению, всё остальное уходит файлом; --type image|video|audio|file задаёт вид явно. Текст с файлом можно не писать:

max sales bot messages send "Команда продаж" "Отчёт за неделю" --file report.pdf
max sales bot messages send "Команда продаж" --file screenshot.png

Файл сначала загружается в MAX, потом уходит сообщение. Пока MAX обрабатывает видео или большой файл, он отвечает «ещё не готово», и max ждёт — четыре раза, всего около девяти секунд. Если загрузка не удалась, в чат ничего не уходит.

uploads put только загружает файл и печатает вложение — его кладут в attachments тела для bot api send-message:

max sales bot uploads put report.pdf

max sales bot messages list "Команда продаж" --limit 20
max sales bot messages get mid.0000019a7f3c21de
max sales bot messages edit mid.0000019a7f3c21de "Исправленный текст"
max sales bot messages delete mid.0000019a7f3c21de

Если связь оборвалась во время отправки, max не повторяет её сам: он говорит, что не знает, дошло ли сообщение (код 14). Проверьте чат, прежде чем отправить снова.

ЧатыCopy Anchor Link

У MAX нет запроса «все чаты бота». Поэтому chats list показывает чаты, которые этот бот видел на этом компьютере: те, что вы открыли через chats get, куда он писал и откуда читал. Это не полный список.

max sales bot chats list
max sales bot chats get "Команда продаж"
max sales bot chats pin "Команда продаж" mid.0000019a7f3c21de
max sales bot chats unpin "Команда продаж"
max sales bot chats action "Команда продаж" typing_on
max sales bot chats leave "Команда продаж"    # вернуть бота может только админ чата

Участники и админыCopy Anchor Link

Боту нужно быть админом чата с правом на это действие.

Сначала бота нужно пустить в группы: по умолчанию MAX запрещает добавлять бота в групповые чаты, и добавить его не выйдет — ни из приложения, ни командой max chats members add (ответ participants.filter.out). Разрешить — на business.max.ru: бот → ⋮ → Настройки → Приватность (документация MAX). Потом добавьте его в группу и сделайте админом в приложении MAX. Для проверки чата боту нужно право читать сообщения: без него MAX не отдаёт боту ни одного сообщения группы. Выдать его можно и своим аккаунтом: max chats admins add "Поход" <номер бота> --can read,members,delete.

max sales bot members list "Команда продаж" --limit 50
max sales bot members add "Команда продаж" 4815162342 2342481516
max sales bot members remove "Команда продаж" 4815162342 --block
max sales bot admins list "Команда продаж"
max sales bot admins add "Команда продаж" 4815162342 --permissions write,pin_message --alias "Дежурный"
max sales bot admins remove "Команда продаж" 4815162342

members list отдаёт до 100 человек и marker; следующая страница — --marker с этим числом. Права админа: read_all_messages, add_remove_members, add_admins, change_chat_info, pin_message, edit_link, write, edit, delete, can_call, view_stats.

Локальная копияCopy Anchor Link

Всё, что бот прочитал, отправил или получил, max сохраняет на этом компьютере. Из этой копии можно читать без сети и искать:

max sales bot messages list "Команда продаж" --offline
max sales bot messages get mid.0000019a7f3c21de --offline
max sales bot messages search "итоги недели"

Обычные команды всё равно спрашивают MAX: у него вся история чата. Сообщение, которое бот удалил сам или о котором updates watch узнал, что его удалили, из копии пропадает. Если его удалили, пока watch не работал, копия об этом не знает.

По той же копии — о людях. Человека называют номером, @username или частью имени; если под имя подходят двое, max покажет обоих и попросит номер.

max sales bot people show @ann                   # где писала, и её личный чат с ботом
max sales bot people show @ann --refresh         # сначала перечитать личный чат у MAX
max sales bot messages search --from @ann        # всё, что она написала
max sales bot messages search "счёт" --from @ann --from Борис
max sales bot messages between @ann Борис --limit 20

between показывает только чаты, где писал каждый из названных, по 20 последних сообщений из каждого, старые сверху. «Общий чат» здесь — тот, где бот видел сообщения от каждого, а не список участников из MAX.

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

max shop config set --bot readOtherBots true          # боту shop можно читать всех ботов
max shop config set --bot readOtherBots news,support  # или только этих
max shop bot messages search заказ --bots news        # и тогда — явно, в команде
max shop bot people show @ann --all-bots              # все, кого разрешено

--all-bots и --bots есть у messages search, people show и messages between. Без readOtherBots оба отказывают с кодом 5 и называют команду, которая разрешает. Агенту через max <имя> bot mcp те же поля (all_bots, bots) предлагаются, только когда это разрешено.

ОбновленияCopy Anchor Link

max sales bot updates watch                # до Ctrl-C
max sales bot updates watch --jsonl --types message_created,message_edited

watch печатает события по мере прихода и сохраняет их сообщения в локальную копию, а кто вступил в чат и кто вышел — для проверки чата по правилам (ниже). Следующий запуск продолжает с того места, где остановился прошлый. Пока у бота задан вебхук, watch не работает.

Всё, что получил watch, MAX больше не отдаст никому другому, кто читает этого бота через get-updates.

Проверка чата по правиламCopy Anchor Link

Бот может следить за группой, где он админ, по тем же правилам, что и max chats check у личного аккаунта (groups.md). Правила у каждого бота свои:

max sales bot chats rules set -72894839451 invites remove        # приглашения в чужие чаты — удалять автора
max sales bot chats rules set -72894839451 consent.remove allow  # без вопросов
max sales bot chats check -72894839451                           # проверить, что нового
max sales bot chats check -72894839451 --dry-run                 # только показать

Проверка смотрит сообщения с прошлой проверки (в первый раз — за сутки) и тех, кто вступил, и делает то, что разрешают правила и уровень согласия. Отличия от личного аккаунта:

• Удалённого бот банит: вернуться по ссылке человек не сможет — у него ссылка открывается как «устаревшая или не работает», у остальных работает. Вернуть его может админ, добавив вручную (max chats members add). --no-ban — удалить без бана. Бан работает только в чатах со ссылкой-приглашением.
• Кто вступил, бот знает только от updates watch. MAX отдаёт каждое событие одному читателю, поэтому проверка берёт вступления из того, что сохранил watch. Пока watch не запущен, проверка судит только сообщения и так и говорит.
• Возраста аккаунта у бота нет — Bot API его не даёт, и это правило через бота не срабатывает.

Боту нужны права админа на удаление сообщений и участников.

КомментарииCopy Anchor Link

Комментарии — под постом канала. Первым идёт номер поста (mid.…), вторым — номер комментария:

max sales bot comments list mid.0000019a7f3c21de --limit 20
max sales bot comments get mid.0000019a7f3c21de 42
max sales bot comments send mid.0000019a7f3c21de "Спасибо за вопрос"
max sales bot comments edit mid.0000019a7f3c21de 42 "Исправлено"
max sales bot comments delete mid.0000019a7f3c21de 42

Комментарий проходит тот же список получателей, что и сообщение в канал.

КнопкиCopy Anchor Link

Когда человек нажимает кнопку под сообщением бота, бот получает номер нажатия (callback_id) и отвечает на него:

max sales bot callbacks answer f9LHodD0cOL5 --notification "Готово"
max sales bot callbacks answer f9LHodD0cOL5 --text "Заказ подтверждён"

--notification показывает короткую надпись только нажавшему, --text заменяет текст сообщения с кнопкой. Ответ идёт в тот чат, где нажали, а по номеру нажатия чат не узнать, поэтому список получателей к ответу не применяется.

Меню командCopy Anchor Link

Меню — то, что человек видит, набрав / в чате с ботом.

max sales bot commands list
max sales bot commands set start=Начать help=Помощь "report=Отчёт за день"
max sales bot commands clear

set заменяет меню целиком. Каждая команда — имя=описание; описание можно не писать.

ВебхукиCopy Anchor Link

Вебхук — адрес, на который MAX сам присылает всё, что получил бот. Пока вебхук задан, получать обновления через get-updates бот не может.

max sales bot webhooks list
max sales bot webhooks set https://bot.example.ru/max --secret-stdin --types message_created,bot_started
max sales bot webhooks delete https://bot.example.ru/max

• Адрес — HTTPS на порту 443, с сертификатом, которому доверяет MAX.
• Новый адрес не заменяет старый: MAX шлёт каждое обновление на оба. Поэтому set отказывает, пока задан другой адрес. Удалите старый или добавьте --add, если два адреса нужны.
• --secret-stdin спрашивает секрет в скрытом вводе или читает его из трубы. MAX присылает его в заголовке X-Max-Bot-Api-Secret, по нему сервер узнаёт MAX. В командной строке секрета нет.

Кому бот может писатьCopy Anchor Link

Бот подчиняется тем же настройкам профиля, что и личный аккаунт:

• readOnly — бот ничего не меняет, только читает;
• allow — только названные действия: отправка send, правка edit, удаление delete, закрепление pin, участники и настройки чата groups, команды бота profile, получение обновлений read. Действие без своего слова (вебхуки) при заданном allow запрещено.

У каждого бота свой список чатов, в которые ему можно писать:

max sales bot recipients add "Команда продаж"
max sales bot recipients list
max sales bot recipients remove "Команда продаж"
max sales bot recipients clear            # писать можно снова в любой чат

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

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

max sales bot sends list

В журнале чат, вид действия, исход и длина текста, но не сам текст. Список и журнал проходит любая запись бота, в том числе через bot api. Лимита сообщений в час у бота нет, пока он не задан в разделе bot файла настроек (max <имя> config set --bot sendsPerHour 200, см. configuration.md).

Любая операция APICopy Anchor Link

Все операции Bot API доступны как max bot api <операция>. Команды собраны из официальной схемы API, поэтому новая операция MAX появляется здесь после обновления схемы:

max sales bot api get-my-info
max sales bot api get-subscriptions
max sales bot api answer-on-callback --callback-id f9LHodD0cOL5 --body '{"notification": "Готово"}'
max sales bot api send-message --user-id 4815162342 --body-file message.json

Параметры пути и запроса — флаги, тело — JSON в --body, --body - (из трубы) или --body-file. Перед отправкой тело сверяется со схемой, а в сообщении об ошибке — поле и что в нём ожидалось, без самого значения. Список всех операций и того, какая из них читает, а какая пишет, — dev/bot-api-coverage.md.

Для скриптов и агентовCopy Anchor Link

С --json команда печатает на stdout только данные, ошибку — на stderr, с кодом выхода:

Сообщения выводятся в той же форме, что и у личного аккаунта. Идентификатор больше 2^53 печатается строкой, чтобы не потерять цифры.

--trace и --record работают и для бота: каждый запрос к Bot API — строкой в stderr, загрузка файла — вид, размер и код ответа, без адреса и имени файла. Неудачный запуск сохраняется, его видно в max runs list (diagnostics.md).

СертификатCopy Anchor Link

Сертификат platform-api2.max.ru подписан корневым сертификатом Минцифры, которого нет в Node. max добавляет его только в свои запросы к Bot API и ничего не меняет в системе. Запросы бота называют себя max-cli/<версия>.

Бот для агента (MCP)Copy Anchor Link

max <имя> bot mcp отдаёт бота агенту, как max mcp — личный аккаунт:

claude mcp add sales-bot -- max sales bot mcp
max sales bot mcp config          # запись для Claude Desktop, Cursor и других

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

• --allow-send — писать от имени бота: отправлять текст, править, закреплять, показывать «печатает», комментировать и отвечать на кнопки;
• --allow-delete — удалять сообщения и комментарии;
• --allow-moderate — проверка чата по правилам (max_bot_chats_check) и добавление и удаление участников. Действия, которые правила велят подтверждать, агент показывает вам одной формой;
• --confirm-send — каждую запись вы сначала видите в форме.

Каждая запись идёт через ту же команду, что вы набрали бы сами: её проходят список получателей бота, readOnly, allow и журнал. Агенту недоступны токен и вебхуки; список получателей, меню команд и админов он только читает, а не меняет; выход из чата, отправка файлов и bot api ему тоже недоступны.