Skip to Content
IntegrationsDiscord Integration

Discord Integration

Connect your Hatcher agent to Discord so it can interact with users in your server’s channels. Setup takes about 5 minutes.

Prerequisites

  • A Discord account
  • A Discord server where you have Manage Server permission (or create a new one)
  • A Hatcher agent already created (Getting Started)
  • Discord integration is free on all Hatcher plans

Setup

Create a Discord Application

  1. Go to the Discord Developer Portal 
  2. Click New Application in the top right
  3. Enter a name for your application (e.g., “My Crypto Agent”)
  4. Accept the terms of service and click Create

Create the Bot

  1. In your application’s settings, click Bot in the left sidebar
  2. Your bot is created automatically with the application

Get the Bot Token

  1. On the Bot page, click Reset Token
  2. Discord will show you the token once — copy it immediately
MTIzNDU2Nzg5MDEyMzQ1Njc4.ABCDEF.abcdefghijklmnopqrstuvwxyz1234567890

Save this token somewhere secure. Discord only shows it once. If you lose it, you’ll need to reset it (which invalidates the old token).

Enable Privileged Intents

Still on the Bot page, scroll down to Privileged Gateway Intents and enable:

  • Message Content Intent — Required so your bot can read message text
  • Server Members Intent — Required for member-related features

Click Save Changes.

Without Message Content Intent enabled, your bot will receive empty messages and won’t be able to respond. This is the most common setup mistake.

Generate the Invite URL

  1. Go to OAuth2 in the left sidebar
  2. Click URL Generator
  3. Under Scopes, check:
    • bot
    • applications.commands
  4. Under Bot Permissions, check:
    • Send Messages
    • Read Message History
    • Use Slash Commands
    • Embed Links
    • Attach Files
    • Add Reactions
  5. Copy the generated URL at the bottom of the page

Invite the Bot to Your Server

  1. Paste the URL from the previous step into your browser
  2. Select the server you want to add the bot to
  3. Click Authorize
  4. Complete the CAPTCHA if prompted

You should see your bot appear in the server’s member list (it will show as offline until your Hatcher agent starts).

Get the Application ID

  1. On the General Information page of your application (in the left sidebar)
  2. Copy the Application ID (a long numeric string) — you’ll need this along with the bot token

Configure in Hatcher

  1. Go to your Hatcher Dashboard
  2. Navigate to My Agents and select your agent
  3. Open the Integrations tab
  4. Find Discord and click Configure
  5. Paste your Bot Token into the token field
  6. Paste your Application ID into the application ID field
  7. Click Save

Restart your agent

Click Restart on your agent to apply the new configuration. Within a few seconds, your bot should appear as online in your Discord server.

Test it

Go to a channel in your Discord server where the bot has access and send a message. Your agent should respond.

Channel Permissions

By default, the bot can see and respond in all channels it has access to. To restrict it to specific channels:

  1. In Discord, go to Server Settings → Roles
  2. Find your bot’s role
  3. Go to the specific channel’s settings → Permissions
  4. Configure which channels the bot can read and send messages in

Slash Commands

The agent framework automatically registers slash commands with Discord if configured. Users in your server can type / to see available commands.

Troubleshooting

Bot is offline in Discord

  • Check that your agent is running. Go to the Hatcher dashboard and verify the status is Active.
  • Verify the token. If you reset the token in Discord, you need to update it in Hatcher too.
  • Restart the agent after saving the token.

Bot is online but doesn’t respond

  • Message Content Intent is probably not enabled. Go to the Discord Developer Portal → your app → Bot → enable Message Content Intent → Save Changes. Then restart the agent in Hatcher.
  • Check channel permissions. Make sure the bot’s role has permission to read messages and send messages in the channel.

”Used disallowed intents” error in logs

You enabled intents in your agent config that aren’t enabled in the Developer Portal. Go back to the Bot page and enable the required Privileged Gateway Intents.

Bot responds to some users but not others

Check the channel permissions. The bot needs Read Message History and View Channel permissions for each channel where it should work.

Rate limiting (429 errors)

Discord rate limits bots to approximately 50 requests per second globally. If your agent sends too many messages too quickly, Discord will temporarily block it. This usually resolves within a few seconds.

”Invalid token” error

Your token is wrong or has been reset. Go to the Discord Developer Portal, reset the token, copy the new one, and update it in Hatcher.

Last updated on
Platform IntegrationsGitHub Action