Concepts

A bot is a member that cannot sign in, with exactly the access an admin gave it. This page explains the pieces every bot touches.

Who may create bots

Only the Owner and members with Manage bots, which only the Owner can grant. The usual hierarchy applies: you can only change a bot whose highest role is below yours, give it roles below your own highest role, and no permission you do not hold yourself. A role with Administrator or any admin-area permission can only be given to a bot by the Owner.

What a bot is

A member-like account plus a record with its name, avatar, allowed intents and tokens. Its messages show its name and avatar with a BOT tag. It is listed in the member list, can be mentioned, and is online while it has a gateway connection. It cannot sign in, cannot hold the Owner role, and no bot endpoint manages roles, bots, webhooks or members, whatever roles it holds.

Two roles of its own

  • The Bot role. One built-in, managed role that every bot holds from its creation. It cannot be removed from a bot, given to a person, deleted or renamed. Its colour, position and hoist (its own group in the member list, on by default) are editable.
  • The bot's own role. A managed role named after the bot, held by that bot only, renamed and deleted with it. Its permissions are editable, within the rules below.

Both start empty. There is deliberately no default: a sensible minimum differs per community, and an empty default keeps the rule "nothing without a grant".

Permissions

A bot's permissions come from the same engine as a member's: its roles, and the channel and category overwrites for those roles. Unlike a member, a bot does not inherit @everyone: neither its base permissions nor its overwrites. A private channel stays invisible to a bot unless one of its roles is allowed there.

One rule covers every way a bot could gain access, checked on the outcome in the same transaction as every change: a change by anyone but the Owner can add nothing to a bot that is elevated (Administrator or any admin-area permission) or that the person making the change does not hold there themselves. Managing a bot afterwards (tokens, edits) also needs at least the bot's rights.

Voice is out of scope: bots cannot join Talks.

Tokens

  • Up to 10 active tokens per bot, mnb_…, 256 random bits. The secret is shown once; only a SHA-256 hash is stored.
  • Optional expiry. Each token shows its last characters, its state and when it was last used.
  • Regenerate issues a new token and revokes the old one at once. Revoking, or disabling or deleting the bot, takes effect immediately, also for open gateway connections.
  • A token remembers who issued it. Every use re-checks, at most every 30 seconds, that this person is still active and still qualifies. When they are demoted, disabled or banned, or the bot gains a permission they lack, their tokens stop working.

Intents

Intents choose which classes of events the gateway sends. The admin sets the intents a bot is allowed to ask for; asking for more closes the connection with 4014.

IntentBitEvents
GUILDS1CHANNELS_UPDATE: the channel layout or the bot's access changed
GUILD_MEMBERS2GUILD_MEMBER_ADD for new members who share a channel with the bot
GUILD_MESSAGES512MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE
GUILD_MESSAGE_REACTIONS1024MESSAGE_REACTIONS_UPDATE

Which channels an event comes from is not an intent. Every event is checked, at the moment it is sent, against what the bot may view, so a bot never receives an event from a channel it cannot see, and loses a channel's events the moment its access ends. Interactions need no intent.

Presence

A bot is online while it has at least one live gateway connection. It sets its own status (online, idle, do not disturb, invisible) and one activity with gateway op 3; see the gateway. Bots are not counted in the online total and are never reached by @here.

A bot written by someone else describes itself in a manifest: a JSON document in its README.

{
  "manifest_version": 1,
  "name": "Mnemo",
  "description": "Answers questions and keeps notes.",
  "homepage": "https://github.com/mnema-xyz/talk-mnemo-bot",
  "intents": ["GUILDS", "GUILD_MESSAGES"],
  "permissions": ["view_channel", "send_messages", "add_reactions"],
  "commands": [
    {"name": "ask", "description": "Ask Mnemo something",
     "options": [{"name": "question", "description": "Your question", "type": 3, "required": true}]}
  ]
}
FieldRule
manifest_versionrequired, 1
namerequired, 1 to 24 characters
descriptionoptional, up to 200 characters
homepageoptional https URL, up to 512 characters
avataroptional data: URL of a PNG, JPEG or WebP image of at most 256 KB
intentsoptional: GUILDS, GUILD_MEMBERS, GUILD_MESSAGES, GUILD_MESSAGE_REACTIONS
permissionsoptional, channel permissions only: view_channel, send_messages, attach_files, add_reactions, manage_messages, mention_everyone
commandsoptional, at most 50, each as for PUT /api/bot/v1/commands

Unknown fields are ignored, so a newer manifest still installs on an older server.

The add link carries the manifest in the URL fragment, which the browser never sends to the server:

https://<your server>/admin/bots/add#manifest=<the manifest as base64url>

Both SDKs build it (addBotLink(serverUrl, manifest) in TypeScript, mnema.AddBotLink in Go). The admin who opens it sees what the bot asks for, picks the channels it may work in (none ticked by default), and nothing is created until Add bot. The requested permissions become allow overwrites of the bot's own role in the ticked channels, never anything server-wide or elevated. The token is shown once.

Something wrong on this page? Tell us.