Skip to main content

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

2

Create New Application

Click “New Application”Enter a name (e.g., “OrcBot”)
3

Create Bot User

  1. Navigate to the “Bot” tab
  2. Click “Add Bot”
  3. 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

  1. Go to “OAuth2” → “URL Generator”
  2. Select scopes:
    • bot
    • applications.commands (for slash commands)
  3. Select bot permissions:
    • Send Messages
    • Send Messages in Threads
    • Embed Links
    • Attach Files
    • Read Message History
    • Add Reactions
    • Use Slash Commands
  4. Copy the generated URL
7

Add Bot to Server

  1. Open the invite URL in your browser
  2. Select your server
  3. Click “Authorize”

Configure OrcBot

Using Environment Variables

Using Config File

Add to ~/.orcbot/orcbot.config.yaml:

Start the Bot

You should see:
Your bot will now appear online in your server!

Sending Messages

Direct Messages (DMs)

Server Channels

Using Channel IDs

From skills or code:
Get channel ID:
  1. Enable Developer Mode: User Settings → Advanced → Developer Mode
  2. Right-click channel → Copy Channel ID

Handling Attachments

Receiving Files

OrcBot automatically downloads and processes attachments:
Implementation:

Sending Files

Use the send_file skill:
Implementation:
File size limit: 25 MB (100 MB with Nitro boost level 2)

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:
Example:

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:
Result:
  • 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

Should see: Discord bot logged in as YourBot#1234

Missing Permissions Error

Fix: Re-invite the bot with correct permissions:
  1. Generate new invite URL with proper permissions
  2. Open URL and select your server
  3. Bot permissions will be updated

Messages Not Being Received

Check:
  1. Message Content Intent is enabled (Developer Portal)
  2. Bot has Read Messages permission
  3. Auto-reply is enabled: discordAutoReplyEnabled: true

Rate Limiting

OrcBot includes built-in delays:
If you still hit limits:
  • 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

Example Workflows

Code Review Assistant

Server Monitoring

Team Coordination