Discord Setup Guide
Enables your agent to send and read messages and manage interactions in your Discord server.
Prerequisites
- A Discord account
- A Discord server where you have admin permissions (or permission to add bots)
Step 1: Create a Discord Application
- Go to the Discord Developer Portal
- Click New Application
- Enter a name (e.g., "Carapace Agent") and click Create
Step 2: Create a Bot and Get the Token
- In the left sidebar, click Bot
- Click Add Bot (if not already created)
- Under Token, click Reset Token
- Copy the token — this is your
bot_token. It's shown only once.
Step 3: Enable Required Intents
This step is critical and commonly missed.
- Still on the Bot page, scroll down to Privileged Gateway Intents
- Enable:
- Message Content Intent — required for the bot to read message content (without this, messages appear empty)
- Server Members Intent — enable if the agent needs to look up server members
- Click Save Changes
Step 4: Invite the Bot to Your Server
- In the left sidebar, click OAuth2 > URL Generator
- Under Scopes, check
bot - Under Bot Permissions, check:
- Send Messages
- Read Messages/View Channels
- Read Message History
- Embed Links (optional, for rich messages)
- Attach Files (optional)
- Copy the generated URL at the bottom
- Open the URL in your browser, select the server, and click Authorize
Step 5: Connect in Carapace
- Go to Dashboard > Connections
- Find Discord and click Connect
- Paste the bot token
- Click Save Credentials
Credential Fields Reference
| Field | Required | Format | Description |
|---|---|---|---|
bot_token | Yes | Three dot-separated segments | Bot token from the Developer Portal |
Gotchas
Message Content Intent must be enabled: Without this privileged intent enabled in the Developer Portal, your bot receives message events but the message content is empty. This is Discord's default privacy restriction — you must explicitly opt in.
Bot token vs Client Secret: The Developer Portal shows both a Bot Token and an Application Client Secret. You need the Bot Token (under the Bot section), not the Client Secret (under General Information).
Bot token is shown once: After clicking "Reset Token," the token is displayed only once. If you lose it, you'll need to reset it again (which invalidates the old token).
Channel permissions: Even after inviting the bot to the server, it can only access channels its role has permission to view. Check the channel's permission overrides if the bot can't see specific channels.
Verification requirement for large bots: Bots in more than 100 servers require verification by Discord. For single-server agent use, this doesn't apply.
Troubleshooting
Bot is online but doesn't respond to messages
Message Content Intent is probably not enabled. Go to Developer Portal > Bot > Privileged Gateway Intents and enable it.
"Missing Permissions" errors
The bot's role doesn't have the required permissions in that channel. Check the channel's permission settings and ensure the bot role has Send Messages and View Channel.
Bot doesn't appear in the server
The invite URL wasn't generated with the correct scopes. Regenerate it with the bot scope and re-invite.