sometimespermission catalogue
these 67 stable permission keys are the v1 consent contract. numbers are reference labels, not bit positions or a JavaScript numeric bitmask.
permission evaluation
evaluate application status and token, installation ownership/status, revision, private eligibility, resource scope, current installer access, group exclusion, blocks, audience, operation grant, field grant and resource ownership on every read, write, event delivery and media subscription. all conditions must pass. absent grants deny. administrator expands to the approved catalogue even if individually disabled. existing administrator approvals remain limited to keys 2–66; published configurations with permission_catalogue 67 include interactive displays only after renewed consent. scope and ownership checks still apply.
combinations and dependencies
history, search, downloads and poll results never independently grant message content. actions on an existing message require the appropriate author read grant unless it is the installation’s own bot resource. creating a message-shaped sticker, GIF, attachment or poll uses its specific create/send permission without additionally requiring plain-text send; an optional caption uses the same grant. receiving/publishing media requires a joined bot session and the corresponding receive/publish grant. commands require commands plus bot.messages.send or bot.messages.ephemeral to reply. a writable operation’s receipt does not grant general read access.
dependency validation
publication rejects a required permission if every way to satisfy its prerequisites is disabled. for example, required downloads need an enabled author-read grant; required media receive needs one of the join permissions enabled. if an optional prerequisite is declined, the prompt explains which features will be unavailable. a required feature cannot rely only on a declined optional prerequisite: authorization must reject that selection until the dependency is selected. administrator satisfies all v1 grant prerequisites when selected.
master permission
grant names are exact API identifiers; display labels are shown during authorization.
scroll the table horizontally to see all columns.
| # | permission key and label | contract |
|---|---|---|
| 1 | administrator administrator | expands to the catalogue approved during authorization, including disabled permissions. existing approvals cover 2–66; renewed approvals can include 67. it never overrides scope, ownership, group exclusion, blocks or the prohibited operations. |
utility
grant names are exact API identifiers; display labels are shown during authorization.
scroll the table horizontally to see all columns.
| # | permission key and label | contract |
|---|---|---|
| 2 | messages.read_self read your messages | reads messages authored by the installer, including delegated messages. history and search require their additional grants. |
| 3 | messages.read_others read others messages | reads other authors in authorized chats, including bot authors. blocks and private-message audiences still filter results. |
| 4 | messages.history read past messages | allows messages created before this installation's history boundary; requires the applicable author read grant. |
| 5 | messages.search search for messages | searches only messages the installation can already read. older results also require messages.history. |
| 6 | scribbles.read read scribbles | reads persisted chat strokes, cuts and placements and live drawing previews. it does not grant message bodies or private profile artwork. |
| 7 | bot_dm message you 1-on-1 | creates or reopens the installer’s bot DM, with a blue bot tag. reading and sending in it still require their respective grants. |
| 8 | calls.audio.receive listen to calls | subscribes to separate audio tracks identified by participant; requires an authorized joined bot call session. |
| 9 | calls.video.receive receive video feeds | subscribes to participant camera tracks; does not include screen tracks or audio. |
| 10 | calls.screen.receive receive screen share feeds | subscribes to screen video; screen audio additionally requires calls.audio.receive. never permits publishing a screen. |
| 11 | attachments.download download sent attachments | downloads bytes only for messages currently readable by this installation, including the author/history/audience checks. |
| 12 | polls.results view poll results | reads counts, outcomes and public voter identities for readable polls. anonymous polls never disclose voters. |
| 13 | presence.read view online statuses | reads visible status for eligible users; respects their online-visibility preference and blocks. no device/session or last-seen telemetry. |
| 14 | typing.read view typing indicators | receives transient typing activity in authorized chats, respecting typing privacy. never includes draft text. |
| 15 | groups.members.read view group member lists | reads the roster and basic identity of members in authorized groups; full profiles require profile read grants. |
| 16 | friends.read view your friend list | reads the installer’s accepted friends with basic identity, not their private profiles or messages. |
| 17 | friends.requests.read view pending friend requests | reads the installer’s incoming and outgoing pending requests with basic identity. |
| 18 | profile.read_self view your profile | reads the installer’s public profile fields and artwork, excluding credentials, recovery contacts and private account data. |
| 19 | profile.read_others view others profiles | reads profiles the installer is eligible to view, subject to privacy and blocks. |
| 20 | profile.write modify your profile | writes all editable Profile settings: display name, about me, pronouns, avatar, banner, gradient, profile/nameplate artwork, nameplate colors, online-indicator color and announcement pack. never username, roles, badges or points. |
| 21 | settings.write modify your settings | reads and changes settings outside profile, testing, stickers and account. includes alerts, quiet hours, appearance, chat/media, call/audio preferences and privacy preferences; never exports, reports, credentials, sessions or permission grants. |
| 22 | chats.mute mute and unmute chats | reads and changes only the installer’s mute state in authorized chats; does not change anyone else’s notifications. |
| 23 | commands create and respond to commands | registers application commands and receives installer invocations. message responses require the appropriate bot send grant; command arguments are delivered without whole-chat read access. |
| 24 | notifications.send send you notifications | sends the installer an app notification, subject to their blocks, mute/alert preferences and quotas. cannot broadcast to other users. |
| 25 | stickers.manage create, view, and remove your stickers | manages the installer’s sticker library and consumes their normal storage/count quota. cannot delete another owner’s original asset. |
outbound bot actions
grant names are exact API identifiers; display labels are shown during authorization.
scroll the table horizontally to see all columns.
| # | permission key and label | contract |
|---|---|---|
| 26 | bot.messages.send send messages (as a bot) | creates ordinary messages with the application’s bot identity. |
| 27 | bot.messages.ephemeral send ephemeral messages (as a bot) | creates private messages for this installation’s user in an eligible chat; faint background and “(only visible to you)” label. |
| 28 | bot.messages.edit edit messages (as a bot) | edits messages created by this application through this installation; cannot edit other installations’ messages. |
| 29 | bot.messages.delete delete messages (as a bot) | deletes messages created by this application through this installation; no message moderation. |
| 30 | bot.scribbles.write create and edit scribbles (as a bot) | creates and updates strokes owned by this bot installation; deletion and erasure require bot.scribbles.erase. |
| 31 | bot.scribbles.erase erase scribbles (as a bot) | erases only strokes owned by this bot installation, by whole stroke or cut path. |
| 32 | bot.stickers.send send stickers (as a bot) | sends any sticker in the installer’s library or uploads/sends an application-owned sticker. the library’s sendable picker is included; library mutation is not. |
| 33 | bot.gifs.send send gifs (as a bot) | searches the supported GIF catalogue and sends a resolved GIF as the bot. |
| 34 | bot.placements.write drag and remove stickers and gifs (as a bot) | moves/removes only this bot installation’s sticker/GIF placements. |
| 35 | bot.attachments.send send attachments (as a bot) | uploads and sends supported files as the bot, with existing media validation and quotas. |
| 36 | bot.polls.create create polls (as a bot) | creates a poll with bot authorship. does not permit bot voting. |
| 37 | bot.polls.close close polls (as a bot) | closes only polls created by this bot installation. |
| 38 | bot.pins.write pin and unpin messages (as a bot) | pins eligible readable messages as the bot; removes only pins attributed to this installation. |
| 39 | bot.reactions.write add and remove reactions (as a bot) | adds/removes this bot installation’s reactions on eligible readable messages. |
| 40 | bot.games.start start games (as a bot) | creates a game session/invitation but never adds the bot as a player. without an active call it starts with zero players. |
| 41 | bot.groups.create create groups (as a bot) | creates a group attributed to the bot, with the installer as human owner. normal invitation eligibility applies. |
| 42 | bot.calls.start start calls (as a bot) | starts or obtains a call in an authorized chat. does not itself join, publish or receive media. |
| 43 | bot.calls.speak speak in calls (as a bot) | publishes a bot audio track in an authorized joined session; never uses the installer’s microphone. |
| 44 | bot.calls.join_with_user join calls you are in (as a bot) | joins only while the installer is a participant; leaves when the installer leaves unless join_all is also granted. |
| 45 | bot.calls.join_all join all calls (as a bot) | joins eligible calls in authorized chats even when the installer is absent; no discovery or admission outside scope. |
| 46 | bot.calls.video display a video feed (as a bot) | publishes a bot camera/video track in an authorized joined session; never enables the installer’s camera. |
| 47 | bot.calls.invite invite users to a call (as a bot) | proposes invitations using existing call voting, recipient acceptance, block and eligibility rules; cannot silently admit users. |
outbound user actions
grant names are exact API identifiers; display labels are shown during authorization.
scroll the table horizontally to see all columns.
| # | permission key and label | contract |
|---|---|---|
| 48 | user.messages.send send messages (as you) | sends as the installer with visible “via [bot]” attribution and a private activity record. |
| 49 | user.messages.edit edit messages (as you) | edits the installer’s ordinary messages, including ones they wrote manually, preserving bot edit attribution. |
| 50 | user.messages.delete delete messages (as you) | deletes only the installer’s messages; group ownership does not authorize deleting another person’s message. |
| 51 | user.scribbles.write create and edit scribbles (as you) | creates and edits the installer’s strokes, with delegated attribution. |
| 52 | user.scribbles.erase erase scribbles (as you) | erases only the installer’s strokes, by whole stroke or cut path. |
| 53 | user.stickers.send send stickers (as you) | sends only stickers uploaded by the installer and still in their library; adopted or bot-owned stickers are ineligible. |
| 54 | user.gifs.send send gifs (as you) | searches and sends supported catalogue GIFs with delegated attribution. |
| 55 | user.placements.write drag and remove stickers and gifs (as you) | moves/removes only the installer’s placements. |
| 56 | user.attachments.send send attachments (as you) | uploads and sends files as the installer, using their normal quotas. |
| 57 | user.polls.create create polls (as you) | creates a poll owned by the installer with delegated attribution. |
| 58 | user.polls.close close polls (as you) | closes only polls owned by the installer. |
| 59 | user.polls.vote vote in polls (as you) | casts, replaces or clears the installer’s vote; one user remains one voter. never accepts a bot actor. |
| 60 | user.pins.write pin and unpin messages (as you) | pins eligible readable messages and removes pins attributed to the installer. |
| 61 | user.reactions.write add and remove reactions (as you) | adds/removes only the installer’s reactions on eligible readable messages. |
| 62 | user.friends.request send friend requests (as you) | sends or cancels the installer’s own outgoing requests, subject to existing recipient preferences and blocks. |
| 63 | user.friends.respond accept and deny friend requests (as you) | accepts or denies incoming requests addressed to the installer; cannot manufacture a reciprocal acceptance. |
| 64 | user.blocks.write block and unblock users (as you) | changes the installer’s blocks; no ability to remove another user’s block. |
| 65 | user.groups.write modify groups you own (as you) | changes name, icon and member-invitation settings of an authorized group the installer still owns; no ownership transfer, group deletion or bot-exclusion management. |
| 66 | user.groups.members modify members in groups you own (as you) | invites/removes human members in authorized groups the installer still owns, under normal membership limits. cannot remove the owner or alter group bot exclusions. |
interactive displays
grant names are exact API identifiers; display labels are shown during authorization.
scroll the table horizontally to see all columns.
| # | permission key and label | contract |
|---|---|---|
| 67 | bot.messages.components create interactive displays | adds styled, interactive components to this installation’s bot messages. sending, editing, private replies, commands and audio still require their respective permissions. clicks disclose only the acting user and submitted values. |
privacy and identity boundaries
basic identities attached to an authorized resource include only stable ID, display name, bot/user kind and avatar thumbnail. they do not grant full profile, presence, friends, contact details or message access. username is read-only wherever normally public; it is never writable. profile artwork asset reads require profile permission, and chat attachment bytes require attachments.download. message bodies, search snippets, embeds, captions, quote previews, polls, notifications and replay all use the same visibility rules. a single installer cannot grant access to someone else’s private DM or account.