Platforms
How-to

Set up Discord

Create a Discord application and bot, configure its permissions and Gateway Intents, connect it to Agent Barn, and verify the Agent in an approved server channel.

For
Discord administrators, Agent operators, Agent creators, and Organization administrators
On this page
  1. Overview
  2. Connection model
  3. Before you begin
  4. 1. Create a Discord application
  5. 2. Enable Gateway Intents
  6. 3. Configure installation
  7. 4. Copy Discord IDs
  8. 5. Connect Agent Barn
  9. 6. Configure access
  10. 7. Start the Agent
  11. 8. Verify the integration
  12. Manage the bot token
  13. API reference
  14. Troubleshooting
  15. Next steps
  • Discord
  • Hermes and OpenClaw
  • 15–20 minutes

Create a Discord application and bot, connect it to Agent Barn, restrict it to approved servers and channels, and verify that the Agent responds only to permitted operators.

An Agent Barn Discord Agent uses a bot account that you create in the Discord Developer Portal. Its runtime connects to Discord through the Gateway, and authenticates HTTP requests with the bot token.

Overview

When you finish this guide, you will have:

  • A Discord application with a bot user
  • The required Gateway Intents enabled
  • A least-privilege installation link
  • The bot installed in an approved Discord server
  • Server, channel, user, role, and mention restrictions
  • A running Agent verified through positive and negative access tests
Runtime Discord support Server channels Direct messages
HermesSupportedSupportedDisabled
OpenClawSupportedSupportedDisabled

Discord direct messages remain disabled for Agent Barn Agents. Configure a controlled server channel for interaction.

Use a separate Discord application and bot token for every production Agent. Agent Barn prevents two active Discord Agents from using the same bot token.

Connection model

The integration follows this path.

  1. Discord server
  2. Discord Gateway and HTTP API
  3. Hermes or OpenClaw runtime
  4. Agent Barn

The runtime opens an outbound WebSocket connection to the Discord Gateway. No public webhook, callback, or Discord Interactions Endpoint URL is required for this setup.

Discord documents the Gateway as its real-time connection for receiving events from servers. The bot token authenticates both the Gateway connection and most bot HTTP API requests. See Discord’s Gateway documentation and OAuth2 and permissions guide.

Before you begin

Make sure you have:

  • Access to the Agent Barn organization where the Agent will be created
  • Permission to create an Agent
  • Permission to manage the Agent lifecycle
  • Permission to update Agent configuration
  • Permission to manage Agent secrets, if you will later rotate the token
  • A Discord account that can create applications
  • Manage Server permission in the Discord server where the bot will be installed
  • An available Hermes or OpenClaw runtime
  • Model credentials, or an organization model configuration
  • A test channel where the bot can safely be verified

You do not need to expose Agent Barn or its runtime through a public Discord endpoint.

Create a Discord application

The Discord Developer Portal holds three pages you will use.

Discord Developer Portal
  1. General Information Application name and the public Application ID
  2. Bot Bot identity, the bot token, and Privileged Gateway Intents
  3. Installation Install context, OAuth2 scopes, and bot permissions

This is a description of the portal navigation, not a screenshot.

Create the application

Open the Discord Developer Portal.

  1. Select New Application.
  2. Enter a recognizable name.
  3. Accept Discord’s developer terms when prompted.
  4. Select Create.
  5. On General Information, copy the Application ID.
Application details 
Application name: Agent Barn Support
Application ID:   123456789012345678

The Application ID is a public identifier, not a secret. Agent Barn uses it only to generate an installation link. Agent Barn does not create the Discord application for you.

Do not copy the Public Key or Client Secret into Agent Barn. They are not required for this integration.

New Discord applications normally include a bot user automatically. Open Bot in the portal sidebar to configure it. Discord’s current creation flow is documented in Building your first Discord bot.

Configure the bot identity

On the Bot page:

  1. Set the bot’s username.
  2. Add an icon if desired.
  3. Decide whether other Discord administrators should be able to install it.
  4. Find the Token section.
  5. Select Reset Token to generate the initial bot token.
  6. Copy the token immediately.

Discord does not display the token again after you leave the page unless you reset it. Store it temporarily in a password manager.

Bot token 
REDACTED_DISCORD_BOT_TOKEN

The token is not the Application ID, Public Key, or Client Secret. Anyone with the token can authenticate as the bot, so Discord requires bot tokens to be treated like passwords and kept out of version control.

You now have an Application ID and a freshly generated bot token.

Enable Gateway Intents

On the application’s Bot page, scroll to Privileged Gateway Intents and enable the intents this Agent needs.

Intent When required Purpose
Message Content Intent Always Allows the runtime to receive the text and related content of Discord messages
Server Members Intent When using allowed role IDs Allows the runtime to evaluate server membership and role-based access

Without Message Content Intent, Discord may deliver message events with content-related fields removed.

For unverified applications, privileged intents can be enabled in the portal. Applications operating at Discord’s verification scale may also need Discord approval for those intents.

Configure installation

Configure the installation context

Open Installation in the Discord Developer Portal. For an Agent Barn bot:

  1. Enable Guild Install.
  2. Select Discord Provided Link if you want the portal to manage the default link.
  3. Include the bot scope.
  4. Include the applications.commands scope.
  5. Select only the bot permissions required for conversation.

Discord calls servers “guilds” in its API and developer settings.

OAuth2 scopes

  • bot
  • applications.commands

Bot permissions

  • Add Reactions
  • View Channels
  • Send Messages
  • Send Messages in Threads
  • Embed Links
  • Attach Files
  • Read Message History
  • Use External Emojis

The recommended Agent Barn installation link uses:

Installation link 
https://discord.com/oauth2/authorize?client_id=APPLICATION_ID&scope=bot%20applications.commands&permissions=274878286912

Replace APPLICATION_ID with the value from General Information. Agent Barn generates this link automatically when you enter the Application ID in the hiring flow.

Discord permissions remain subject to server and channel overrides. A channel can deny the bot access even if the permission was accepted during installation. See Discord’s permissions reference.

Install the bot

Open the generated installation link.

  1. Select Add to server.
  2. Choose the intended Discord server.
  3. Review the requested permissions.
  4. Select Authorize.
  5. Complete any verification prompt.
  6. Confirm that the bot appears in the server member list.

The person completing this flow must have permission to manage the selected server. Server-installed apps must be authorized by a member with Discord’s MANAGE_GUILD permission.

After installation, review the bot’s permissions in every intended channel. It must be able to:

  • View the channel.
  • Read message history.
  • Send messages.
  • Send messages in threads, if threads are used.
  • Embed links or attach files, if the Agent will produce those response types.

The bot appears in the server member list with the least-privilege permission set.

Copy Discord IDs

Agent Barn access policies use Discord’s numeric identifiers rather than names.

Application ID

Developer Portal → General Information

Generates the bot installation link. Public, not a secret.

Server ID

Right-click the server icon → Copy Server ID

Allowed server IDs. Discord’s API calls this a guild ID.

Channel ID

Right-click the channel → Copy Channel ID

Allowed channel IDs, and the optional alert destination.

User or role ID

Right-click the user, or a role in server settings → Copy User ID or Copy Role ID

Allowed user IDs and allowed role IDs.

Enable Developer Mode

In the Discord desktop application:

  1. Open User Settings.
  2. Select Advanced.
  3. Enable Developer Mode.

Discord documents the desktop and mobile process in Where can I find my User, Server, or Channel ID?

Example identifiers:

Example identifiers 
Application ID: 123456789012345678
Server ID:      234567890123456789
Channel ID:     345678901234567890
User ID:        456789012345678901
Role ID:        567890123456789012

Discord IDs are long numeric strings. Keep them as strings when using the Agent Barn API.

Do not use server names, channel names such as #support, Discord usernames, display names, or role names. Names can change, may not uniquely identify the intended resource, and are not accepted in an Agent Barn allowlist.

Connect Agent Barn

In Agent Barn:

  1. Open the intended organization.
  2. Select Hire Agent.
  3. Choose the Agent template.
  4. Select Hermes or OpenClaw.
  5. Select Discord as the platform.
  6. Continue to Connect your Discord bot.
Agent Barn field Value
Bot tokenSecret copied from the Developer Portal
Application IDPublic application identifier
Allowed server IDsComma-separated Discord server IDs
Allowed channel IDsComma-separated Discord channel IDs
Allow all usersWhether every user inside the approved boundaries may interact
Allowed operator IDsDiscord user IDs used when all-user access is disabled
Allowed role IDsDiscord role IDs used when all-user access is disabled
Alert destination channel IDOptional channel for scheduled or proactive delivery

The Application ID is optional. It is used to generate the installation link, and is not saved as a bot credential.

The bot token is required. Agent Barn encrypts it before storage, and never returns it through Agent read responses.

Agent Barn also hashes the token to enforce uniqueness. Attempting to reuse the token of another active Discord Agent returns a conflict.

Finish the remaining Agent details and create the Agent. A new Discord Agent is created in the Stopped state.

A malformed or revoked token may not be detected until the runtime attempts to connect during startup.

Configure access

Discord access is evaluated through several independent boundaries. A message must pass every configured boundary.

  1. Bot is installed in the server A Discord administrator authorized the application
  2. Server policy permits the server Open, or the server ID is on the allowlist
  3. Channel policy permits the channel The channel ID is allowed, and Discord permits the bot to see it
  4. User or role policy permits the sender All users are allowed, or the sender matches a user or role ID
  5. Mention requirement permits the message The message explicitly addresses the Agent while gating is enabled

Server access

Policy Behavior Recommended use
AllowlistThe Agent operates only in configured serversRecommended for production
OpenThe Agent may operate in any server containing the botControlled development, or intentionally distributed bots

For Allowlist, enter one or more server IDs:

Allowed server IDs 
234567890123456789, 678901234567890123

An empty allowlist does not provide production access. Add the intended server before starting the Agent.

Open access does not install the bot in other servers. A Discord administrator must still authorize the bot for every server.

Channel access

Enter the channels where the Agent may operate:

Allowed channel IDs 
345678901234567890, 789012345678901234

Channel restrictions continue to apply when the server policy is Open.

Leaving Allowed channel IDs empty removes this additional Agent Barn channel restriction, allowing the runtime to operate in channels it can see within the permitted server boundary. For production, explicitly list the intended channels.

Discord’s own channel permissions apply first. An Agent Barn allowlist cannot grant access that Discord denies.

Operator access

By default, Allow all users means any person inside the approved server and channel boundaries may interact with the Agent.

For restricted access:

  1. Disable Allow all users.
  2. Enter at least one allowed user ID or allowed role ID.
  3. Enable Server Members Intent if role IDs are used.
Restricted operator example 
Allowed user IDs:
456789012345678901

Allowed role IDs:
567890123456789012, 890123456789012345

Agent Barn rejects a restricted user policy with no allowed user or role IDs.

Role access

When access is restricted, a person is allowed if:

  • Their Discord user ID is listed; or
  • They hold at least one listed Discord role.

Role permissions do not need to grant control over the Agent. The role ID is used only as an interaction boundary, and role names cannot replace the numeric role ID.

Mention requirement

Keep Require an explicit mention in server channels enabled.

Mention example 
@Agent Barn Support summarize the unresolved questions

With mention gating enabled, ordinary channel conversation should not activate the Agent. A direct reply to one of the Agent’s messages may still be treated as addressed to that Agent.

Disabling mention gating allows ordinary messages in approved channels to reach the Agent. Use this only when the channel is dedicated to a single Agent, and the broader behavior is intentional.

Alert destination

Alert destination channel ID is optional. For Hermes, it acts as the home destination for scheduled and proactive messages. OpenClaw can use it as the target for heartbeat delivery.

Choose a channel that:

  • Is in an approved server.
  • Is included in the allowed channel IDs.
  • Is visible to the bot.
  • Allows the bot to send messages.
Recommended configuration 
Server access:               Allowlist
Allowed server IDs:          One or more approved server IDs
Allowed channel IDs:         Explicitly configured
Allow all users:             Disabled
Allowed user or role IDs:    Explicitly configured
Require explicit mention:    Enabled
Alert destination:           Optional approved channel
Direct messages:             Disabled

Start the Agent

After the hiring flow completes:

  1. Open the new Agent.
  2. Review its Discord channel configuration.
  3. Confirm that the bot is already installed in the approved server.
  4. Select Start.
  5. Wait for the status to move through initialization.
  6. Confirm that it reaches Running.

During startup, Agent Barn builds the runtime configuration and supplies the encrypted bot token to the selected runtime.

If the bot token is invalid, Gateway Intents are missing, or the runtime cannot connect to Discord, the Agent may remain unhealthy or enter Error.

When changing Discord configuration later:

Agent state Action Result
RunningApply & RestartStops the Agent, saves the configuration, and starts it with regenerated runtime settings
Stopped or ErrorApplySaves the configuration without starting the Agent

The Agent reports Running, and its runtime holds an open Gateway connection.

Verify the integration

Test every boundary that matters to your deployment.

Test Action Expected result
Allowed server and channelMention the Agent in an allowed channelAgent responds
No mentionSend an ordinary message in the allowed channelAgent does not respond
Disallowed channelMention the Agent in an unlisted channelAgent does not respond
Disallowed serverMention the Agent in another serverAgent does not respond
Allowed userAn explicitly allowed user mentions the AgentAgent responds
Allowed roleA user with an allowed role mentions the AgentAgent responds
Disallowed userA user with no allowed ID or role mentions itAgent does not respond
Direct messageSend the bot a direct messageAgent does not respond

Example positive test:

Verification message 
@Agent Barn Support reply with "Discord connection verified"

Then confirm in Agent Barn:

  1. The Agent remains Running.
  2. The inbound message appears in the Agent’s activity.
  3. The resolved channel and sender are correct.
  4. The response appears in Discord.
  5. The runtime logs contain no Gateway or permission error.

A Discord message appearing in Agent Barn proves that Discord delivery is working. If the message arrives but the Agent produces no useful response, investigate the model, Agent instructions, or runtime separately.

Manage the bot token

Do not:

  • Commit it to the agent-barn repository.
  • Put it in an environment example with real values.
  • Include it in screenshots.
  • Send it through Discord.
  • Store it in issue trackers.
  • Reuse it across Agents.
  • Place it in a URL.
  • Print it in logs.

Rotate a token

To rotate a compromised or lost token:

  1. Open the application in the Discord Developer Portal.
  2. Select Bot.
  3. Select Reset Token.
  4. Complete Discord’s authorization prompt.
  5. Copy the new token.
  6. Open the Agent in Agent Barn.
  7. Open Keys & integrations.
  8. Replace the Discord bot token.
  9. Select Apply & Restart if the Agent is running.
  10. Verify the integration again.

Resetting the token invalidates the old credential. The Agent cannot reconnect until Agent Barn contains the replacement.

Updating a Discord token requires Agent secret-management permission.

Deleting a Discord Agent releases its token hash, but a deleted bot token should still be reset or retired if the Discord application is no longer used.

API reference

Discord Agents can also be created and configured through the Agent Barn API.

Operation Endpoint
Create AgentPOST /api/v1/organizations/{organization_id}/agents
Read AgentGET /api/v1/organizations/{organization_id}/agents/{agent_id}
Update Discord configurationPATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Start AgentPOST /api/v1/organizations/{organization_id}/agents/{agent_id}/start
Stop AgentPOST /api/v1/organizations/{organization_id}/agents/{agent_id}/stop
Read healthGET /api/v1/organizations/{organization_id}/agents/{agent_id}/healthz
Read logsGET /api/v1/organizations/{organization_id}/agents/{agent_id}/logs

Create a Discord Agent

Create Agent 
POST /api/v1/organizations/{organization_id}/agents
Create Agent request 
{
  "name": "Discord Support Agent",
  "platform": "discord",
  "agent_type": "hermes",
  "template_key": "REPLACE_WITH_TEMPLATE_KEY",
  "model": "REPLACE_WITH_MODEL",
  "discord_bot_token": "REDACTED",
  "discord_group_policy": "allowlist",
  "discord_guild_ids": [
    "234567890123456789"
  ],
  "discord_allowed_channel_ids": [
    "345678901234567890"
  ],
  "discord_allow_all_users": false,
  "discord_allowed_user_ids": [
    "456789012345678901"
  ],
  "discord_allowed_role_ids": [
    "567890123456789012"
  ],
  "discord_home_channel_id": "345678901234567890",
  "discord_require_mention": true,
  "skill_ids": []
}

The Discord Application ID is not part of the Agent configuration API. It is used by the web interface only to generate an OAuth2 installation link.

The create endpoint returns the new Agent in the Stopped state.

Start the Agent

Start Agent 
POST /api/v1/organizations/{organization_id}/agents/{agent_id}/start

No request body is required.

Update routing

Stop the Agent first when calling the API directly, or use the web interface’s Apply & Restart workflow.

Update Agent 
PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Update routing request 
{
  "discord_group_policy": "allowlist",
  "discord_guild_ids": [
    "234567890123456789"
  ],
  "discord_allowed_channel_ids": [
    "345678901234567890",
    "789012345678901234"
  ],
  "discord_allow_all_users": false,
  "discord_allowed_user_ids": [],
  "discord_allowed_role_ids": [
    "567890123456789012"
  ],
  "discord_home_channel_id": "345678901234567890",
  "discord_require_mention": true
}

Rotate the token

Rotate token request 
{
  "discord_bot_token": "REDACTED"
}
Field Purpose
discord_bot_tokenSecret issued from the application’s Bot page
discord_group_policyopen or allowlist
discord_guild_idsAllowed Discord server IDs
discord_allowed_channel_idsAllowed channel IDs
discord_allow_all_usersAllows every user inside the server and channel boundaries
discord_allowed_user_idsExplicitly allowed user IDs
discord_allowed_role_idsRoles whose members may interact
discord_home_channel_idOptional proactive or heartbeat destination
discord_require_mentionRequires the bot to be explicitly addressed in server channels

If discord_allow_all_users is false, provide at least one user ID or role ID.

Troubleshooting

The Agent enters Error or never becomes healthy

Usually a token or intent problem

Check:

  • The bot token has not been reset.
  • Message Content Intent is enabled.
  • Server Members Intent is enabled when roles are used.
  • The bot is installed in the intended server.
  • The runtime can reach discord.com.
  • The selected runtime supports Discord.
  • No other process is using the same bot token.
  • Runtime and Agent logs contain no Gateway close code.

A missing privileged intent may cause Discord to close the Gateway connection with code 4014.

The Agent is running but does not receive messages

A boundary or intent is filtering it

Confirm that:

  • The message was sent in an allowed server.
  • The channel ID is included in the allowlist.
  • The bot can view the channel.
  • The message explicitly mentions the bot.
  • Message Content Intent is enabled.
  • Discord’s channel permission overrides do not deny access.
  • The sender passes the user or role boundary.

The Agent receives a message but cannot answer

Missing send permissions, or a model failure

Check that the bot has:

  • View Channel.
  • Send Messages.
  • Read Message History.
  • Send Messages in Threads, when applicable.
  • Embed Links, if responses contain links or rich content.
  • Attach Files, if responses include files.

Also review model credentials and runtime logs. Inbound delivery can succeed while response generation fails.

A user is unexpectedly blocked

Evaluate the boundaries in order
  1. Is the server allowed?
  2. Is the channel allowed?
  3. Is Allow all users enabled?
  4. If not, is the user’s numeric ID listed?
  5. Does the user currently hold an allowed role?
  6. Is Server Members Intent enabled?
  7. Did the message mention the bot?

Usernames and display names do not satisfy an ID allowlist.

Role-based access does not work

Membership information is required
  • Enable Server Members Intent.
  • Copy the role’s numeric ID rather than its name.
  • Confirm that the user currently holds the role.
  • Confirm that at least one role or user is configured when all-user access is disabled.
  • Apply the settings and restart the Agent.
  • Retest with a new message.

The bot does not need permission to manage the role. It only needs to observe the sender’s membership information.

The bot works in one channel but not another

Channel overrides or a missing ID

Discord channel overrides may deny access. Compare the bot’s effective permissions in both channels and verify:

  • View Channel
  • Send Messages
  • Read Message History
  • Send Messages in Threads

Also confirm that the second channel’s numeric ID is in Agent Barn.

The bot does not respond inside a thread

Thread permissions are separate
  • Confirm that the bot can view the parent channel.
  • Grant Send Messages in Threads.
  • Check the configured channel restrictions.
  • Mention the bot explicitly inside the thread.
  • Review logs for missing-access or permission errors.

The Agent responds to ordinary conversation

Mention gating is disabled

Check Require an explicit mention in server channels. If it is disabled:

  1. Open the Agent’s Discord channel settings.
  2. Enable the mention requirement.
  3. Select Apply & Restart.
  4. Verify with an unmentioned message.

A direct reply to an Agent message can still be treated as addressed to that Agent.

The installation link does not list the server

Server management authority is required

The current Discord user must have permission to manage that server. Also verify:

  • Guild installation is enabled.
  • The Application ID is correct.
  • The application permits the current user to install it.
  • The bot has not reached an application-specific installation restriction.
The link must carry the Application ID

Confirm that the link uses the Application ID, not the bot token:

Installation link 
https://discord.com/oauth2/authorize?client_id=APPLICATION_ID&scope=bot%20applications.commands&permissions=274878286912

Never place the bot token in the installation URL.

Agent Barn reports that the bot token is already in use

Tokens cannot be shared between Agents

Every active Discord Agent must use a unique bot token.

Create another Discord application and bot for the new Agent. Do not stop one Agent merely to alternate a single token between runtimes.

A new token does not work

The runtime needs the replacement

After resetting the token in Discord:

  1. Replace it under Keys & integrations.
  2. Apply and restart the Agent.
  3. Wait for the new runtime configuration.
  4. Review health and logs.
  5. Verify that the bot is still installed in the server.

Resetting a token does not remove the bot from the server, but it immediately invalidates the old runtime credential.

Scheduled or proactive messages are not delivered

No usable alert destination
  • Configure Alert destination channel ID.
  • Put the destination inside an allowed server and channel.
  • Confirm that the bot can send messages there.
  • Restart the Agent after changing the destination.
  • For Hermes, confirm that scheduled delivery is configured.
  • For OpenClaw, confirm that heartbeat delivery is enabled.

Direct messages do not work

Expected: Discord DMs are disabled

This is expected. Discord direct messages are disabled for Agent Barn Agents.

Use an approved private server channel and restrict it with:

  • Discord channel permissions.
  • Agent Barn’s server allowlist.
  • Agent Barn’s channel allowlist.
  • Allowed user or role IDs.
  • Explicit mention gating.

Next steps

After verifying Discord:

Documentation