# Bots (/en/docs/max/bot)

This page guides you through connecting your bot, checking chat access and preparing its first message. A bot is a separate messenger account that receives messages and performs configured actions: answering people, publishing announcements and showing buttons. You or your AI agent can use the command-line tool to act on behalf of your bot. This helps with customer enquiries, community updates and event registration. 

## First connection

[Create a bot on MAX for Business and get its token. Bots are available to verified organisations, sole traders and self-employed users after moderation.](https://business.max.ru/self)

[Install the tool](/llms.mdx/docs/installation/content.md)

1. Install the command-line tool if you have not installed it yet.
2. sales below names a separate bot profile. Run the first command and paste the token into the hidden terminal prompt. You can give the token to your agent, but it will remain in the conversation history. If possible, run this command yourself and enter the token in the terminal.
3. Run the second command to see the connected bot's name. Add it to your group or channel and grant the permissions your task requires.

```sh
max sales bot auth set
max sales bot me
```

Once the bot's name matches, continue with checking access and preparing the first message below.

## Check the connected bot

```text prompt
Use max CLI with my sales bot profile. Show the bot's name and check access to Club. Explain what it can do and which permissions are missing. Do not send or change anything.
```

Expect the bot's identity, selected group and access explanation. The name should match the bot you connected above.

[Choose a bot profile](/llms.mdx/docs/configuration/content.md)

## Prepare a message with buttons

```text prompt
Use max CLI with the sales bot profile. Prepare a Club announcement with Sign up and Learn more buttons. Show the text and proposed button actions. Do not send yet.
```

Check the text, links and each button's action. Publishing is a separate action; the bot needs access to the chosen chat.

[Bot API capabilities](/llms.mdx/docs/bot-api/content.md)

## Commands and instructions

A MAX bot is a separate account that can send messages, answer people and help manage a group. Use this page to connect one to `max`, find its chats, read and send on its behalf, restrict recipients and give your AI agent access to it.

Terms used below:

- **Bot** — a separate MAX account controlled by a program. `max sales bot` uses the official [MAX Bot API](https://dev.max.ru/docs-api). It has its own name, chats and token. `max …` without `bot` uses your personal account ([personal account guide](/llms.mdx/docs/max/usage/content.md)).
- **Token** — the bot's secret credential. Create the bot at [business.max.ru](https://business.max.ru/self). MAX issues bots to verified organisations, individual entrepreneurs and self-employed people, and moderates each bot.
- **Bot name** — the name you save its token under, such as `sales`, placed first in every command: `max sales bot …`.
- **Local archive** — what the bot read, sent or received, saved on this computer.

## What you can do [#what-you-can-do]

| Task | Command |
| --- | --- |
| Connect a bot and check which bot it is | `max <бот> bot auth set`, `max <бот> bot me` |
| Send, edit, delete and pin messages and files | `max <бот> bot messages send\|edit\|delete\|pin` |
| See new messages, button clicks and entries | `max <бот> bot watch` |
| Read and search what the bot saw | `max <бот> bot messages list`, `max <бот> bot search messages` |
| Download old chat history | `max <бот> bot messages sync` |
| Manage members and admins | `max <бот> bot chats members`, `max <бот> bot chats admins` |
| Bring order to the group according to your own rules | `max <бот> bot chats moderate` |
| Reply in the comments under channel posts | `max <бот> bot comments` |
| Respond to buttons, set command menus and webhooks | `max <бот> bot callbacks`, `commands`, `webhooks` |
| Limit chats where the bot can write | `max <бот> bot recipients` |
| Call any Bot API operation | `max <бот> bot api <операция>` |
| Transfer bot to AI agent | `max <бот> bot mcp serve` |

A complete list of commands and options is in the [command reference](/llms.mdx/docs/max/commands/content.md).

## Your first minute [#your-first-minute]

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

`auth set` asks MAX who the token belongs to before saving it. A typo cannot overwrite a working token.

## Finding a chat ID [#finding-a-chat-id]

MAX has no list of all chats a bot belongs to, so obtain IDs from what the bot has done or received.

- **A conversation with a person.** Address them as `user:<номер>`. The send response includes the destination chat ID in `chat_id`.
- **A group or channel.** Add the bot, then request the latest updates from MAX:

  ```sh
  max sales bot api get-updates --limit 10
  ```

  The chat ID is in `chat_id`. With no new updates, the command waits up to 30 seconds; `--poll-timeout 0` disables waiting. MAX does not deliver these updates a second time. This command does not work while the bot has a webhook.

Open the chat with `max sales bot chats show` and its ID. The bot then knows its title, which you can use in subsequent commands. `chats list` shows every chat the bot has already seen.

- Group and channel IDs are **negative**.
- A positive ID usually identifies a person. Use `user:<номер>` for a person; without `user:`, MAX treats the ID as a chat and returns “chat not found” (code `6`), and `max` explains the correct form.

## Multiple bots [#multiple-bots]

A bot is stored under a name you choose, used as the command's **first word**, just like a personal-account profile:

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

A profile name is required: the first word or `MAX_PROFILE` for the whole shell session. Without one, a bot command stops and lists the profiles.

## Token storage [#token-storage]

The token is stored in the system password store, under `bot:<имя>`, separately from the personal-account token. If no password store is available, it goes into a file with permissions `0600`, just like a personal token.

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

`MAX_BOT_TOKEN` takes precedence over stored credentials, which is useful in CI. `auth set` does not save a token from this variable.

## Messages [#messages]

Identify a chat by number and a person by `user:<номер>`; a previously seen chat also accepts its name. Always name the chat with the message, keeping `max` and `tg` commands consistent where message numbers are chat-specific. `max` does not change a message from another chat.

```sh
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` sends without a notification. Text is limited to 4,000 characters. The example ids `user:4815162342` and `mid.0000019a7f3c21de` are fictional; substitute yours. `--html` uses HTML; it cannot be combined with `--md`. Deletion asks for confirmation; `--allow-dangerous` confirms it. Pinning is silent by default; `--notify` informs members. The response contains the message and `operation_id`, its audit-entry id.

If the connection drops during a send, `max` does not retry automatically. It reports an unknown outcome (code `14`). Check the chat before sending again.

### Files [#files]

`--file` attaches a file from disk. Images, video and audio are detected by extension; other files are sent as documents. `--photo` sends an image as a photo, `--voice` sends Ogg Opus as a voice message, and `--as-file` sends video as a document. Known credential files, `max`'s own directories and the message store require `--allow-any-file`; ordinary hidden working directories are allowed. Text is optional when sending a file:

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

The file is uploaded to MAX before the message is sent. While MAX processes a video or large file, it may report “not ready”; `max` waits up to four times, about nine seconds in total. If upload fails, nothing is sent to the chat.

`uploads put` only uploads the file and prints an attachment object. Put this in the body's `attachments` for `bot api send-message`:

```sh
max sales bot uploads put report.pdf
```

## Chats [#chats]

MAX has no “all bot chats” endpoint. `chats list` therefore shows **chats this bot has seen on this computer**: those opened with `chats show`, sent to or read from. It is not a complete list.

```sh
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 "Команда продаж"    # вернуть бота может только админ чата
```

### Members and admins [#members-and-admins]

The bot must be a chat admin with permission for the action.

An administrator bot can add members through `bot chats members add`. [MAX documentation](https://dev.max.ru/docs-api) marks this method removed, but the MAX server executes it; the server determines availability.

First allow the bot to join groups. By default, MAX prevents bots from being added to group chats, whether through the app or `max personal chats members add` (response `participants.filter.out`). Enable this at [business.max.ru](https://business.max.ru/self): bot → **⋮ → Settings → Privacy** ([MAX documentation](https://dev.max.ru/docs/chatbots/bots-create/manage)). Then add it to the group and make it an admin in the MAX app. Group checks require permission to read messages; without it, MAX returns no group messages. You can also grant it with your own account: `max personal chats admins add "Поход" <номер бота> --can read,members,delete`.

```sh
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` returns up to 100 people. Fetch the next page with `--cursor` and the value of `page.next_cursor` (the `page.next` step names it too). Admin permissions in `--can` use the same names as `max personal chats admins add`: `read`, `members`, `admins`, `info`, `pin`, `link`, `edit`, `delete`. `read` grants access to group messages.

## Local storage [#local-storage]

`max` saves everything the bot reads, sends or receives on this computer. You can read and search this copy offline:

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

Search - by words, best matches on top; `--newest` - new on top. All the words are needed; `"фраза"`, `-слово`, `а OR б` and filters `from:`, `chat:`, `after:`, `before:`, `has:` work, and the typo is corrected. To strictly search the general archive, use [regular search](/llms.mdx/docs/max/search/content.md) with `in:bots`.

Download older chat history into the local store:

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

Repeated runs resume where the previous run stopped without refetching downloaded messages. Requests pause one second (`--pause`) and fetch 100 messages each (`--page-size`).

Normal commands still query MAX, which has the full chat history. A message the bot deletes, or that `watch` learns was deleted, is removed from local storage. If deletion happens while `watch` is stopped, the local copy does not know about it.

People are found in the same copy. Use an ID, `@username` or part of a name. If two people match, `max` shows both and asks for an ID.

```sh
max sales bot contacts show @ann                 # где писала, и её личный чат с ботом
max sales bot contacts show @ann --sync-first    # сначала перечитать личный чат у 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` shows only chats where every named person has posted, returning the latest 20 messages from each, oldest first. A “shared chat” here means the bot saw messages from each person, not that MAX's member list includes them.

**Each bot sees only its own local copy.** Reading another bot's copy requires both permission in configuration and an explicit request in the command:

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

`--all-bots` and `--bots` are supported by `search messages`, `contacts show` and `messages between`. Without `read_other_bots`, both refuse with code `5` and name the command that enables access. Through `max <имя> bot mcp serve`, the equivalent fields (`all_bots`, `bots`) are offered only when access is permitted.

## Updates [#updates]

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

`watch` saves incoming data before printing it: messages in local storage, button presses for `callbacks answer`, and joins and departures for group checks below. Without `--events`, only new messages are printed. With `--events`, every line identifies its event (`message`, `edit`, `delete`, `callback`, `joined`, `left`, `added`, `removed`, `started`, `other`). `--types` accepts MAX event names. The next run resumes where the previous one stopped. `watch` does not work while a webhook is configured.

Updates received by `watch` are no longer delivered to another reader using this bot's `get-updates`.

## Checking a chat against rules [#checking-a-chat-against-rules]

A bot can follow a group where he is an admin, according to the same rules as `max personal chats moderate` for a personal account (see [rules in groups that you manage](/llms.mdx/docs/max/groups/content.md#%D0%BF%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0)). Each bot has its own rules:

```sh
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              # только показать
```

The check examines messages since the previous check (the past day on its first run) and new members, then performs actions allowed by rules and consent. Differences from personal accounts:

- **Removed members are banned** and cannot return through the invite link. The link appears expired or invalid to them but keeps working for everyone else. An admin can add them back manually (`max personal chats members add`). Use `--no-block` to remove without banning. Bans work only in chats with an invite link.
- **The bot learns about joins only from `watch`.** MAX delivers each event to one reader, so checks use joins saved by `watch`. Without `watch`, the check examines only messages and reports that limitation.
- **Bots cannot see account ages.** The Bot API does not provide them, so the account-age rule does not apply.

The bot needs admin permissions to delete messages and remove members.

## Comments [#comments]

Comments appear under channel posts. Specify the post ID (`mid.…`) first, then the comment ID:

```sh
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
```

Comments use the same recipient allowlist as messages sent to that channel.

## Buttons [#buttons]

When someone presses a button under a bot message, the bot receives a callback ID (`callback_id`) and can answer it:

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

`--notification` displays a short notice only to the person who pressed the button; `--text` replaces the message containing it. The response goes to the chat where the button was pressed, but the callback ID does not reveal that chat, so the recipient allowlist does not apply.

## Command menu [#command-menu]

The menu is what someone sees when typing `/` in a bot chat.

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

`set` replaces the entire menu. Each entry is `имя=описание`; the description is optional.

## Webhooks [#webhooks]

A webhook is an address where MAX pushes everything the bot receives. While one is configured, the bot cannot receive updates through `get-updates`.

```sh
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
```

- The address must use HTTPS on port 443 with a certificate MAX trusts.
- A new address **does not replace** an old one: MAX sends every update to both. `set` therefore refuses if another address is configured. Remove it first, or use `--append` if you need both.
- `--secret-stdin` prompts without showing input or reads from a pipe. MAX sends this secret in `X-Max-Bot-Api-Secret`, letting your server identify MAX. The secret never appears in command arguments.

## Who the bot may contact [#who-the-bot-may-contact]

Bots follow the same profile settings as personal accounts:

- `permissions` sets levels for `bot.*` keys; `readonly` permits reading only;
- `allow` permits only named actions: sending `send`, editing `edit`, deleting `delete`, pinning `pin`, members and chat settings `groups`, bot commands `profile`, and receiving updates `read`. Actions without a corresponding word, such as webhooks, are forbidden when `allow` is set.

Each bot has its own list of chats it may write to:

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

Without a list, the bot may write anywhere. With one, sending to another chat refuses with code `7` and shows a command to add it.

Every bot write — send, edit, delete or pin — is logged:

```sh
max sales bot sends list
```

The journal records the chat, action type, outcome and text length, but no text. Recipient restrictions and journalling apply to **every** bot write, including `bot api`. A bot has no hourly send limit until one is set in configuration section `bot` (`max <имя> config set --bot sends_per_hour 200`; see [configuration](/llms.mdx/docs/max/configuration/content.md)).

## Any API operation [#any-api-operation]

`max sales bot api <операция>` exposes all Bot API operations, including those without convenient commands above. Commands are generated from the official API schema; new operations appear after a schema update. Operation help lists accepted fields:

```sh
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
```

Path and request parameters are flags, body is JSON in `--body`, `--body -` (from the pipe) or `--body-file`. `--body-file -` also reads stdin. The native parameter `timeout` is called `--poll-timeout`, and the global `--timeout` limits the entire command. The general option `--store-token <profile>` is not available for current MAX methods: they all reject it before performing the operation. Before sending, the body is checked against the schema, and the error message contains the field and what was expected in it, without the value itself. A list of all operations and which ones read and which ones write is [Bot API coverage](https://github.com/WireCatLabs/max-cli/blob/v0.111.0/docs/dev/bot-api-coverage.md).

## If the bot fails or makes a mistake [#if-the-bot-fails-or-makes-a-mistake]

The failure or error is explained in the error message, and the command exits with the code:

| Code | What happened | What to do |
|---|---|---|
| `4` | there is no bot token or MAX did not accept it | rerun `bot auth set` |
| `5` | read-only profile or action not allowed `allow` | change permissions only if you want to allow it |
| `6` | chat not found - for example, by name, which the bot has not yet seen, or a person without `user:` | indicate the chat number or `user:<номер>`, or open the chat via `bot chats show` |
| `7` | chat is not in the list of bot recipients | add chat via `bot recipients add` |
| `8` | exhausted `sends_per_hour` bot | wait or raise the limit |
| `14` | no response received: unknown whether MAX completed the write | check chat before repeating |

The [command reference](/llms.mdx/docs/max/commands/content.md) lists all codes. Bot `--trace` and `--record` log each Bot API request on stderr. File uploads report type, size and response code without URLs or filenames. Failed runs are saved in `max personal runs list` ([diagnostics](/llms.mdx/docs/max/diagnostics/content.md)).

## Certificate [#certificate]

The `platform-api2.max.ru` certificate is signed by a Russian Ministry of Digital Development root certificate absent from Node. In Node, `max` adds it to the trusted certificates for the whole process: after the first bot request, every TLS connection in that `max` invocation trusts it, not only Bot API requests. In Bun it applies only to Bot API requests. The system is unchanged. Bot requests identify themselves as `max-cli/<версия>`.

## Connecting a bot to an agent (MCP) [#connecting-a-bot-to-an-agent-mcp]

`max <имя> bot mcp serve` gives your AI agent access to a bot, just as `max personal mcp serve` exposes your personal account:

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

The agent can access what the bot profile permits: the bot, chats it has seen, messages, search, people, members and administrators, comments, command menus, the log and recipient list. If the profile is not read-only, it can also write as the bot: send, edit, pin, indicate typing, comment, answer buttons, delete, add or remove members, and check a chat against its rules (`max_bot_write` (`command: "chats moderate"`)). `max_bot_read` (`command: "status"`) shows which profile the server represents, where the token comes from, which bot it is and which write tools are enabled.

- `permissions.bot: readonly` makes the agent read only unless more specific permissions override it;
- to allow only sends and comments, set `permissions.bot: readonly`, then `permissions.bot.messages.send: allow`; check for other more specific permissions;
- Deleting a message or comment defaults to level `ask`: the requested write is allowed without a server confirmation form; `deny` and `readonly` forbid it.
- Actions that chat rules require you to confirm remain plans for the owner.

Every write uses the same command you would type, including bot recipient restrictions, `permissions` and the journal. Leaving chats, command menus, administrators and webhooks are available within profile permissions. Changing chat rules or recipients requires `permissions.mcp.authority: allow` or `ask`; the default is `deny`.

Raw `bot api` operations are listed in the catalogue, but run only with explicit `permissions.bot.api: allow` or `ask`. They remain disabled by default even with `permissions.bot: allow`. In max these calls retain permission and recipient checks, and writes are recorded in the journal. The agent cannot change `mcp` or `bot.api` through `config set`, or replace the whole `permissions` object. The owner enters the token; uploading a local file with `bot uploads put` is not offered.

With `--md`, the bot uses MAX rules: `__жирный__`, `++подчёркнутый++`, `^^выделенный^^`, links, code, headings and quotations. The formatter creates safe HTML with escaped text and addresses; this is an internal representation, and the --md argument remains Markdown.
