Permissions
What a bot may do in a server is decided exactly as it is for a person: by the permissions of its roles, adjusted by each channel's overwrites. There is nothing separate to learn for bots.
The model
- A member's base permissions are those of the server's
@everyonerole plus those of every role they hold, added together. - A server's owner has every permission, and so does anyone with Administrator.
- In a channel, the base is adjusted by that channel's overwrites: first the category's, then the channel's own, each in the order
@everyone, the member's roles, the member. A bit in an overwrite's deny takes a permission away; a bit in its allow gives it. - A member who cannot View channel can do nothing in that channel.
- Roles form a ladder (their position). A member can only act on members and roles that stand below their own highest role, and can only hand out permissions they hold themselves.
This is the model most chat platforms use, on purpose: it is the one people already know.
A bot's role
When a bot is added to a server, Moymo makes it a managed role named after your application, with exactly the permissions the person adding it chose and could give. The role sits just below that person's highest role. Only an install changes a managed role, and it is deleted with the application.
A server owner can still shape a bot like anyone: allow it in one channel and deny it in another with overwrites, put it in other roles, or take it out of the server.
The numbers
Every permission is one bit of a 64-bit integer, listed with its value in Permission bits. To ask for several, add their values: View channels (1) + Send messages (2) + Read message history (4) = 7.
The portal's Installation tab and OAuth2 URL generator have a checkbox for each permission and show the number.
Choosing permissions
Ask for what the bot needs and nothing more. People adding it see the list and can untick items; a bot that stops working because one was unticked is an expected case your code should survive (it gets a 403 from the API when it tries something it may not).
| If your bot... | It needs about |
|---|---|
| Reads and answers messages | View channels, Send messages, Read message history |
| Reacts | + Add reactions |
| Sends pictures or files | + Attach files |
| Posts game cards | + Embed games |
| Moderates (deletes messages, times members out) | + Manage messages, Moderate members |
| Manages roles | + Manage roles (and it can only manage roles below its own) |
Administrator
Administrator gives a bot every permission in every channel and ignores overwrites. Apps that ask for it have to explain why to publish, and server owners are right to be wary. Almost nothing needs it.
permissions in the install link
The permissions parameter of an install link is the sum of the permissions your bot asks for. It is a request, not a grant: the person adding the bot sees it as checkboxes and may untick any, and can only give what they hold themselves.