--- title: Connect an Agent to Discord canonical: "https://agentbarn.dev/guides/platforms/discord" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-28T09:37:04.000Z" author: Agent Barn description: "Connect Discord to an Agent Barn Agent: create a bot, enable the required Gateway Intents, add its token to a Communication Connection, and layer server, channel, user, and role access." tags: [Platforms, How-to, "Discord administrators, Agent operators, Agent creators, and Organization administrators", Discord, Discord bot, Discord application, Communication Connection, Gateway Intents, Message Content Intent, Server Members Intent, server ID, guild ID, channel ID, role ID, direct messages] categories: [Guides, Platforms] --- - Discord - Hermes and OpenClaw - 15–20 minutes Connect Discord to an existing Agent by creating a Discord Communication Connection. You create a Discord application and bot, install it into a server, then paste its token into the Connection and layer the access policies you need. Discord works with both Hermes and OpenClaw. Agent Barn's Communications Gateway supervises the Discord Gateway session, so no public inbound webhook is required. ## Overview Discord is not selected while creating the Agent. The Agent is created headless, and Discord is added afterward as a Connection. - An Agent can have zero or many Communication Connections. - The same Agent can have multiple Discord Connections using different Discord bots. - The Communications Gateway supervises the Discord Gateway session. - The Agent Runtime never receives the Discord bot token and does not maintain the Gateway connection. - Discord does not require a public inbound webhook. When you finish this guide, you will have: - A Discord application and bot with Message Content Intent enabled - The bot installed in the intended server with the required permissions - A Discord Communication Connection on an existing Agent - Layered server, channel, user, role, direct-message, and mention policies - A verified Discord conversation with the Agent See [Communication Connections](/guides/agents/communication-connections) for the shared Connection lifecycle, and [Compare platform compatibility](/guides/platforms/compatibility) for how Discord sits beside the other Platforms. ## Connection model The Discord Platform Plugin uses a supervised Gateway session held by the Communications Gateway: 1. Discord server 2. Discord Gateway 3. Discord Platform Plugin 4. Communications Gateway 5. Hermes or OpenClaw Replies return through the same Connection, sent with the Connection's own bot token. Discord transport does not run inside Hermes or OpenClaw. | Portal page | What it provides | | --- | --- | | General Information | Application name and the public Application ID | | Bot | Bot identity, the bot token, and Privileged Gateway Intents | | OAuth2 | The URL Generator used to install the bot into a server | ## Before you begin You need: - An existing Agent - Permission to update the Agent and manage its Connection credentials - Permission to create an application in the Discord Developer Portal - Permission to invite the bot into the intended Discord servers - A Discord bot token - Message Content Intent enabled for the bot **Security** Anyone who obtains the bot token can control the bot. Never commit it, paste it into a Template or Skill, or send it through a Discord message. Enter it only into the Connection credential field. ## Create the Discord application and bot 1. Open the [Discord Developer Portal](https://discord.com/developers/applications). 2. Create a new application, or open an existing application. 3. Open the application's **Bot** page. 4. Create the bot if one does not already exist. 5. Reset or copy the bot token. 6. Store the token securely for entry into the Communication Connection. ``` Application name: Agent Barn Support Application ID: 123456789012345678 ``` **Important** The required credential is the bot token from the **Bot** page. Do not enter any of these as the bot token: - Application ID - Public key - Client secret - OAuth invite URL Resetting the token invalidates the previous value immediately. If a Connection already uses the old token, update it before or right after the reset. ## Enable Gateway Intents Open **Bot → Privileged Gateway Intents** and enable: - **Message Content Intent** Message Content Intent is required for Agent Barn to receive the content of Discord messages. Without it, messages arrive without readable text and the Agent cannot act on them. Also consider **Server Members Intent**: - Enable it when the Connection editor must suggest server members. - It is relevant to member discovery and user-based access configuration. - It is not required when you are not using member discovery. Reconnect the bot after changing its enabled intents so Discord applies the new configuration. ## Install the bot into a server 1. Open **OAuth2 → URL Generator**. 2. Select the `bot` scope. 3. Generate an installation URL. 4. Open the URL and choose the intended Discord server. 5. Grant the bot the required permissions. 6. Repeat the installation for every server the Connection should use. | Permission | Why it is needed | | --- | --- | | View Channels | See the channels the Connection is allowed to use | | Send Messages | Deliver the Agent’s replies | | Read Message History | Read context in an allowed channel | | Send Messages in Threads | Reply inside Discord threads, when threads are used | **Important** Discord permissions and Agent Barn Connection policies both apply. Agent Barn cannot read or reply in a channel the Discord bot itself cannot access, and an allowlist never grants access that Discord denies. Installing the bot requires Discord authority in that server. If you cannot complete the install, ask a server administrator to open the generated URL. ## Create the Discord Connection With the token in hand, create the Connection on the Agent. 1. Open the existing Agent. 2. Open its **Communication Connections** section. 3. Choose Discord. 4. Enter a Connection display name. 5. Paste the Discord bot token into **Bot token**. 6. Configure the server, channel, user, role, direct-message, and mention policies. 7. Create and enable the Connection. Use a display name that identifies the server or purpose, such as `Discord: Community server`. **Security** The bot token belongs to the Communication Connection. It is encrypted at rest, the stored token is not returned through the API, and it is never materialized into Hermes or OpenClaw. The token must not be reused by another active Discord Communication Connection. The Communications Gateway validates the token and owns the Discord Gateway lifecycle for this Connection. ## Browse the Discord directory A saved Discord Connection can browse provider-backed directory data using its stored credential, so you can pick servers, channels, members, and roles instead of collecting IDs by hand. 1. Save the Discord Connection. 2. Open the Connection for editing. 3. Use **Browse** for Allowed servers. 4. Select a server before browsing its channels, users, or roles. 5. Use the resulting searchable pickers to populate the policy fields. Directory discovery can return: - Servers where the bot is installed - Message-capable channels in the selected server - Human server members - Non-default roles How it behaves: - Bot accounts are excluded from member suggestions. - Non-message channels are excluded from channel choices. - Only Discord provider IDs are persisted. - Manual ID entry remains available. - Raw IDs may still be used for multi-server allowlists. - Provider directory results are credential-scoped and cached briefly. A directory failure does not expose the bot token or raw provider error text, and it does not stop you from configuring policies manually. Browsing is server-first: select the server before its channels, members, and roles can be listed. ## Copy Discord IDs manually Manual entry remains a supported alternative to browsing. 1. Open Discord user settings. 2. Open **Advanced**. 3. Enable **Developer Mode**. 4. Use Discord's context menus to copy server, channel, user, and role IDs. ``` Server ID: 234567890123456789 Channel ID: 345678901234567890 User ID: 456789012345678901 Role ID: 567890123456789012 ``` Policy fields require Discord IDs rather than display names. A server, channel, user, or role name cannot be used as an access identifier. ## Configure the Connection settings The Discord Platform Plugin supplies these settings on the Connection form. | Setting | Behavior | Underlying setting | | --- | --- | --- | | Channel access | open: accept eligible messages from any server where the bot is installed; allowlist: accept messages only from configured Discord servers | `group_policy` | | Allowed servers | Discord server, or guild, IDs used when Channel access is allowlist | `guild_ids` | | Allowed channels | Optional Discord channel IDs. Empty means any channel in an otherwise allowed server may pass; populated restricts messages to the listed channels | `allowed_channel_ids` | | Allowed users | Optional Discord user IDs, used for direct-message allowlists and server-message user restrictions | `allowed_user_ids` | | Allowed roles | Optional Discord role IDs used for server-message role restrictions | `allowed_role_ids` | | Direct messages | off: ignore direct messages; open: accept from any Discord user; allowlist: accept only from Allowed users | `dm_policy` | | Require mention | Enabled by default. When enabled, server messages must directly mention the bot; when disabled, otherwise eligible server messages are admitted without one | `require_mention` | | Alert channel | Optional channel ID. The built-in runtime adapter does not use this field for scheduled delivery; setting it does not enable scheduled notifications through that adapter | `home_channel_id` | ### Users and roles For server messages, when Allowed users or Allowed roles are configured, a sender is admitted if **either** condition holds: - Their user ID is allowed, or - They hold at least one allowed role. Both conditions are not required. A role ID is used purely as an interaction boundary, and role names cannot replace the numeric ID. ``` allowed_user_ids: 456789012345678901 allowed_role_ids: 567890123456789012, 890123456789012345 ``` ### Direct messages Direct messages default to `off`, but they are configurable and not permanently disabled. Set `open` to accept messages from any Discord user, or `allowlist` to accept them only from Allowed users. ### Alert channel and scheduled messages The connection form includes an optional **Alert channel** field. The built-in runtime adapter does not use this setting to route independently scheduled output to Discord. The adapter sends replies through the connection and destination of an existing incoming delivery. Setting **Alert channel** therefore does not enable scheduled notifications through this adapter. A separate integration needs its own documented delivery setup. Configuring the field does not grant the bot Discord permission to access that channel; the bot must already be able to see and post there. ### Recommended production configuration ``` group_policy: allowlist guild_ids: One or more approved server IDs allowed_channel_ids: Explicitly configured allowed_user_ids: Explicitly configured, or empty allowed_role_ids: Explicitly configured, or empty require_mention: Enabled dm_policy: off home_channel_id: Optional approved channel ``` Start narrow, then widen after the first successful exchange. See [Configure channel access](/guides/agents/channel-access) for policy guidance. ## Verify the integration Confirm the Connection is enabled and its Gateway session is healthy, then test from a controlled channel. | Test | Expected result | | --- | --- | | Mention the bot in an allowed channel | The Agent responds | | Send an unmentioned message while Require mention is enabled | The Agent does not respond | | Mention the bot in a channel outside Allowed channels | The Agent does not respond | | Send a message as a sender outside Allowed users and roles | The Agent does not respond | | Send a direct message while Direct messages is `off` | The Agent does not respond | | Send a direct message as an Allowed user while Direct messages is `allowlist` | The Agent responds | Then confirm the exchange in Agent Barn: 1. Open the Agent. 2. Open **Conversations**. 3. Select this Discord Connection. 4. Confirm the inbound message and outbound response appear under it. See [Verify your Agent](/guides/get-started/verify-agent) for the full layered verification. ## How access is evaluated A Discord server message passes through several layers, in order: 1. **Discord permits the bot** The bot is installed in the server and Discord allows it to access the channel 2. **The server passes Channel access** Policy is open, or the server ID appears in Allowed servers 3. **The channel passes Allowed channels** The list is empty, or the channel ID appears in it 4. **The sender passes user or role policy** Their user ID is allowed, or they hold at least one allowed role 5. **The message satisfies Require mention** The bot is mentioned directly, when the setting is enabled Direct messages use a shorter path: 1. Direct messages must not be set to `off`. 2. When set to `allowlist`, the sender must appear in Allowed users. 3. Mention gating does not apply. Every layer after the first is a Communication Connection policy, not a Runtime capability. The first layer belongs to Discord itself. ## Gateway and conversation behavior - The Communications Gateway owns a supervised Discord Gateway connection. - The Connection receives Discord `MESSAGE_CREATE` events and component interactions. - Bot-authored messages are ignored. - Accepted messages and command-approval clicks become durable Communication Deliveries. - Interactive command approvals render clickable buttons directly in Discord (up to five per row) and acknowledge interactions within Discord's response deadline. - Replies and thread references are preserved where Discord provides them. - Conversation histories remain scoped to the Discord Connection. Provider-supplied names are preferred, with best-effort credential-scoped user and channel enrichment when names are missing. Discord IDs remain the stable policy and conversation identifiers. ## Change the Connection later Discord settings, credentials, and intents can be changed without touching the Agent. - Connection updates increment the Connection revision. - The Communications Gateway reconciles the Discord Gateway session independently. - Updating the Connection does not rebuild or restart the Agent Runtime. - Disabling or retiring the Connection stops its provider activity without deleting the Agent. When the Gateway session needs recovery, request a Connection reconnect through its diagnostics rather than restarting the Agent. ## Manage the bot token The token lives in two places: the Developer Portal, and the Connection's credential field. 1. Reset the token on the application's **Bot** page. 2. Open the Agent's Discord Connection. 3. Enter the new token. 4. Save the Connection. The Gateway validates the new token and reconciles the session on the next revision. Replacing a token requires Agent secret-management permission. **Security** Resetting a token in Discord immediately breaks the existing Gateway session. Plan the reset and the Connection update together. **Important** The Discord Communication Connection provides message transport. Its bot token is not an Agent Secret or Shared Credential, the token is not materialized into the Agent Runtime, and creating a Discord Connection does not grant unrelated tool Integration access. ## Troubleshooting Start at the saved Connection's health and diagnostics, then work through these checks: - The entered value is the bot token, not another Discord application identifier - Message Content Intent is enabled - Server Members Intent is enabled when member suggestions are needed - The bot is installed in the intended server - The bot has View Channels, Send Messages, and Read Message History permissions - Thread permissions are present when threads are used - The server passes the configured Channel access policy - The channel passes Allowed channels - The sender passes Allowed users or Allowed roles - The message includes a direct mention when Require mention is enabled - Direct messages are enabled when testing through a DM - The Connection is enabled and its Gateway session is healthy The Connection journal shows observation, policy rejection, Runtime delivery, provider delivery, retry, reconnect, or dead-letter activity. Use it to decide which layer to investigate. ### The bot token is rejected Confirm you copied the token from the **Bot** page, not the Application ID, public key, client secret, or an OAuth invite URL. If the token was reset in Discord, enter the current value. Also confirm the token is not already held by another active Discord Connection. ### Messages arrive with no content, or not at all Empty message content almost always means Message Content Intent is disabled. Enable it, then reconnect the bot. If nothing is observed at all, confirm the bot is installed in the server, that Discord grants it View Channels and Read Message History, and that the Connection is enabled with a healthy Gateway session. ### Messages are observed but rejected by policy Work down the layers: Channel access and Allowed servers, then Allowed channels, then Allowed users or Allowed roles, then Require mention. Remember that user and role restrictions are satisfied by _either_ condition, so a sender with an allowed role does not also need to be listed by user ID. ### The Agent receives a message but cannot answer Check the Discord side first: the bot needs Send Messages in that channel, and Send Messages in Threads to reply inside a thread. A channel-level permission override can deny what the server-level grant allows. If Discord permissions are correct, review the Connection's delivery diagnostics. ### Role-based access does not work Confirm the numeric role IDs were entered rather than role names, and enable Server Members Intent when the editor must suggest members or resolve roles. ### The bot works in one channel but not another Check whether Allowed channels is populated and excludes the second channel, and whether Discord channel overrides deny the bot there. ### The Agent responds to ordinary conversation Require mention is probably disabled. Enable it, or narrow Allowed channels so the Connection only listens where broad participation is intended. ### Direct messages do not work Direct messages default to `off`. Set `open`, or set `allowlist` and add the sender's user ID to Allowed users. ### The server is not listed when browsing Directory results only include servers where the bot is installed. Install the bot in that server, then browse again, or enter the server ID manually. ### Messages are delivered but the Agent does not answer Admission succeeded, so the problem is downstream. Review [Agent health and logs](/guides/agents/health-and-logs) for the Runtime, then review the Connection's delivery diagnostics for the outbound reply. Do not restart the Agent for a provider or policy problem. **Note** Discord Gateway health, admission, and delivery belong to the Connection. Agent Runtime health is a separate concern, and a message can be received from Discord successfully but still fail later during Runtime processing or outbound delivery. ## Next steps After the Discord Connection is working: - [Review the Connection lifecycle](/guides/agents/communication-connections) - [Configure channel access](/guides/agents/channel-access) - [Verify your Agent](/guides/get-started/verify-agent) - [Review Agent health and logs](/guides/agents/health-and-logs), separately from Connection health - [Compare platform compatibility](/guides/platforms/compatibility) before adding another Connection - [Set up Slack](/guides/platforms/slack)