installation and consent

authorization prompt

show bot name, blue bot label, developer identity, description, privacy/support links, install policy and requested permissions grouped exactly as the catalogue. disabled permissions are omitted. required permissions are checked and locked; optional permissions start on and can be switched off. explain account-wide access to present and future eligible chats. the final authorize button summarizes the selected scope. cancel creates nothing. show administrator as an explicit all-permissions choice with an expandable complete list; when selected, granular switches cannot imply exclusions.

account and chat scopes

account means all current and future chats the installer can access, subject to group bot exclusions and privacy rules. chat means exactly one selected existing DM or group. either lets the installer choose. a single-chat installation can still use explicitly granted account capabilities such as profile, settings, friends and stickers. those account effects must be identified separately in the prompt. bot_dm adds a dedicated private bot DM as an explicit extra surface even for a single-chat installation; it never expands access to other chats.

group-owner control

any current group member can install a bot for their own use. the group’s bot roster discloses every application with active access and which members authorized it; private account grants are not shown to peers. a human group owner can exclude an application from the group. exclusion immediately denies every installation of that application in the group, including account-wide installations, disconnects its call streams and cancels queued work there. the exclusion persists until the owner explicitly removes it. members cannot evade it by reinstalling; the bot API cannot alter this exclusion.

multiple installations

allow one active installation per application, installer and scope target. installing the same target opens its management screen. an account-wide installation and distinct chat installations may coexist, but grants never combine: every operation names exactly one installation. command routing uses the installer’s active chat-specific installation if present, otherwise their account-wide installation. event fanout can produce one authorized event per installation, identified separately. developers must deduplicate intended shared effects rather than union permissions.

configuration changes and permission renewal

a published revision never silently adds privileges. existing installations keep their approved permission configuration and command snapshot until the user accepts a newer revision. the developer must support those old grants or return a clear upgrade-needed response; new optional permissions remain unavailable until consent. scope expansion requires a new prompt. new code deployed by the developer may run immediately but still has only existing grants. users may revoke optional grants immediately; disabling a required grant pauses the installation until restored or reauthorized. uninstall, private eligibility, platform suspension and group exclusion always take effect immediately, regardless of revision pinning.

history boundary

each author-read grant records an authorized_since timestamp when it is first enabled. without messages.history, reads and searches include only messages created at or after that grant’s timestamp. enabling a read grant later does not backfill earlier messages; edits to old messages do not turn them into new messages. scope additions likewise establish a new boundary for each newly authorized chat. loss and later regrant reset the corresponding boundary. bot-authored content has a separate narrow own-resource readback described in the resource chapters.

user management routes

these same-origin routes require the human session and CSRF protection. they cannot be called with a bot token. consent POST includes a one-use prompt token bound to user, application, published revision, scope choices and expiry; tokens expire in 10 minutes and are consumed atomically. update prompts use the same flow. group exclusion writes require current owner status at commit.

scroll the table horizontally to see all columns.