Skip to main content

Discord Setup Guide

This guide walks you through creating a Discord bot from scratch, configuring its permissions, and connecting it to Elftia so that your AI Agent works inside your Discord server.

Prerequisites​

  • A Discord account
  • A Discord server where you have admin permissions (or create a new test server)
  • Elftia installed with at least one LLM provider configured

Step 1: Create a Discord Application​

  1. Open the Discord Developer Portal
  2. Click New Application in the upper right
  3. Enter an application name (e.g., Elftia Bot) and click Create
  4. Click Bot in the left-hand menu
  5. Note the bot username shown on the page

Step 2: Obtain a Bot Token​

  1. On the Bot page, find the Token section
  2. Click Reset Token (if this is your first time, the token will be shown directly)
  3. Copy the token and store it securely

:::danger Security Warning A Bot Token is equivalent to the bot's password. Never share it publicly or commit it to a repository. If the token is leaked, reset it immediately in the Developer Portal. :::

Step 3: Configure Bot Permissions​

On the Bot page, find the Privileged Gateway Intents section and enable the following two options:

  • MESSAGE CONTENT INTENT — allows the bot to read message content (must be enabled)
  • SERVER MEMBERS INTENT — allows retrieving server member information (recommended)

Click Save Changes at the bottom of the page.

:::info Why Is the Message Content Intent Needed? Since 2022, Discord requires all bots to explicitly enable the Message Content Intent in order to read message content. Without it, the bot receives only empty messages. :::

  1. Click OAuth2 → URL Generator in the left-hand menu
  2. Check bot under SCOPES
  3. Check the following permissions under BOT PERMISSIONS:
PermissionDescription
Send MessagesSend messages
Read Message HistoryRead message history
View ChannelsView channels
Embed LinksSend embedded links
Attach FilesSend file attachments
Add ReactionsAdd emoji reactions
Use External EmojisUse external emojis
  1. Copy the GENERATED URL at the bottom of the page

Step 5: Invite the Bot to Your Server​

  1. Open the invite link copied in the previous step in a browser
  2. Select the target server (you must have Manage Server permission on that server)
  3. Review the permissions list
  4. Click Authorize and complete the CAPTCHA

After a successful invite, you will see the bot in the server's member list (shown as offline, since it hasn't connected yet).

Step 6: Configure in Elftia​

  1. Open Elftia and go to Settings → Channel
  2. Click Add Channel
  3. Select Discord (if the plugin is not installed, it will be downloaded from the Marketplace automatically)
  4. Fill in the configuration form:
FieldValue
Display nameA name for this instance (e.g., My Discord Bot)
Bot TokenPaste the token obtained in Step 2
  1. Click Test Connection to verify the token is valid
  2. Click Save to create the Channel instance

Step 7: Configure Trigger Rules​

After creating the instance, it is recommended to configure appropriate trigger rules:

ModeRecommended ForConfiguration
mentionMulti-user serversAgent replies only when @mentioned. Set mentionName to the bot's username
allDedicated/test serversAgent replies to all messages; suitable for personal use
keywordTopic-specific channelsSet a list of trigger keywords; case-insensitive
dm_onlyPublic serversAgent replies to direct messages only; completely silent in groups

Select the trigger mode and configure the corresponding parameters in the Channel settings.

Step 8: Start the Connection​

  1. Find the Discord instance you just created on the Channel page
  2. Click the Connect button (or enable Auto Connect)
  3. Wait for the status to change to Connected (green indicator)
  4. Send a message to the bot in Discord to test it

If using mention mode, remember to @mention the bot in your message:

@Elftia Bot Hello, please introduce yourself

Discord Platform Features​

FeatureSupport
Group chatSupported
Direct messages (DM)Supported
Attachments/file sendingSupported
Typing indicatorSupported
Emoji reactionsSupported
Threads/forumsPartially supported
Message length limit2,000 characters

When the Agent's reply exceeds 2,000 characters, the system automatically splits it into multiple messages. Splitting is done preferentially at newlines, then at spaces, and finally as a hard cut.

FAQ​

Bot Shows as Offline​

  • Check whether the Channel instance status in Elftia shows "Connected"
  • Confirm the Bot Token is correct
  • Confirm the Elftia app is running (Channel plugins run in the main process; the bot goes offline when the app is closed)

Bot Is Online but Not Responding​

  • Check that the trigger rule configuration is correct. If using mention mode, ensure mentionName matches the bot's actual username
  • Confirm that MESSAGE CONTENT INTENT is enabled in the Developer Portal
  • Check the Elftia logs for any records of security pipeline interceptions (RateLimiter, PromptGuardian, etc.)
  • Confirm the Agent has an LLM provider and model properly configured

Messages Are Truncated​

Discord's single-message limit is 2,000 characters. If the Agent's reply is too long, the system splits it and sends multiple messages. If a reply appears incomplete, check for follow-up messages.

Permission Errors (Missing Permissions)​

  • Confirm the bot has Send Messages and View Channel permissions in the target channel
  • Check whether any override rules in the server role settings restrict the bot's permissions
  • Regenerate the invite link in the Developer Portal and confirm all required permissions are checked

Multiple Discord Instances​

You can create multiple Discord Channel instances in Elftia, each using a different Bot Token and connecting to a different server. Each instance can have independent trigger rules and security policies.

Next Steps​