Telegram and MAX Bot API for your AI agent
Run a Telegram or MAX bot through your AI agent or the terminal with the Bot API: send messages and files, handle events and help with group tasks.
Use a messenger bot through your agent or the terminal to answer requests, publish updates or help with a group. Connect it and check its access before your first task. A bot has its own account, name and permissions. It does not gain access to your private conversations,
and commands without bot still use your personal account.
Bot API is the official way to control a Telegram or MAX bot from a program:
Telegram Bot API and MAX Bot API.
The tg and max command-line tools cover all of it: all 185 Telegram methods and all 33 MAX
operations. They also add what the official API does not have: a searchable copy of the bot's
messages, group moderation by your rules and limits on where the bot may write. Ask your agent to
use the bot, or run commands yourself.
On this page:
- What a bot can do
- What the CLI adds to the Bot API
- Differences between Telegram and MAX
- Connect your bot
- Give your agent a task
- Send a message yourself
- Before you automate
- When you need the full API
What a bot can do
| Task | Telegram | MAX |
|---|---|---|
| Send, reply to, edit, delete and pin messages, with Markdown or HTML | Yes | Yes |
| Send files, photos and voice messages | Yes | Yes |
| See new messages, edits, button presses, joins and departures | Yes | Yes, and deleted messages |
| Answer buttons, set the command menu, set a webhook | Yes | Yes |
| Make and remove admins with the rights you choose; remove or ban members | Yes | Yes |
| List a group's members | No: the Telegram Bot API cannot | Yes, 100 per page |
| Add members to a group | No: the Telegram Bot API cannot | Yes, while the MAX server allows it |
| Reply in comments under channel posts | No | Yes |
| Check a group against your rules and remove what breaks them | Yes | Yes |
| Read and search what the bot sent and received | Yes | Yes |
| Import older messages | Channels and supergroups | Yes |
A bot sees only what the messenger shows it, and changes in a group need admin rights there. Continuous auto-replies need a program that keeps running and handles events; a single command does not start one.
What the CLI adds to the Bot API
- A history you can search. The Telegram Bot API has no call to read old messages. The CLI keeps what the bot sends and receives on your computer, so you and your agent can list, search and look up who wrote what. It can also import older messages.
- Group moderation by your rules. Save a group's rules once. The bot checks new messages against them, shows what it would do, and acts only as the rules allow.
- Limits on writing. Each bot has a list of chats it may write to, an optional hourly limit and a journal of every write. The journal never stores the message text. These limits apply to the full API too.
- A protected token. The token is kept in your system keyring and is never printed, not even in error messages.
- Several bots. Each bot has its own profile name, the first word of the command:
tg sales bot …,tg support bot …. - Results a program can use.
--jsongives clean data and clear exit codes. If the connection breaks during a send, the CLI does not send again: it reports that the result is unknown, so you check the chat first. - A connection for your agent.
tg <bot> bot mcp serveandmax <bot> bot mcp servegive the bot to an agent app with only the permissions you set.
Differences between Telegram and MAX
- Telegram: a person must start the bot before it can write to them. In a group, a bot that is not an admin sees only commands and replies to it, unless privacy mode is turned off in BotFather.
- MAX: only verified organisations, individual entrepreneurs and registered self-employed people can create a bot, and every bot goes through moderation. A bot can join groups only after you allow it in the bot's privacy settings at business.max.ru.
All commands and limits: Telegram bot guide · MAX bot guide.
Connect your bot
First create a bot: in Telegram through BotFather, in MAX at business.max.ru. The Telegram guide and MAX guide explain each step. Then save its token at a hidden terminal prompt:
tg support bot auth set
max support bot auth setsupport is the bot profile name you choose. Run the command for your messenger. Prefer entering the token yourself at the hidden terminal input above. You can choose to share it with your agent, but then it becomes part of that agent chat’s history. Keep it out of command arguments and screenshots. Check which bot is connected:
tg support bot me
max support bot meExpect your bot's name and identifier. Then add it to the target group or channel, or start a private conversation with it. Telegram users must start the bot before it can message them.
Give your agent a task
This example uses the support Telegram bot profile. For MAX, replace “Use tg CLI” with “Use max CLI” and name its bot profile. In a browser chat, name the connected bot tool.
Use tg CLI with the connected support bot: check its identity and the events it can access. Suggest how to prepare a report for my group. Show the chosen chat and draft the message. Don't send anything yet.The agent should show the bot, selected chat and draft. Review the text and recipient, then authorise sending separately. Finding a chat and sending: Telegram or MAX.
Send a message yourself
tg support bot messages send "Team" "The report is ready"
max support bot messages send "Team" "The report is ready"Replace the chat and text with what you intend to send. This is a real message from the bot. The bot can also send files, reply to a message and manage chats when it has the required rights. Do not give it administrator rights for actions that do not need them.
Before you automate
Give the bot profile only the permissions it needs and decide which recipients it may contact. For important messages, ask to review the text first. Webhooks and update polling feed other applications; changing them can interrupt an existing integration.
When you need the full API
Common tasks have convenient commands such as bot messages send. Less common operations can use the whole native Bot API of Telegram and MAX.
tg support bot api --help
max support bot api --help
tg support bot api get-me --json
max support bot api get-my-info --jsonEach method's help explains its fields. Names and inputs follow the provider API. The full API is available through the command line; MCP offers separate tools for common tasks. An agent with terminal access can use both interfaces.
Telegram bot setup and tasks · MAX bot setup and tasks. Official methods: Telegram and MAX.
Group and channel analytics
A recipe for a full report on a public Telegram channel: reach, what readers share, themes, posting rhythm, polls and comments, with an example report, and how a group admin follows activity.
Configuration
Find the settings file, view and change a value, choose a profile or bot, and set what the tool may do.