Repository navigation
permissions
Use this page before you let an AI agent, a script or another person work with your Telegram
account through tg. It shows how to decide, for each profile, what may only be read, what asks
you first, and what may go ahead without a question. By the end you can make a profile read-only,
allow one action such as sending, and know which other checks still apply.
Words this page uses:
-
Profile: a named set of settings for one account or bot, such as
work(profiles and bots). -
Permission key: the name of a command or a group of commands, such as
messagesormessages.send. A longer key is more specific. -
Access level: what happens when that command runs:
deny,readonly,askorallow.
Start with reading, and allow changes only when you need them.
| Level | What happens |
|---|---|
deny |
The action is refused, including reading. |
readonly |
Reading works; changes are refused. |
ask |
A change asks in the terminal. |
allow |
The action can run without another question. |
A refusal tells you to check the requested action and settings. It does not mean your account connection is broken. Do not ask an assistant to remove a restriction just to finish a task.
tg work config set permissions.messages.send askReplace work with your profile. For a default that allows reading messages and refuses changes:
tg work config set permissions.messages readonlyMore specific keys win: permissions.messages.send ask still permits sending, with a question
in the terminal and without a server form over MCP. Set that key to readonly to refuse sends.
Check other exceptions with config show.
This controls messages. Other actions, such as reactions or chat administration, have their own permission keys. A complete read-only profile and every key are in what a profile may do.
Bot permissions and limits belong to the bot section. To ask before sends in the terminal:
tg support config set permissions.bot.messages.send ask --bot
tg support config set sends_per_hour 30 --botA recipient list limits which chats the profile may send to. An hourly send limit helps stop a loop. These checks remain active when a particular command is allowed. The commands to manage them are in the send guard.
Add --permission messages.send=deny to the server startup command to refuse sending for that
process. Saved settings stay the same. The flag only tightens: an override that would loosen the
profile's level is refused at startup. Over MCP, ask does not require a server form: the app controls
its own approvals and may allow a call without asking again. Use deny or readonly to refuse changes. Browser setup explains the full connection.
Over MCP, commands that change what a later run may do remain visible in discovery, marked unavailable by default: config set|unset, recipient lists,
chat rules, reply rules and consents, schedules, server install, skill install, model keys, media archive timers
and flood clear. One key opens them:
tg work config set permissions.mcp.authority allowFor a bot's server add --bot: tg support config set permissions.mcp.authority allow --bot.
deny is the default; allow and ask permit execution. Leave it at deny for a profile you give to an agent.
With it open, the agent can change its other settings and tighten its permissions, but since 0.113.0 it can never
loosen one: an agent, over MCP or in its own shell, may only lower a level (readonly to deny), and removing a
permission or changing --defaults accepts only deny. You loosen them in your own terminal. An agent cannot set
the key through config set, since that command is behind the key. See the MCP server.
Raw bot api <operation> calls bypass the send guard and the bot's recipient list. MCP lists them as unavailable
unless permissions.bot.api is allow or ask; its default is deny, and a broader permissions.bot: allow
does not enable them. Set this separate permission from a terminal:
tg support config set --bot permissions.bot.api allowSet it back to deny to make those tools unavailable again; they remain discoverable. An agent cannot change this key through MCP.
An assistant that can edit configuration files or run unrestricted terminal commands may be able to change these settings. Read security before giving that access. For nested permissions and exact command keys, see what a profile may do.
messages send --draft uses the separate drafts permission. Saving changes the Telegram draft
for that chat or topic, sends no message and journals no draft text. deny or readonly refuses
the save; ask requests confirmation in the CLI and follows the MCP client’s approval flow.
Over MCP, the messages send command must also be permitted by its command-level permission.
A drafts: allow setting does not lift messages.send: deny or readonly.