Discord Bot Setup Guide

🤖 Discord Bot Setup Guide

This guide covers how to create and configure a Discord bot to connect with AionUi, enabling AI assistant interactions through Discord.

English | 简体中文

🎯 Overview

AionUi connects to Discord over the Gateway (a WebSocket connection), so you don't need a public URL, reverse proxy, or webhook endpoint — everything runs from your local AionUi. This guide will walk you through:

1. Creating a Discord app and generating a bot token
2. Inviting the bot to your server
3. Configuring credentials in AionUi
4. Authorizing users and starting conversations

---

📋 Prerequisites

• A Discord server where you have Manage Server permission (create a free personal server if you don't have one — it's instant)
• AionUi application installed (with the Discord channel)
• Basic understanding of Discord apps

💡 Tip: Discord uses a single Bot Token — there's no second token to manage. The one thing people miss is the Message Content Intent in Step 3; without it your bot connects but can't read message text.

---

🚀 Step-by-Step Setup

Step 1: Create the Discord App

1. Create a new application

   • Go to Discord Developer Portal
   • Click New Application
   • Name it (e.g. AionUi) and click Create

   

---

Step 2: Get the Bot Token

1. Open the Bot page

   • In the left sidebar, click Bot

2. Reset and copy the token

   • Click Reset Token → confirm → Copy
   • ⚠️ Important: This is the only token you need — it's the Bot Token in the AionUi form. Store it now; you can't view it again after leaving the page.

   

---

Step 3: Enable the Message Content Intent

⚠️ This is the step people miss. Without it the bot connects but receives empty message text and never replies.

1. Open Privileged Gateway Intents

   • Still on the Bot page, scroll to Privileged Gateway Intents

2. Turn on Message Content Intent

   • Toggle MESSAGE CONTENT INTENT on and save

   

---

Step 4: Invite the Bot to Your Server

1. Open the URL Generator

   • In the left sidebar, go to OAuth2 → URL Generator

2. Select scopes and permissions

   • Under Scopes, check bot
   • Under Bot Permissions, check:

   Permission	Purpose
   Send Messages	Send and edit replies
   Read Message History	Read messages in a channel
   View Channels	See the channels it's in

3. Authorize

   • Copy the generated URL at the bottom → open it in a browser → pick your server → Authorize

   1	2	3	4

---

Step 5: Configure AionUi

1. Open the Discord channel

   • Launch AionUi and go to Settings → Remote → Channels
   • Find the Discord card and expand it

2. Enter the Bot Token

   • Bot Token: paste the token from Step 2
   • Click Test — on success you'll see Connected! Bot: @your-bot and the channel auto-enables (the Gateway connection opens)

3. Configure assistant and model

   • Select the Assistant for Discord conversations
   • Choose the default model if applicable

   

---

Step 6: Authorize Users and Chat

1. Message the bot in Discord

   • DM the bot (you must share a server with it) or @mention it in a channel
   • The first message triggers a pairing request

   

2. Approve the pairing request

   • In AionUi, go back to Settings → Remote → Channels → Discord
   • Find the Pending Pairings section and click Approve to authorize the user

   

3. Start chatting

   • Send another message — the assistant replies, streaming and updating in place

   discord	aionui

---

🔧 Troubleshooting

Bot Doesn't Reply

Problem: The bot connects but never responds

• Solution:
  • Confirm MESSAGE CONTENT INTENT is enabled (Step 3) — this is the most common cause
  • Confirm the bot was invited with the Step 4 permissions and the channel is enabled + connected in AionUi
  • Confirm the user has been approved in AionUi (Pending Pairings → Approve)

Can't DM the Bot

Problem: Direct messages to the bot don't trigger anything

• Solution:
  • You must share a server with the bot — invite it to a server first (Step 4), then DM it
  • Only DMs and @mentions are handled; plain channel messages without a mention are ignored by design

Connection / Token Issues

Problem: Test fails / "invalid token"

• Solution:
  • Re-check the Bot Token — if in doubt, Reset Token again (Step 2) and paste the new value
  • The Bot Token is the only credential; there is no second token for Discord

Discord Card Not Shown

Problem: There's no Discord card under Channels

• Solution:
  • Update to an AionUi build that includes the Discord channel

---

📚 Additional Resources

• Behavior: responds to DMs and @mentions only (plain channel messages are ignored). Replies stream via in-place edits; an @mention inside a thread replies in that thread.
• Not supported yet: interactive buttons / embeds, file / attachment upload, streaming replies inside a thread.
• Discord Developer Portal
• Discord Gateway
• AionUi Configuration Guides
• AionUi FAQ

---

🔗 Quick Links

• 🚀 Getting Started
• ⚙️ LLM Configuration
• 💬 Slack Bot Setup Guide
• 🤖 DingTalk Bot Setup Guide
• 💻 WebUI Configuration
• ❓ FAQ

---

Need help? Check the FAQ or open an issue on GitHub.