Use with your agent

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:

  1. What a bot can do
  2. What the CLI adds to the Bot API
  3. Differences between Telegram and MAX
  4. Connect your bot
  5. Give your agent a task
  6. Send a message yourself
  7. Before you automate
  8. When you need the full API

What a bot can do

TaskTelegramMAX
Send, reply to, edit, delete and pin messages, with Markdown or HTMLYesYes
Send files, photos and voice messagesYesYes
See new messages, edits, button presses, joins and departuresYesYes, and deleted messages
Answer buttons, set the command menu, set a webhookYesYes
Make and remove admins with the rights you choose; remove or ban membersYesYes
List a group's membersNo: the Telegram Bot API cannotYes, 100 per page
Add members to a groupNo: the Telegram Bot API cannotYes, while the MAX server allows it
Reply in comments under channel postsNoYes
Check a group against your rules and remove what breaks themYesYes
Read and search what the bot sent and receivedYesYes
Import older messagesChannels and supergroupsYes

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. --json gives 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 serve and max <bot> bot mcp serve give 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 set

support 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 me

Expect 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.

Request
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 --json

Each 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.