Talk to your GnamiAI agent from Discord.

Install the bot

The Discord integration is part of every GnamiAI workspace, free or paid. There's nothing to download.

1. Sign into the dashboard and go to Settings.
2. Scroll to the Discord card.
3. Click Add to Discord. You'll land on Discord's install screen.
4. In Discord's dropdown, pick the server you want the bot in. You need Manage Server on that guild — Discord enforces this, not us.
5. Click Authorize. Discord redirects you back to GnamiAI and the new connection appears in your Discord settings list.

That's the entire flow. Repeat as many times as you want — one GnamiAI workspace can be wired to multiple Discord servers.

Permissions the bot asks for (and why)

We never ask for Administrator. The OAuth scope is bot and the permissions integer is 76864, which decodes to exactly four capabilities:

• View Channels — required so the bot can see the channel a message was posted in. Without this it would be deaf to everything.
• Send Messages — required so it can answer.
• Read Message History — required so the bot can build a small rolling context window from the last few messages in the channel. Capped at 12 messages.
• Add Reactions — used for the ⏳ "thinking" reaction the bot puts on your message while the agent is running, removed when the answer is posted.

The bot also relies on Discord's Message Content intent, which is required to read what users actually wrote. That intent is enabled at the application level, not requested per-server.

How to talk to the bot

The bot listens for a turn in three ways, in any channel where it has access:

• Mention it. @GnamiAI summarize the last hour of #standup
• Prefix. !gnami what's on my plate today?
• Reply. Reply to any message the bot already sent and your reply gets handled as a follow-up.

Anything else — random chatter in the channel — is ignored. The bot does not auto-answer everything; it waits to be addressed.

While the agent is thinking, the bot adds a ⏳ reaction to your message. When the answer is ready, the reaction is removed and the reply lands in the channel. Long answers are split across multiple messages because Discord's per-message cap is 2000 characters.

How GnamiAI knows which workspace to use

Tenant resolution is server-side and based purely on the Discord guild id. When you authorized the install, we stored a (tenant_id, guild_id) pair in our database. Every message that comes in from that guild is executed inside your tenant: your provider key, your skills, your subagents, your Mem0 memories, your budget ledger.

The Discord user who wrote the message is not used for identity. Whoever talks to the bot in your server triggers a turn against your workspace. Treat the channel like a shared keyboard pointed at your account. Don't add the bot to a public server you don't trust.

Privacy & data retention

• The bot keeps a rolling 12-message per-channel context window. That's it. Older messages are dropped.
• The full prompt + answer for each turn lands in your tenant's budget ledger on GnamiAI, exactly like a turn from the web dashboard. You can browse and delete it from Budget.
• Discord message ids and channel ids are not persisted long-term — only the rolling context window. We never store full guild membership, never query users you didn't address.
• The Cloudflare Worker that holds the WebSocket connection runs no LLMs and stores no provider keys. All inference happens in your GnamiAI workspace.

Disconnect a server

Two ways:

1. From GnamiAI — Settings → Discord → click the ✕ on the server you want to drop. The connection is removed immediately. You should also kick the bot from the guild on the Discord side, otherwise it'll silently sit there with no workspace to talk to.
2. From Discord — kick the bot from the guild (Server Settings → Integrations → GnamiAI → Remove). Next time someone tries to talk to it from that server, the Worker will get a 403 from us and the connection card in your settings will quietly stop receiving turns. Hit ✕ in Settings to clean up the stale row.

Troubleshooting

The bot doesn't reply

• Did you address it? Mention, prefix !gnami, or reply to one of its messages. The bot ignores everything else.
• Can the bot see the channel? Discord per-channel permissions still apply. Check Channel Settings → Permissions → GnamiAI has View Channel and Send Messages.
• Provider key set? The agent needs a working provider in Settings → Providers. Without one, the bot will reply with the actual error from the provider — it never fakes an answer.
• Budget? If the daily budget cap is reached, the turn is rejected and you'll see the error in-channel.

The install fails with "this server is already connected to another workspace"

Each Discord guild can only be wired to one GnamiAI tenant at a time. The other tenant has to disconnect first (Settings → Discord → ✕) before yours can take over.

I sent a DM to the bot and got "DMs aren't connected yet"

That's intentional in v1. DMs cross the tenant-resolution boundary (no guild id), and we'd rather refuse cleanly than guess. Talk to the bot inside a connected server channel.

FAQ

Do I have to host the bot myself?

No. We run a single shared bot on Cloudflare Workers. Tenant isolation happens at the GnamiAI layer based on the Discord guild id. The bot you install is the same hosted instance for everyone — your data is yours regardless.

Does this cost extra?

No. The Discord integration is free for every GnamiAI workspace. The agent turns it triggers count against your usual budget ledger and provider quotas, same as turns from the web dashboard.

Can multiple people in my Discord server talk to the bot?

Yes. Anyone with channel access can address the bot. All their turns are billed to your tenant and recorded under your budget. Treat that as a feature for trusted teams; for public servers, think twice before installing.

Can I run two different agents in two channels?

Not yet via the bot itself. The active subagent pin is per-tenant, set from Subagents. We're considering per-channel pins; not in v1.

Where is the bot's source code?

The Worker code lives at cloudflare-bot/ in the GnamiAI repository. The repo is private, but the architecture is documented in this page and in the Worker's README.

Ready?

Open Settings, hit Add to Discord, pick your server. Takes longer to read this page than to wire it up.