Prerequisites
A Discord account
Server admin permissions (to add bot)
OrcBot installed and configured
Node.js 18+ installed
Create Discord Bot
Open Discord Developer Portal
Create New Application
Click “New Application” Enter a name (e.g., “OrcBot”)
Create Bot User
Navigate to the “Bot” tab
Click “Add Bot”
Confirm “Yes, do it!”
Configure Bot Settings
Enable these Privileged Gateway Intents:
☑ SERVER MEMBERS INTENT
☑ MESSAGE CONTENT INTENT
☑ PRESENCE INTENT (optional)
Copy Bot Token
Under the “Bot” tab, click “Reset Token” and copy the new token Save this token securely - you won’t be able to see it again!
Generate Invite Link
Go to “OAuth2” → “URL Generator”
Select scopes:
bot
applications.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
Add Bot to Server
Open the invite URL in your browser
Select your server
Click “Authorize”
Using Environment Variables
Linux/macOS
Windows
Docker Compose
export DISCORD_TOKEN = "your-bot-token-here"
Using Config File
Add to ~/.orcbot/orcbot.config.yaml:
discordToken : "your-bot-token-here"
# Optional: Enable auto-reply
discordAutoReplyEnabled : true
Start the Bot
cd ~/orcbot
npm run build
npm run start
You should see:
Discord bot logged in as OrcBot#1234
Agent: Discord channel started
Your bot will now appear online in your server!
Sending Messages
Direct Messages (DMs)
User: "Hello!"
Bot: "Hi! I'm OrcBot. How can I help you today?"
Server Channels
User: "@OrcBot summarize this conversation"
Bot: "Here's a summary of the last 10 messages..."
Using Channel IDs
From skills or code:
// Send to specific channel
await agent . discord . sendMessage (
"123456789012345678" , // Channel ID
"Hello from OrcBot!"
);
Get channel ID:
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
User: [uploads diagram.png]
"Explain this architecture"
Bot: Based on the diagram, this shows a microservices
architecture with:
- API Gateway at the front
- 3 backend services
- Shared database layer
- Message queue for async processing
Implementation: if ( attachment . contentType ?. startsWith ( 'image/' )) {
const localPath = path . join ( downloadPath , `discord_ ${ messageId } _ ${ fileName } ` );
fs . writeFileSync ( localPath , buffer );
mediaPaths . push ( localPath );
}
User: [uploads meeting.mp3]
"Transcribe this recording"
Bot: [Processing audio...]
Transcription:
"Welcome everyone to the Q4 planning meeting.
Let's start with the sales update..."
Auto-transcription: const audioExts = [ '.ogg' , '.mp3' , '.m4a' , '.wav' , '.opus' ];
if ( audioExts . includes ( path . extname ( fileName ). toLowerCase ())) {
const result = await this . agent . llm . analyzeMedia (
localPath ,
'Transcribe this audio message exactly.'
);
transcriptionResult = result . replace ( / ^ Transcription result: \n / i , '' );
}
User: [uploads report.pdf]
"Summarize the key points"
Bot: I've analyzed the 15-page report.
Key Points:
1. Revenue up 23% YoY
2. New product line launching Q2
3. Expansion into APAC markets
4. 5 new hires planned
Sending Files
Use the send_file skill:
send_file (
to : "123456789012345678" , // Channel ID
filePath : "/path/to/report.pdf" ,
caption : "Here's the quarterly report" ,
channel : "discord"
)
Implementation:
const attachment = new AttachmentBuilder ( filePath );
await textChannel . send ({
content: caption || undefined ,
files: [ attachment ]
});
File size limit: 25 MB (100 MB with Nitro boost level 2)
Markdown Support
Discord supports rich markdown:
**bold text**
*italic text*
~~strikethrough~~
__underline__
||spoiler||
OrcBot Markdown Conversion
OrcBot automatically converts markdown for Discord:
const formatted = hasMarkdown ( message )
? renderMarkdown ( message , 'discord' )
: message ;
// Headings → bold
// Images → URLs
// Clean up formatting
Message Splitting
Discord has a 2000 character limit. OrcBot auto-splits long messages:
if ( formatted . length <= 2000 ) {
await textChannel . send ( formatted );
} else {
const chunks = this . splitMessage ( formatted , 2000 );
for ( const chunk of chunks ) {
await textChannel . send ( chunk );
await this . delay ( 500 ); // Avoid rate limiting
}
}
Server Management
List Servers (Guilds)
const guilds = await discordChannel . getGuilds ();
guilds . forEach ( g => {
console . log ( ` ${ g . name } ( ${ g . id } )` );
});
List Channels in Server
const channels = await discordChannel . getTextChannels ( guildId );
channels . forEach ( c => {
console . log ( `# ${ c . name } ( ${ c . id } )` );
});
Find Channel by Name
const channel = await discordChannel . findChannelByName (
guildId ,
"general"
);
Reply Context & Threads
OrcBot preserves conversation context:
if ( message . reference ?. messageId ) {
const repliedMessage = await message . fetchReference ();
const repliedText = repliedMessage . content || '[Media/Embed]' ;
const repliedUser = repliedMessage . author ?. username || 'Unknown' ;
replyContext = `[Replying to ${ repliedUser } 's message: " ${ repliedText } "]` ;
}
Example:
Alice: "What's the deployment status?"
Bob: [Replies to Alice] "@OrcBot answer this"
Bot: [Replies to Bob's message]
"Based on Alice's question about deployment status:
Current deployment is at 85% completion..."
Typing Indicators
OrcBot sends typing indicators for long operations:
await discordChannel . sendTypingIndicator ( channelId );
// Typing indicator lasts ~10 seconds
// Auto-refresh for longer operations
const interval = setInterval (() => {
discordChannel . sendTypingIndicator ( channelId );
}, 8000 );
// Clear when done
clearInterval ( interval );
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
const channel = await client . channels . fetch ( channelId );
const permissions = channel . permissionsFor ( client . user );
if ( ! permissions . has ( 'SendMessages' )) {
console . log ( 'Bot cannot send messages in this channel' );
}
Advanced Features
Voice Channels
For voice channel support (future):
# Config for voice features
discordVoiceEnabled : false
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):
const { SlashCommandBuilder } = require ( 'discord.js' );
const command = new SlashCommandBuilder ()
. setName ( 'summarize' )
. setDescription ( 'Summarize recent conversation' )
. addIntegerOption ( option =>
option . setName ( 'messages' )
. setDescription ( 'Number of messages to summarize' )
. setRequired ( false )
);
Embeds
Send rich embeds:
const { EmbedBuilder } = require ( 'discord.js' );
const embed = new EmbedBuilder ()
. setTitle ( 'Task Complete' )
. setDescription ( 'Your report has been generated' )
. setColor ( 0x00FF00 )
. addFields (
{ name: 'Status' , value: 'Success' , inline: true },
{ name: 'Duration' , value: '2.3s' , inline: true }
)
. setTimestamp ();
await channel . send ({ embeds: [ embed ] });
Session Management
Session Scoping
OrcBot tracks separate sessions per channel:
const sessionScopeId = this . agent . resolveSessionScopeId ( 'discord' , {
sourceId: channelId ,
userId
});
Result:
DM: discord:987654321098765432
Server channel: discord:123456789012345678
Messages include metadata:
metadata : {
guildId , // Server ID (if in server)
channelName , // Channel name
replyToMessageId // If replying to another message
}
Troubleshooting
Bot Not Responding
Check Token
Verify token is correct: grep discordToken ~/.orcbot/orcbot.config.yaml
Check Intents
Ensure MESSAGE CONTENT INTENT is enabled in Discord Developer Portal
Check Permissions
Verify bot has Send Messages permission in the channel
Check Logs
tail -f ~/.orcbot/logs/orcbot.log | grep -i discord
Should see: Discord bot logged in as YourBot#1234
Missing Permissions Error
Fix: Re-invite the bot with correct permissions:
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
DiscordAPIError: You are being rate limited
OrcBot includes built-in delays:
for ( const chunk of chunks ) {
await textChannel . send ( chunk );
await this . delay ( 500 ); // 500ms between messages
}
If you still hit limits:
Reduce message frequency
Batch multiple responses
Increase delay between messages
Attachment Download Failures
# Check download directory
ls -la ~/.orcbot/downloads/
# Check disk space
df -h ~/.orcbot/
# Check permissions
chmod 755 ~/.orcbot/downloads/
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
Example Workflows
Code Review Assistant
User: [uploads code.py]
"Review this code for security issues"
Bot: [Typing...]
Security Analysis:
⚠️ Critical:
- Line 23: SQL injection vulnerability
- Line 45: Hardcoded API key
💡 Recommendations:
1. Use parameterized queries
2. Move credentials to environment variables
3. Add input validation on lines 15-20
Server Monitoring
#alerts channel
Bot: 🚨 Alert: High CPU Usage
Server: web-prod-01
CPU: 92%
Memory: 78%
Uptime: 14 days
[Restart Service] [View Logs] [Dismiss]
Team Coordination
#general channel
Alice: "Who's working on the API refactor?"
Bob: "When is the deadline?"
Carol: "What's the progress?"
@OrcBot: "Summarize this project discussion"
Bot: Project: API Refactor
Team: Alice, Bob, Carol
Deadline: March 15 (8 days away)
Progress: 65% complete
Recent updates:
- Authentication module done (Alice)
- Database layer in progress (Bob)
- Testing pending (Carol)
Next steps:
1. Complete DB migration (Bob, 2 days)
2. Integration testing (Carol, 3 days)
3. Final review (All, 1 day)