For the complete documentation index, see llms.txt. This page is also available as Markdown.

Creating a Discord bot account

Create the Discord application, turn on the two privileged intents, and copy the token your bot logs in with.

Both a custom bot and a self-hosted bot log in with your own Discord application. You create it once, in the Discord Developer Portal.

Create the application

1

Open the Developer Portal

Open discord.com/developers/applications?new_application=true and sign in with the Discord account that should own the bot. That link opens the New Application dialog for you; you can also click New Application at the top right of the portal.

2

Create the application

Give it a name, accept the developer terms and click Create. The name you type here is the name your bot shows in Discord, so use the one you actually want, and use a dedicated application instead of reusing a bot you already run.

The New Application dialog in the Discord Developer Portal
Name the application and click Create

Upload the avatar and banner here too; this is the only place that changes the bot's Discord profile.

Turn on the privileged intents

Open the Bot tab and scroll to Privileged Gateway Intents. Member Counter needs two of the three. Set them as below and click Save Changes.

Intent
Set it to
Why

Presence Intent

On

Tells Online, Idle and Do Not Disturb apart, and powers the "playing a game" member filter

Server Members Intent

On

Counts members exactly and powers the role and account-type filters

Message Content Intent

Off

Member Counter never reads message content

The Privileged Gateway Intents section with Presence and Server Members enabled
Presence Intent and Server Members Intent on, Message Content Intent off

Copy the token

Still in the Bot tab, click Reset Token and confirm. Discord shows the token once. Copy it and keep it somewhere safe.

The Reset Token button in the Bot tab
The Reset Token button on the Bot tab. The new token is shown only once, right after you confirm

Resetting the token invalidates the old one, so a bot already running on it stops working until you paste the new one. Where the token goes next:

OAuth2 credentials

Self-hosting only: a self-hosted bot also needs the OAuth2 client id, secret and redirect URL from the same application. See Configuration.

The OAuth2 tab showing the client id, the reset secret button and the redirects list
The OAuth2 tab of the same application
Technical details
  • Every bot requests Guilds, GuildEmojisAndStickers and GuildModeration, plus GuildMembers, GuildPresences and GuildVoiceStates for a privileged premium bot. MessageContent is never requested. The list is in packages/common/src/bot/botIntents.ts.

  • Before deploying anything, a custom bot start logs in for real with the privileged intents. A failure throws BOT_START_PRE_CHECK_FAILED, shown as Bot failed to start (check the token or intents); no saved token throws BOT_TOKEN_MISSING, The bot must have at least a token.

  • A self-hosted bot with an intent off exits with Discord's disallowed-intents error instead of starting. Past 100 servers Discord only keeps granting the intents through bot verification; below that the toggles are enough.

  • The dashboard never asks for a client id: it calls Discord's /users/@me with the saved bot token, which is why the profile row fills in as soon as you paste a valid one. With no usable token it shows the bot as Unknown Bot.

  • The application id is base64-decoded from the token's first segment, for the sidebar list and for the DISCORD_CLIENT_ID the deployed pod gets.

  • Variables a self-hoster fills from this application: DISCORD_BOT_INSTANCE_TOKEN, DISCORD_CLIENT_ID (the application id), DISCORD_CLIENT_SECRET, DISCORD_OAUTH2_REDIRECT_URI, mandatory and with no default (http://localhost:3000/api/auth/callback in .env.example; set it to your WEBSITE_URL followed by /api/auth/callback yourself), and MAIN_DISCORD_CLIENT_ID.

  • MAIN_DISCORD_CLIENT_ID ships as 478567255198662656, the official bot, so /invite on a self-hosted bot links the official bot until you put your own client id there.

  • The redirect has to match character for character, including the scheme, the port and the absence of a trailing slash. A mismatch gives Discord's "Invalid OAuth2 redirect_uri" error when someone signs in to your dashboard.

Last updated