Tutorial

Connect Your Agent to Discord

Talk to your AI agent from any Discord server. Set up in 10 minutes — no coding required.

⏱ About 10 minutes

Before You Start

Make sure you have:

A heyron account with a working agent (you can chat in the web dashboard)
A Discord account
A Discord server you own (or have admin access to)
Don't have your own Discord server?

Create one for free: open Discord → click the + button on the left sidebar → Create My OwnFor me and my friends. Done in 30 seconds.


1

Create a Discord Application

Go to the Discord Developer Portal and click New Application.

  1. Name it whatever you want — this is just the app name, not your bot's display name. Something like "My Agent" works fine.
  2. Accept the Terms of Service and click Create.
2

Set Up the Bot

In the left sidebar, click Bot.

  1. Change the Username to whatever you want your bot to be called in Discord. This is the name people will see.
  2. (Optional) Upload a profile picture for your bot.
3

Enable Message Content Intent

This is the step people miss most often. Still on the Bot page, scroll down to Privileged Gateway Intents.

Turn on these toggles:

Message Content IntentRequired. Without this, your bot can't read messages.
Server Members Intent — Recommended. Lets your bot see who's in the server.
⚠️ #1 Cause of "My Bot Won't Reply"

If you skip Message Content Intent, your bot will appear online but never respond to anything. This is the most common setup issue — it trips up almost everyone. Go back and double-check this toggle is ON.

Click Save Changes at the bottom of the page.

4

Copy Your Bot Token

Scroll back to the top of the Bot page and click Reset Token.

First time?

Despite saying "Reset," this just generates your first token. Nothing is being deleted.

Copy the token and save it somewhere safe (a text file, a note, whatever). You'll need it in a few minutes. You can only view this token once — if you lose it, you'll have to regenerate it.

Keep your token private

Your bot token is like a password. Never share it in a public channel or screenshot. Anyone with your token can control your bot. If you accidentally leak it, come back here and click Reset Token to invalidate the old one.

5

Set Bot Permissions and Create Invite Link

In the left sidebar, click OAuth2.

Scroll down to OAuth2 URL Generator.

Select Scopes:

bot
applications.commands

Select Bot Permissions:

A permissions panel appears after you select bot. Enable these:

View Channels
Send Messages
Read Message History
Embed Links
Attach Files
Add Reactions
Don't use Administrator

You might be tempted to just check "Administrator" to cover everything. Don't. Give your bot only what it needs. The permissions above are plenty.

Scroll to the bottom and copy the generated URL.

6

Add the Bot to Your Server

  1. Paste the URL from Step 5 into your browser.
  2. Select your Discord server from the dropdown.
  3. Click Continue, then Authorize.
  4. Complete the captcha if prompted.

You should now see your bot in your server's member list (it'll show as offline for now — that's normal).

7

Enable Developer Mode & Copy Your IDs

You need two IDs from Discord to connect everything. First, enable Developer Mode:

  1. In Discord, click the gear icon (User Settings) next to your avatar.
  2. Go to Advanced (under App Settings).
  3. Toggle on Developer Mode.

Now copy your IDs:

  1. Server ID — Right-click your server icon in the sidebar → Copy Server ID.
  2. Your User ID — Right-click your own avatar or name → Copy User ID.

Save both IDs alongside your bot token. You'll need all three in the next step.

8

Enable Direct Messages

Your agent needs to be able to DM you for the initial pairing handshake.

  1. Right-click your server iconPrivacy Settings.
  2. Toggle on Direct Messages.

This lets bots on this server send you DMs. You can turn it off after pairing if you only want to use channel chat.

9

Tell Your Agent to Connect

Now go to your heyron dashboard chat (heyron.ai/chat) and tell your agent:

Set up Discord for me. Here are my details:

Bot Token: [paste your token]
Server ID: [paste your server ID]
User ID: [paste your user ID]

Your agent will handle the rest — it'll save the token, configure Discord, and restart its gateway. This usually takes about 30 seconds.

If the automatic setup fails

Sometimes the auto-setup hits a snag. If your agent says something went wrong, don't worry — check the troubleshooting section below. The most common fix is to make sure Message Content Intent is enabled (Step 3) and try again.

⚠️ Important: Only send the token in your dashboard chat

Your dashboard at heyron.ai/chat is a private, encrypted connection to your agent. Never paste your bot token in a Discord channel, a support ticket, or anywhere public. It's like posting your password.

10

Approve the Pairing

After your agent sets up Discord, go to Discord and DM your bot. Say anything — "hello" works.

Your bot will reply with a pairing code. Go back to your heyron dashboard chat and tell your agent:

Approve this Discord pairing code: [paste the code]

Once approved, your bot is live. Try chatting with it in Discord!

🎉 You're Connected!

Your agent is now live on Discord. Every channel in your server gets its own conversation — like separate chat rooms. Your DMs with the bot are your main private line.


After Setup: Making It Yours

Talk Without @Mentioning

By default, your bot only responds in channels when you @mention it. If it's your private server and you want it to reply to every message, tell your agent in the dashboard:

Allow my agent to respond on Discord without being @mentioned

Use Different Channels for Different Tasks

Create channels like #work, #brainstorm, #daily-journal — each one gets its own separate conversation with your agent. Your agent won't mix up contexts between channels.


Troubleshooting

Something not working? Here are the most common issues and their fixes.

My bot is online but won't reply to anything

95% of the time this is the Message Content Intent.

Go to Discord Developer Portal → your application → Bot → scroll to Privileged Gateway Intents → make sure Message Content Intent is toggled ON → Save Changes.

Then tell your agent: "Restart the gateway" or just wait a minute for it to reconnect.

Bot replies in DMs but ignores channel messages

This is usually a policy/config mismatch — not a token failure.

Run this exact sequence in your dashboard chat:

1) "Add my Discord Server ID [your server ID] to the guild allowlist."
2) "Set Discord requireMention to false and groupPolicy to open."
3) "Set Discord allowBots to true." (needed if your workflow involves relays/other bot messages)
4) "Restart the gateway."

Then test in a brand-new text channel with default permissions. If it works there, your core setup is healthy and older channels likely have overrides/restrictions.

I can't DM the bot / no pairing code appears

Check that you enabled DMs from server members (Step 8). Right-click your server icon → Privacy Settings → toggle Direct Messages ON.

Also make sure the bot is actually online in your server. If it shows offline, the token might be wrong or the gateway hasn't started. Ask your agent "Is Discord connected?" in the dashboard.

I get a "pairing code" but it won't approve

Pairing codes expire after 1 hour. If too much time has passed, DM the bot again to get a fresh code.

Make sure you're pasting the code exactly — no extra spaces. Tell your agent: "Approve this Discord pairing code: XXXX"

My agent broke after trying Discord setup

In rare cases, an agent can accidentally overwrite its own config during setup. If your agent stopped responding everywhere (including the web dashboard), you'll need support.

Open a ticket in #help on the heyron Discord with your signup email, and the team will fix your config server-side. This is a known edge case and they can usually resolve it in minutes.

I see the bot in my server but it says "offline"

The bot showing offline usually means the gateway hasn't connected yet. Tell your agent: "Restart the gateway" in the web dashboard.

If that doesn't work, double-check that your bot token is correct. You can regenerate it in the Developer Portal (Bot → Reset Token) and give the new token to your agent.

My setup gets stuck on an “Approval Required” prompt

This is expected if your agent is configured to ask before sensitive actions. Read the full guide: Why Your Agent Says “Approval Required”.

Quick rule: approve only if the command matches what you're trying to do (Discord connect / gateway restart), and deny anything that looks unrelated.

If you denied a needed command by accident, just tell your agent to try again and approve the same safe action on the next prompt.

Slash commands or @mentions still don't trigger a response

First, make sure your bot has View Channels, Send Messages, and Read Message History in the specific channel you're testing.

Then test in a brand-new channel with minimal custom permissions. Channel-level overrides are a common hidden blocker.

If it works in the new channel, the issue is channel permissions — not your token or intents.

I enabled intents and bot permissions, but it still won't respond

This is usually a Discord integration restriction, stale session, or channel override issue.

Run this fast isolation flow:

1) In Discord: Server Settings → Integrations → your bot and confirm commands are allowed for your role/channel.
2) In heyron dashboard, start fresh with /new and ask your agent: "Restart the gateway and verify Discord is connected."
3) Create a brand-new channel with default permissions and test one message that @mentions the bot.
4) If mention works there but not elsewhere, fix per-channel overrides. If mention fails everywhere, regenerate token (Bot → Reset Token) and reconnect in dashboard.

Community pattern: many "bot won't reply" reports are not bad intents — they're integration restrictions or channel-level permission drift.

DM works, but my server channel feels like a different bot

You're still talking to the same agent identity. Discord just gives you two conversation surfaces:

DM = private one-on-one thread
Server channels = group/public threads with separate channel context

If channel behavior feels different, it's usually one of these:

1) You're testing in a different channel (each channel has its own conversation history).
2) Channel permissions/overrides differ from DM behavior.
3) You accidentally created a second bot application/token during retries.

Quick check: in Discord Developer Portal, confirm you're using one app + one token; in heyron dashboard, ask your agent to report the active Discord app name and server ID, then test in a clean new channel with one @mention.

Bot can read my message but still doesn't send a reply

This pattern usually means read permissions are okay, but send permissions are blocked in that channel.

Check these in the exact channel you're testing:

1) Channel settings → Permissions: bot role has Send Messages allowed (not neutral/denied).
2) If channel is a Thread, also allow Send Messages in Threads.
3) If channel is a Forum, confirm the bot can create/reply to posts in that forum.
4) Server Settings → Integrations → your bot: command and channel restrictions are not blocking this channel.
5) Slowmode/mod rules are not preventing immediate replies from newly joined bots.

Known-good test: create a fresh text channel with default permissions, @mention the bot once. If it replies there, your core setup is fine and this is a channel-level policy issue.

Can I make two bots talk to each other in Discord?

Short answer: not reliably, and usually not recommended.

Most users mean "my Heyron bot + another bot should auto-chat." In practice, this creates loops, mention failures, and moderation/rate-limit issues. Many bots also ignore other bots by design.

If your goal is automation, better pattern:

1) Keep one primary Heyron bot for conversation.
2) Use connectors/tools for data handoff instead of bot-to-bot chatting.
3) Test with a human message + @mention first to confirm your Heyron bot is healthy.

If your Heyron bot responds to humans but not other bots, your setup is probably fine — that's expected behavior, not a broken connection.

How do I connect to a server I don't own?

You need admin permissions on the server to add a bot. If you're a regular member, ask the server owner to add your bot using the invite URL from Step 5.

For most use cases, we recommend creating your own private server. It's free and takes 30 seconds.


Quick Reference

Discord Developer Portal: discord.com/developers/applications

Your Dashboard: heyron.ai/chat

Need Help? Post in #help on The Den

Full Docs: docs.openclaw.ai/channels/discord