Permissions
Every SDK operation is tied to a permission. The user sees the list of permissions and your reasons at install time and can grant them partially.
What the host does
Section titled “What the host does”- Checks that each requested permission is known to the host and not listed twice.
- Shows the user the list with each
reasonand a risk level (Low,Medium,High). The level is fixed per permission (the column in the permission list); onlymessages.readdepends onscope:all(or noscope) is High,selectedis Medium. Rows are sorted riskiest first. - On every call, checks the operation against the granted permissions. No permission — the answer is
denied; in Python this is thefreshgram.Deniedexception.
Risks the app warns about
Section titled “Risks the app warns about”The host builds risk notes from the set of permissions that are currently switched on in the dialog. Each note below appears when its condition holds (the texts are the English source strings):
| Note | Shown when |
|---|---|
| can read your data and send it to the internet | any reading permission is on and a network permission (net.https, net.ws, net.tcp, net.udp) is on. Reading permissions: messages.read, messages.read_deleted, messages.history, chats.list, chat.info, account.info, contacts.list, composer.draft, media.read, folders.list, settings.read, stars.balance, users.info, chats.active, chats.activity, users.presence, app.activity, translate.provide, ai.provide, stories.read, calls.activity |
| can contact any public server | a network permission (as above) is on |
| can open its own TCP or UDP connections | net.tcp or net.udp |
| can read deleted messages kept on this device | messages.read_deleted |
| can send messages in your name | messages.send |
| can change what you send | messages.transform_outgoing |
| can change or hide the messages you receive | messages.transform_incoming |
| can talk to programs on this computer | net.local |
| can ban and unban chat members | chats.moderate |
| can edit or delete messages you sent | messages.edit or messages.delete (one shared note) |
| keeps running in the background | background |
| can use the clipboard | clipboard |
| can read and save files you pick | fs.user_selected |
| receives the text you ask it to rewrite | ai.provide |
| can use the files in the folder you chose | fs.folder |
| can send the files of that folder to the internet | fs.folder and a network permission |
| can exchange data with other plugins that accept it | plugins.message |
net.local does not count as a network permission for the first two notes (it has its own note).
User action
Section titled “User action”Some operations work only within a limited window after a user action, such as a menu click:
clipboard.read/write— within 10 seconds;chats.ban/unban— within 10 seconds;- turning ghost mode off (
ghost.set(False)) — right after a user action. files.pickandfiles.save(fs.user_selected) — within 10 seconds;ui.open_settings(ui.settings_page) — within 10 seconds, and it uses up the action: a second call needs a new click.
Call such operations from a click handler, not from a timer.
The window starts at any event the user causes and the app delivers to the plugin (a menu or badge click, a /command, or an interaction with a dialog, window, toast or settings page) and lasts 10 seconds; closing a dialog, window or toast does not start it. A call outside the window is answered with denied (“only right after a user action”). Opening a dialog without a recent action is also rate-limited.
Message scope
Section titled “Message scope”For messages.read you can set scope: selected (selected chats only) or all. Chat-bound events follow the selected scope and never come from secret chats.
If you choose selected, the user must pick the chats in the install dialog (“all chats” is disabled for such a request and picking none is refused). If a grant ever reaches the host with selected but without a chat selection, the permission is silently dropped (no error): calls then fail with denied as for any permission the user did not grant.
Updates
Section titled “Updates”When a new version is installed the dialog shows the whole permission list; new items are marked “New” and pre-selected. Raising messages.read scope to all or fs.folder mode to write also counts as new. See Publishing and updates.