Discord Integration

Deploy your Studio bot to a Discord server and control exactly who can interact with it, in which channels, and what capabilities those interactions unlock. Balchemy handles the adapter layer — you configure the behavior.

What is this?

Balchemy runs a shared Discord bot application that connects to servers on behalf of all Studio bots. You authorize the Balchemy bot application in your Discord server once, then configure your bot's specific policy: which guild it operates in, which channels are active, which roles have access, and how it greets new members.

You never manage a Discord bot token, application credentials, or webhook registration. That infrastructure is maintained by Balchemy. Your Studio configuration translates directly into per-guild, per-channel, and per-role behavior for your bot instance — isolated from every other bot on the platform.

Multiple Studio bots can be active in the same Discord server with different channel and role policies, giving you fine-grained control over which bot serves which community segment.

Prerequisites

Before you start, make sure:

You have a bot created in Studio
You are a server administrator (or have the Manage Server permission) in the Discord server you want to connect
You have authorized the Balchemy bot application in your server (instructions in step 3 below)
To link your personal Discord identity to your Balchemy wallet, complete Hub verification at /hub/verify/discord first (see Discord Verification)
Discord Developer Mode is enabled in your Discord client so you can copy channel and role IDs (Settings → Advanced → Developer Mode)

Step-by-step: connect Discord in Studio

Open Studio and navigate to the bot you want to connect.
Select the Platforms tab from the bot sidebar.
Find the Discord card and click Configure to open the settings sheet.
Authorize the Balchemy bot application in your Discord server by visiting discord.com/oauth2/authorize with the Balchemy application ID. Accept the default permissions. You only need to do this once per server.
After authorization, return to Studio. In the Configure sheet, enter your Guild ID — right-click your server name in Discord and select Copy Server ID.
Fill in the remaining fields as needed (see the configuration reference below).
Click Save Configuration.
Toggle the switch on the Discord card to Connected.
Verify the status badge shows Connected with a timestamp.
Test by sending a message in one of your configured Allowed Channels.

Tip: Turn on Developer Mode in Discord before starting this setup (Discord Settings → Advanced → Developer Mode). Without it, right-clicking channels and roles will not show the Copy ID option you need for the configuration fields.

Configuration fields explained

Guild ID (required)

The Guild ID is your Discord server's unique numeric identifier. Every other field in the configuration is scoped to this guild. Right-click your server name in the Discord sidebar and choose Copy Server ID.

If you operate the same bot in multiple servers, you need separate bot configurations for each guild. Create a new bot in Studio for each server you want to deploy to.

Log Channel ID

The Log Channel ID tells Balchemy where to post bot activity summaries — commands received, trades triggered, errors encountered, and role assignments. Paste the channel ID of a private admin channel that your team monitors.

Leave this field empty if you do not want bot activity logged to a Discord channel. Logs are still available in the Studio interface regardless.

Tip: Create a dedicated #balchemy-logs channel with restricted visibility so your team can monitor activity without cluttering public channels.

Allowed Channel IDs

A comma-separated list of channel IDs where your bot is active. When this list is populated, the bot ignores all messages in channels not on the list. Leave it empty to allow the bot to respond in every channel where it has read permissions.

Start with a narrow list during testing — one or two dedicated channels — and expand as needed.

Blocked Channel IDs

A comma-separated list of channel IDs the bot will never respond in, regardless of the Allowed Channel IDs setting. Blocked channels take priority. Use this to permanently exclude announcement channels, rules channels, or any channel where bot activity would be disruptive.

Required Role IDs

When populated, only users who hold at least one of the listed roles can interact with the bot. This is your primary access control for role-gated bots. Paste the role IDs comma-separated.

To find a role ID: open Server Settings → Roles, right-click the role you want, and choose Copy Role ID.

Blocked Role IDs

Users with any of the listed roles are ignored by the bot, even if they also hold a role from the Required Role IDs list. Use blocked roles to exclude moderation bots, administrators (who may not want to trigger trade workflows accidentally), or restricted member roles.

Welcome Message

When enabled, the bot posts a message to a specified channel whenever a new member joins the server. Toggle Welcome Message on and fill in:

Welcome Channel ID — the channel where the greeting is posted
Welcome Message — the message text. Use {user} as a placeholder for the new member's mention.

Keep welcome messages concise and friendly. A good welcome message sets expectations about what the bot can do without overwhelming new members with instructions.

Auto Role ID

If set, Balchemy automatically assigns this role to every new member who joins the server. This is useful for giving all members access to a @community role that your Required Role IDs setting checks for.

Leave this blank if you manage role assignment through Discord's own onboarding flow or a separate bot.

Nickname

The display name for the bot in this server. Discord allows bot nicknames to be set per-server. Use this to match your community's naming conventions — for example, "Alpha Desk" instead of "Balchemy Bot".

Only Respond to Mentions

When turned on, the bot only replies to messages that directly @mention it. This prevents the bot from responding to every message in a busy server. Recommended for servers with multiple channels or a high message volume.

Configuration reference

Field	Type	Required	Notes
Guild ID	Snowflake `string`	Yes	Right-click server → Copy Server ID
Log Channel ID	Snowflake `string`	No	Where bot activity logs are posted
Allowed Channel IDs	Comma-separated `string`	No	Leave empty to allow all channels
Blocked Channel IDs	Comma-separated `string`	No	Always excluded; overrides Allowed list
Required Role IDs	Comma-separated `string`	No	Users must have at least one of these roles
Blocked Role IDs	Comma-separated `string`	No	Users with these roles are always ignored
Welcome Message Enabled	`boolean`	No	Toggle on to enable member welcome
Welcome Channel ID	Snowflake `string`	If welcome enabled	Channel for welcome posts
Welcome Message Content	`string`	If welcome enabled	Use `{user}` placeholder for member mention
Auto Role ID	Snowflake `string`	No	Role assigned automatically to new members
Nickname	`string`	No	Bot's display name in this server
Only Respond to Mentions	`boolean`	No	Require @mention before bot replies

Role-based access control

Role-based access is the most powerful way to gate who can use your bot in a large community. Here is a recommended setup pattern:

Create a dedicated Discord role called @bot-access (or any name you choose).
Assign that role manually to verified community members, or use the Auto Role ID to assign it to all new members.
In the Discord Configure sheet, add that role's ID to Required Role IDs.
Add moderator and admin role IDs to Blocked Role IDs if those accounts should not accidentally trigger bot workflows.

With this pattern you have a single role to manage. Granting access means assigning the role; revoking access means removing it. You never need to touch the Studio configuration again for individual users.

Warning: Required Role IDs and Blocked Role IDs interact. If a user holds both a required role and a blocked role, the blocked role wins and the bot ignores them. Design your role structure so these two sets are mutually exclusive.

Hub identity verification and Discord

Discord integration in Studio and Discord verification in Hub serve different purposes.

Studio Discord configuration defines your bot's server-level behavior — which guild, which channels, which roles.

Hub Discord verification at /hub/verify/discord links your personal Discord account to your Balchemy wallet via OAuth. This is required when you want to claim an external agent that operates on Discord, or when you want Balchemy to route operator notifications to your Discord account.

The Hub OAuth flow redirects you to Discord's authorization page, you approve it, and your Discord user ID is linked to your wallet. See Discord Verification for the full walkthrough.

You can connect a bot to Discord in Studio without completing Hub verification. Hub verification is only needed for identity-claim and notification workflows.

Tips and warnings

Tip: The safest starting configuration is a single Allowed Channel, one Required Role, and Only Respond to Mentions turned on. This gives you the tightest possible surface area to test against before you open access to your community.

Warning: If you leave both Allowed Channel IDs and Required Role IDs empty, your bot will respond to every message from every user in every channel where the Balchemy bot application has read permissions. For a busy server, this can produce a very high message volume.

Tip: Use a separate bot configuration (and a separate Studio bot) for each community tier you want to serve. For example: one bot for a private alpha channel with Trading enabled, and a second bot for a public channel with Analysis only.

Common issues

The bot is in my server but not responding. Check that the Guild ID in the Configure sheet matches your actual server ID exactly. Paste the ID fresh from Discord rather than copying it from another document. Also confirm that the channel you are testing in is either in the Allowed Channel IDs list or the list is empty.

The bot responds in some channels but not others. Your Allowed Channel IDs list does not include the channels where the bot is silent. Either add those channel IDs to the list or clear the list entirely to allow all channels.

Users with the right role cannot interact with the bot. Verify that the role ID in Required Role IDs matches the actual Discord role ID — not the role name. Role names can be duplicated; IDs are unique. Enable Developer Mode in Discord and copy the ID directly from the role.

The bot is responding to everyone, not just role holders. Required Role IDs is empty. When this field is empty, Balchemy imposes no role restriction. Add the correct role ID to gate access.

The welcome message is not being sent to new members. Confirm Welcome Message Enabled is toggled on, the Welcome Channel ID is correct, and the Balchemy bot application has permission to post in that channel. Check the Log Channel for any permission error entries.

Discord OAuth fails — I see a redirect error. Each OAuth authorization flow generates a fresh URL. Do not reuse an old authorization link. Click Connect Discord Account from /hub/verify/discord to generate a new URL every time.

I need to remove the Discord bot from my server. In Discord, go to Server Settings → Integrations → Bots and Apps and revoke the Balchemy application. Then toggle the Discord card in Studio to Disconnected. Removing the bot application from Discord first prevents error states in the Platform card.

Discord Verification — link your personal Discord identity to your wallet
Telegram Integration — connect your bot to Telegram
Platform and MCP Settings — full overview of the Platforms tab
Bot AI Configuration — configure trading and analysis capabilities
Your First Bot — create your first Studio bot

Twitter/X

Edit this page on GitHub