bot

Бот MAX

Эта страница нужна, когда у вас есть бот MAX или вы хотите его завести, и ему надо писать сообщения, отвечать людям, следить за группой или наводить в ней порядок. Вы узнаете, как подключить бота к max, найти его чаты, отправлять и читать сообщения от имени бота, ограничить, куда он может писать, и передать бота своему AI-агенту.

Несколько слов, которые встретятся ниже:

• Бот — отдельный аккаунт MAX, которым управляет программа. max sales bot работает с ним через официальный Bot API MAX. С личным аккаунтом он не связан: у бота своё имя, свои чаты и свой токен, а max … без слова bot — это ваш личный аккаунт (см. работу с личным аккаунтом).
• Токен — пароль бота. Бота создают на business.max.ru. MAX выдаёт ботов только подтверждённым организациям, ИП и самозанятым, и каждый бот проходит модерацию.
• Имя бота — слово, под которым вы храните его токен, например sales. Это первое слово каждой команды бота: max sales bot ….
• Локальная копия — то, что бот прочитал, отправил или получил, сохранённое на этом компьютере.

Что можно сделать

Задача	Команда
Подключить бота и проверить, какой это бот	max <бот> bot auth set, max <бот> bot me
Отправлять, править, удалять и закреплять сообщения и файлы	max <бот> bot messages send|edit|delete|pin
Видеть новые сообщения, нажатия кнопок и вступления	max <бот> bot watch
Читать и искать то, что видел бот	max <бот> bot messages list, max <бот> bot search messages
Скачать старую историю чата	max <бот> bot store fetch
Управлять участниками и админами	max <бот> bot chats members, max <бот> bot chats admins
Наводить порядок в группе по своим правилам	max <бот> bot chats moderate
Отвечать в комментариях под постами канала	max <бот> bot comments
Отвечать на кнопки, задавать меню команд и вебхуки	max <бот> bot callbacks, commands, webhooks
Ограничить чаты, куда бот может писать	max <бот> bot recipients
Вызвать любую операцию Bot API	max <бот> bot api <операция>
Передать бота AI-агенту	max <бот> bot mcp

Полный список команд и опций — в справочнике команд.

Первая минута

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

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

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

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

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

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

  max sales bot api get-updates --limit 10

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

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

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

Несколько ботов

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

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

Имя профиля обязательно: первое слово, MAX_PROFILE на всю сессию оболочки или настройка defaultProfile. Без него команда бота останавливается и перечисляет профили.

Токен

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

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

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

Сообщения

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

max sales bot messages send "Команда продаж" "Сборка готова"
max sales bot messages send user:4815162342 "Здравствуйте"
max sales bot messages send "Команда продаж" "**Итоги недели** в закрепе" --md
max sales bot messages send "Команда продаж" "Принято" --reply-to mid.0000019a7f3c21de
echo "Текст из трубы" | max sales bot messages send "Команда продаж" -
max sales bot messages list "Команда продаж" --limit 20
max sales bot messages show "Команда продаж" mid.0000019a7f3c21de
max sales bot messages edit "Команда продаж" mid.0000019a7f3c21de "Исправленный текст"
max sales bot messages delete "Команда продаж" mid.0000019a7f3c21de --allow-dangerous
max sales bot messages pin "Команда продаж" mid.0000019a7f3c21de --notify
max sales bot messages unpin "Команда продаж" mid.0000019a7f3c21de

--silent отправляет без уведомления. Текст — до 4000 символов. Номера user:4815162342 и mid.0000019a7f3c21de здесь и ниже выдуманы — подставьте свои. --html — текст в HTML, --md и --html вместе нельзя. Удаление спрашивает подтверждение; --allow-dangerous отвечает «да». Закрепление по умолчанию тихое, --notify сообщит участникам. В ответе на отправку — само сообщение и operationId, номер этой записи в журнале.

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

Файлы

--file прикладывает файл с диска. Картинка, видео и звук узнаются по расширению, всё остальное уходит файлом. --photo отправляет картинку фотографией, --voice — файл Ogg Opus голосовым, --as-file — видео файлом. Известные файлы с учётными данными, папки самого max и хранилище не уходят без --allow-any-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 нет запроса «все чаты бота». Поэтому chats list показывает чаты, которые этот бот видел на этом компьютере: те, что вы открыли через chats show, куда он писал и откуда читал. Это не полный список.

max sales bot chats list
max sales bot chats show "Команда продаж"
max sales bot chats action "Команда продаж" typing    # typing, photo, video, voice, file
max sales bot chats leave "Команда продаж"    # вернуть бота может только админ чата

Участники и админы

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

Бот-админ может добавлять участников через bot chats members add. Документация MAX объявляет этот метод удалённым, но сервер MAX его выполняет; доступен ли метод, решает сервер.

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

max sales bot chats members list "Команда продаж" --limit 50
max sales bot chats members add "Команда продаж" 4815162342 2342481516
max sales bot chats members remove "Команда продаж" 4815162342 --block
max sales bot chats admins list "Команда продаж"
max sales bot chats admins add "Команда продаж" 4815162342 --can read,pin --title "Дежурный"
max sales bot chats admins remove "Команда продаж" 4815162342

members list отдаёт до 100 человек и marker; следующая страница — --marker с этим числом. Права админа в --can — те же слова, что у max personal chats admins add: read, members, admins, info, pin, link, edit, delete. read — это право читать сообщения группы.

Локальная копия

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

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

Поиск — по словам, лучшие совпадения сверху; --newest — новые сверху. Нужны все слова; "фраза", -слово, а OR б и фильтры from:, chat:, after:, before:, has: работают, а опечатка исправляется. Для строгого поиска по общему архиву используйте обычный поиск с in:bots.

Чтобы в копии была и старая история чата, скачайте её:

max sales bot store fetch "Команда продаж"                 # до 1000 сообщений, новые сначала
max sales bot store fetch "Команда продаж" --last 500      # пока не будет 500 последних
max sales bot store fetch "Команда продаж" --since-time 7d # за последние семь дней

Повторный запуск продолжает с того места, где остановился прошлый, и уже скачанное не просит. Между запросами — пауза в секунду (--pause), по 100 сообщений за запрос (--page-size).

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

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

max sales bot contacts show @ann                 # где писала, и её личный чат с ботом
max sales bot contacts show @ann --refresh       # сначала перечитать личный чат у MAX
max sales bot search messages --from @ann        # всё, что она написала
max sales bot search messages "счёт" --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 search messages заказ --bots news        # и тогда — явно, в команде
max shop bot contacts show @ann --all-bots            # все, кого разрешено

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

Обновления

max sales bot watch                       # новые сообщения, до Ctrl-C или --timeout
max sales bot watch --events --jsonl       # и всё остальное: правки, удаления, кнопки, кто вошёл и вышел
max sales bot watch --types message_created,message_edited

watch сначала сохраняет пришедшее — сообщения в локальную копию, нажатые кнопки для callbacks answer, кто вступил в чат и кто вышел для проверки чата по правилам (ниже) — и только потом печатает. Без --events печатаются только новые сообщения; с --events каждая строка называет своё событие (message, edit, delete, callback, joined, left, added, removed, started, other). --types — имена событий MAX. Следующий запуск продолжает с того места, где остановился прошлый. Пока у бота задан вебхук, watch не работает.

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

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

Бот может следить за группой, где он админ, по тем же правилам, что и max personal chats moderate у личного аккаунта (см. правила в группах, которые вы ведёте). Правила у каждого бота свои:

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

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

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

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

Комментарии

Комментарии — под постом канала. Первым идёт номер поста (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

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

Кнопки

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

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

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

Меню команд

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

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

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

Вебхуки

Вебхук — адрес, на который 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. В командной строке секрета нет.

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

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

• permissions — уровни по ключам bot.*; 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, см. настройки).

Любая операция API

Все операции Bot API доступны как max sales 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. --body-file - также читает stdin. Нативный параметр timeout называется --poll-timeout, а глобальный --timeout ограничивает всю команду. Общая опция --store-token <profile> недоступна для текущих методов MAX: все они отклоняют её до выполнения операции. Перед отправкой тело сверяется со схемой, а в сообщении об ошибке — поле и что в нём ожидалось, без самого значения. Список всех операций и того, какая из них читает, а какая пишет, — покрытие Bot API.

Если бот отказывает или ошибается

Отказ или ошибка объясняются в сообщении об ошибке, а команда завершается с кодом:

Код	Что случилось	Что делать
4	нет токена бота или MAX его не принял	заново выполнить bot auth set
5	профиль только для чтения или действие не разрешено allow	менять права, только если вы хотите это разрешить
6	чат не найден — например, по названию, которого бот ещё не видел, или человек без user:	указать номер чата или user:<номер>, либо открыть чат через bot chats show
7	чата нет в списке получателей бота	добавить чат через bot recipients add
8	исчерпан sendsPerHour бота	подождать или поднять лимит
14	ответа не пришло: неизвестно, выполнил ли MAX запись	проверить чат, прежде чем повторять

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

Сертификат

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

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

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

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

Агенту доступно то, что разрешает профиль бота: бот, чаты, которые он видел, сообщения, поиск, люди, участники и админы, комментарии, меню команд, журнал и список получателей — и, если профиль не только для чтения, запись от имени бота: отправка, правка, закрепление, «печатает», комментарии, ответы на кнопки, удаление, добавление и удаление участников, проверка чата по правилам (max_bot_write (command: "chats moderate")). max_bot_read (command: "status") показывает, за какой профиль говорит сервер, откуда токен, чей это бот и какие пишущие инструменты включены.

• permissions.bot: readonly у профиля бота — агент только читает, если нет более точных разрешений;
• чтобы разрешить только отправку и комментарии, задайте permissions.bot: readonly, затем permissions.bot.messages.send: allow; проверьте, нет ли других более точных разрешений;
• удаление сообщения или комментария по умолчанию имеет уровень ask: запрошенная запись допускается без серверной формы; deny и readonly запрещают её;
• действия, которые правила чата велят подтверждать, остаются планом для владельца;
• старые флаги подтверждения не меняют доступ.

--allow-send, --allow-delete и --allow-moderate ничего не решают: сервер с ними запускается и пишет об этом предупреждение.

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

С --md бот использует правила MAX: __жирный__, ++подчёркнутый++, ^^выделенный^^, ссылки, код, заголовки и цитаты. Преобразователь создаёт безопасный HTML с экранированным текстом и адресами; это внутреннее представление, аргумент --md остаётся Markdown.