Prerequisites
- A Discord account
- Server admin permissions (to add bot)
- OrcBot installed and configured
- Node.js 18+ installed
Create Discord Bot
1
Open Discord Developer Portal
Go to Discord Developer Portal
2
Create New Application
Click “New Application”Enter a name (e.g., “OrcBot”)
3
Create Bot User
- Navigate to the “Bot” tab
- Click “Add Bot”
- Confirm “Yes, do it!”
4
Configure Bot Settings
Enable these Privileged Gateway Intents:
- ☑ SERVER MEMBERS INTENT
- ☑ MESSAGE CONTENT INTENT
- ☑ PRESENCE INTENT (optional)
5
Copy Bot Token
Under the “Bot” tab, click “Reset Token” and copy the new tokenSave this token securely - you won’t be able to see it again!
6
Generate Invite Link
- Go to “OAuth2” → “URL Generator”
- Select scopes:
botapplications.commands(for slash commands)
- Select bot permissions:
- Send Messages
- Send Messages in Threads
- Embed Links
- Attach Files
- Read Message History
- Add Reactions
- Use Slash Commands
- Copy the generated URL
7
Add Bot to Server
- Open the invite URL in your browser
- Select your server
- Click “Authorize”
Configure OrcBot
Using Environment Variables
Using Config File
Add to~/.orcbot/orcbot.config.yaml:
Start the Bot
Sending Messages
Direct Messages (DMs)
Server Channels
Using Channel IDs
From skills or code:- Enable Developer Mode: User Settings → Advanced → Developer Mode
- Right-click channel → Copy Channel ID
Handling Attachments
Receiving Files
OrcBot automatically downloads and processes attachments:- Images
- Audio Files
- Documents
Sending Files
Use thesend_file skill:
Message Formatting
Markdown Support
Discord supports rich markdown:OrcBot Markdown Conversion
OrcBot automatically converts markdown for Discord:Message Splitting
Discord has a 2000 character limit. OrcBot auto-splits long messages:Server Management
List Servers (Guilds)
List Channels in Server
Find Channel by Name
Reply Context & Threads
OrcBot preserves conversation context:Typing Indicators
OrcBot sends typing indicators for long operations:Permissions & Roles
Required Bot Permissions
Minimum permissions needed:- View Channels - See server channels
- Send Messages - Reply to users
- Send Messages in Threads - Participate in threads
- Embed Links - Send rich embeds
- Attach Files - Send files and images
- Read Message History - View conversation context
- Add Reactions - React to messages
- Use External Emojis - Use custom emojis
Check Bot Permissions
Advanced Features
Voice Channels
For voice channel support (future):Voice channel integration is not yet implemented in OrcBot v2.1. Audio files sent as attachments are transcribed instead.
Slash Commands
Register slash commands (future enhancement):Embeds
Send rich embeds:Session Management
Session Scoping
OrcBot tracks separate sessions per channel:- DM:
discord:987654321098765432 - Server channel:
discord:123456789012345678
Metadata Storage
Messages include metadata:Troubleshooting
Bot Not Responding
1
Check Token
Verify token is correct:
2
Check Intents
Ensure MESSAGE CONTENT INTENT is enabled in Discord Developer Portal
3
Check Permissions
Verify bot has Send Messages permission in the channel
4
Check Logs
Discord bot logged in as YourBot#1234Missing Permissions Error
- Generate new invite URL with proper permissions
- Open URL and select your server
- Bot permissions will be updated
Messages Not Being Received
Check:- Message Content Intent is enabled (Developer Portal)
- Bot has Read Messages permission
- Auto-reply is enabled:
discordAutoReplyEnabled: true
Rate Limiting
- Reduce message frequency
- Batch multiple responses
- Increase delay between messages
Attachment Download Failures
Best Practices
Security
- Never commit bot token to version control
- Use environment variables or secure config
- Regularly rotate your bot token
- Use least-privilege permissions
Performance
- Send typing indicators for long operations
- Split large messages to avoid rate limits
- Clean up old downloads periodically
- Use message caching for context
User Experience
- Use embeds for structured information
- Add reactions for quick feedback
- Keep messages concise in busy channels
- Use threads for extended conversations
Moderation
- Set up role-based permissions
- Use channel restrictions for sensitive commands
- Log all bot actions
- Implement cooldowns for expensive operations