Skip to content

setup-discord.md

Latest commit

 

History

History
231 lines (153 loc) · 7.01 KB

setup-discord.md

File metadata and controls

231 lines (153 loc) · 7.01 KB

Discord Bot Setup Guide (OmegaBot)

This guide walks you through creating and configuring a Discord bot for OmegaBot, including required scopes, permissions, gateway intents, and common moderation pitfalls.

Table of Contents

Required OAuth Scopes

When generating the Discord invite URL, select these OAuth2 scopes:

  • bot
  • applications.commands

Do not use workspace/API scopes like guilds, guilds.channels.read, guilds.members.read, dm_channels.read, or presences.write for the server bot invite. OmegaBot uses the Discord bot gateway and slash-command install flow, not those OAuth user/API scopes.

If applications.commands is missing, slash commands may not install or update correctly. If you change scopes later, you must re-invite the bot.

Required Bot Permissions

For full functionality, especially admin/moderation commands, the bot role needs:

Core

  • View Channels
  • Send Messages
  • Read Message History
  • Embed Links
  • Use Slash Commands

Role Management

  • Manage Roles

This is required for /roles choose, /roles remove, and reaction-role assignment. The bot's highest role must also be above every role it needs to grant or remove.

Notion Audit Channel Permissions

Notion itself is configured in Notion Wiki Setup, but the optional Discord audit channel still depends on Discord permissions.

If BOT_ADMIN_AUDIT_CHANNEL_ID is set, OmegaBot sends lightweight audit messages for Notion admin actions such as /notion status, /notion templates, /notion create-page, and /notion add.

The bot must have these permissions in the configured audit channel:

  • View Channel
  • Send Messages

If the audit channel has channel-specific role overrides, check that the OmegaBot role is allowed there too. Server-level permissions are not enough when a channel override denies access. When these permissions are missing, the Notion command can still run, but the audit message will not be posted.

Moderation (Admin commands)

  • Moderate Members (timeouts)
  • Kick Members
  • Ban Members

⚠️ The bot’s role must be higher than the roles it is moderating.

Gateway Intents

OmegaBot always requests these standard gateway intents:

  • Guilds
    • Required for slash commands, guild context, channel lookups, and most bot operation
  • GuildMessages
    • Required for message-based features in servers, including message event handling
  • GuildMessageReactions
    • Required for reaction-driven features like starboard
  • DirectMessages
    • Required for DM handling

These do not need a special toggle in the Discord Developer Portal.

Enable these in Developer Portal → Bot → Privileged Gateway Intents only when you need the matching feature:

  • Server Members Intent (required for auto-role, welcome, etc.)
  • Message Content Intent (required only if you want message-based chat: DM the bot or @mention it to get an LLM reply; uses OPENAI_API_KEY or ANTHROPIC_API_KEY)

OmegaBot only requests these when the matching .env flags are enabled:

DISCORD_ENABLE_GUILD_MEMBERS_INTENT=true
DISCORD_ENABLE_MESSAGE_CONTENT_INTENT=true

If either flag is true, the same intent must also be enabled in the Discord Developer Portal.

Feature → Intent Mapping

  • Slash commands, config, admin, info, FAQ, GitHub, Notion, web-linked commands
    • Guilds
  • Starboard / reaction-based message features
    • GuildMessageReactions
  • Self-assignable roles with /roles
    • Guilds; no privileged member intent is required for slash-command role choice
  • DM support
    • DirectMessages
  • DM / @mention chat message handling
    • GuildMessages and DirectMessages
    • Message Content Intent also required if you want the bot to read message text
  • Welcome flow / auto-role on member join
    • GuildMembers

Welcome Messages

Welcome channel and message settings are stored in SQLite, not in .env or a text file. Configure them from Discord:

/config welcome set channel:#welcome
/config welcome set-message text:"Welcome {user} to {server}!"
/config welcome test

Supported message placeholders:

  • {user} - mention the joining user
  • {name} - display name
  • {username} - username
  • {server} - server name

If no custom message is set, OmegaBot uses a generic built-in welcome message. Use /config welcome set-message for server-specific links, rules, forms, or onboarding instructions.

If /config welcome test reports missing permissions, give the bot View Channel and Send Messages in the resolved welcome channel.

If /config welcome test works but real joins do not, check both sides of the member intent setup:

  • .env: DISCORD_ENABLE_GUILD_MEMBERS_INTENT=true
  • Developer Portal: Server Members Intent enabled

If you are unsure, the safest setup is:

  • Always allow the default non-privileged intents the bot requests
  • Turn on Server Members Intent only if you use welcome / auto-role
  • Turn on Message Content Intent only if you use DM or @mention chat

Why Admin Commands Might Fail

If /admin timeout, /admin kick, or /admin ban do nothing:

  • User is not an Administrator or approved moderator
  • Bot role is below target user
  • Bot lacks permission (Kick/Ban/Moderate)
  • Bot was not re-invited after permission changes

Moderator Roles (SQLite-backed)

OmegaBot supports moderator roles stored in SQLite.

Admins must configure these roles using the config command. Only users with:

  • Administrator permission, OR
  • A configured moderator role

can run moderation commands.

Self-assignable Roles

OmegaBot supports slash-command role selection with /roles.

Admins with Manage Roles can configure choices:

/roles enable role:@Announcements description:"Server updates and event pings"
/roles disable role:@Announcements

Members can then use:

/roles list
/roles choose role:@Announcements
/roles remove role:@Announcements

Setup notes:

  • The bot needs Manage Roles.
  • The bot's highest role must be above every self-assignable role.
  • Managed integration roles and @everyone cannot be self-assigned.
  • Disabling a role stops future self-assignment but does not remove it from members who already have it.

Re-inviting the Bot

You MUST re-invite the bot if you change:

  • Permissions
  • Scopes
  • Installation type

Old invites do not update permissions.

Helpful Links