Discord

Nakama can run as a Discord bot so you can chat with the same agent from DMs, server channels, or threads.

The mental model is simple:

• Discord is a channel for Nakama
• The bridge talks to the same Nakama server as the web app
• Pairing links a real Discord user to your Nakama access

What Discord supportsCopy Anchor Link

With Discord enabled, users can:

• chat with a Nakama profile in a private DM
• use the bot in server channels and threads after DM pairing or allowlisting
• keep every conversation attached to the connection's profile
• stop, clear, compact, or restart conversations
• receive streaming replies with typing indicators and live todo progress

Discord can send images (jpeg, png, gif, webp — up to 5 images, 5 MB each) to the agent, with or without a caption. Other attachments and voice are not forwarded yet.

Step 1: Create the bot in DiscordCopy Anchor Link

In the Discord Developer Portal, create an application, then configure it on two separate pages:

1a. Bot tab — token and intentCopy Anchor Link

1. Open Bot (not General Information) → Add Bot if needed → Reset Token → Copy
2. Scroll to Privileged Gateway Intents and turn Message Content Intent on

This toggle is required. Without it, the bridge worker logs Used disallowed intents and cannot connect. There is no API for this — you must flip the toggle in the Developer Portal.

1b. OAuth2 — invite the bot to a serverCopy Anchor Link

1. Open OAuth2 → URL Generator
2. Under Scopes, check bot and applications.commands
3. Under Bot Permissions, check:
   • View Channels
   • Send Messages
   • Read Message History
   • Attach Files
   • Send Messages in Threads (recommended if you use threads)
   • Manage Threads (recommended so /close can archive bot conversation threads)
4. Copy the generated URL, open it, pick a server, and approve

You can also use the Invite bot to server link on Agent → your agent → Channels → Discord after saving your token. Nakama generates an invite with the right permissions.

Keep the token secret. If you enable Message Content Intent after the bot is already in a server, generate a fresh invite and add the bot again.

Step 2: Save in NakamaCopy Anchor Link

Sign in as an organization admin or platform admin and open Agent → your agent → Channels → Discord, then:

1. Paste the bot token
2. Save — Nakama validates it with Discord and generates a pairing code on the same page

The channel settings route is /profiles/:profileId/channels/discord.

Step 3: Pair your Discord accountCopy Anchor Link

Pairing links your Discord user to Nakama so unlinked users cannot use the bot.

1. Copy the pairing code from Agent → your agent → Channels → Discord (click Regenerate if needed)
2. Open a private DM with your bot and send the code as a plain text message

After a successful match, that user is linked and the code is cleared. Server channels require the user to pair in a private DM or be on the profile's allowed-user list.

Step 4: Start the Discord bridgeCopy Anchor Link

On Agent → your agent → Channels → Discord, use the Bridge worker controls to start the worker.

The bridge connects to Discord and forwards messages to your Nakama server.

Optional: Direct allowlist instead of pairingCopy Anchor Link

Nakama also supports allowlisting Discord user IDs directly. This is useful when you want to pre-authorize specific users without the one-time pairing flow.

To add users from the dashboard:

1. Open Agent → your agent → Channels → Discord
2. In Allowed users, click Manage
3. Paste a Discord user snowflake ID and click Add

Use the numeric Discord user ID (snowflake), not the @username.

Private chat behaviorCopy Anchor Link

Private chat is the simplest mode.

Once paired or allowlisted:

• normal messages go to the Nakama profile
• the bot keeps a Discord chat session
• slash commands work immediately

If an unlinked user opens the bot, Nakama asks for the pairing code instead of sending the message to the profile. In server channels, Nakama stays quiet until that user pairs or is allowlisted.

Server and thread behaviorCopy Anchor Link

Nakama supports Discord servers, but it is intentionally conservative about when it replies.

In a server channel, the bot responds only when an authorized user sends:

• a slash command from Discord's command menu
• a reply to one of the bot's messages
• a direct @mention of the bot, or of a Discord role the bot holds

This keeps server channels usable without making the bot noisy. Mention or reply triggers alone do not bypass the paired-or-allowlisted requirement.

Threads and profilesCopy Anchor Link

In Discord threads, each thread keeps its own Nakama session.

• In a parent server channel, every @mention or reply to the bot starts a new Discord thread (you do not need /close or /new first)
• Continue chatting inside a bot-started thread without mentioning the bot again
• The same user can have multiple open bot threads in one channel, and profile replies in different threads can run at the same time
• Every thread uses the profile and organization that own this Discord connection
• /profile and /org are slash commands that report that fixed owner
• /close inside a bot-started thread archives that thread only; other open bot threads stay usable
• /new starts a fresh Nakama conversation in the current Discord thread (it does not open a new Discord thread)
• threads the bot did not start stay quiet until you @mention the bot (or reply to it); that claims the thread so follow-ups work without another mention

Replies in server channels are visible to everyone in that channel. Nakama prefixes those messages so the profile knows the reply is public.

Discord slash commandsCopy Anchor Link

Session controls are Discord slash commands. Use Discord's command menu (/), not plain text commands. The connection is fixed to the profile selected by the channel route; the owner-reporting commands do not switch it.

Paired or allowlisted users can use the session commands. A paired user can also use the administrative /allow slash command to add another Discord user. Unlinked users can use /start and /help to get pairing instructions, but cannot use other commands or start server chat.

In servers, @mention the bot (or a role it holds) or reply to it to chat — each mention in a parent channel opens a new thread. Complete DM pairing or allowlisting first.

Reply formattingCopy Anchor Link

Profiles can write normal Markdown-style replies. Nakama sends them as plain Discord text and splits long replies into multiple messages when needed.

Discord has a 2000-character limit per message. Nakama automatically chunks longer replies.

Saved artifacts and share linksCopy Anchor Link

When your profile saves a file for you with the save-artifact skill, Nakama posts a Publish-style share link after the reply in Discord.

• The link uses the same unguessable /s/{token} URLs as dashboard Publish — no Nakama login required to open it.
• Anyone who can read the Discord message can open the link until the share is revoked from the web app.
• Set Web Public URL in Nakama settings (or NAKAMA_WEB_PUBLIC_URL) so channel footers include absolute links.

To receive the file itself in Discord, ask in plain language — for example, "send the file" or "attach the PDF". The profile uses the Discord-only send_discord_artifact tool to upload a native attachment when the file is within Discord’s size limit. You can also type /attach as a shortcut for the most recent saved artifact. If the file is too large, use the share link instead.

Only successful artifact saves produce share links or attachments.

Connection ownership and disconnectCopy Anchor Link

Each profile owns its bot, pairings, conversations, worker controls, and logs. Threads stay with that profile. Organization admins and platform admins can manage the connection. A bot already connected to another profile cannot be reused.

Stop keeps the configuration. Disconnect removes credentials, pairings, and the channel directory's session/thread data. Disconnect before moving a profile to another organization. Clones and exports do not include connections.

If an older connection cannot be assigned automatically, it stays stopped until it is claimed for an agent through the API (POST /v1/settings/channel-legacy/claim). The dashboard has no claim control. Installation-wide connections require a platform admin.

Running the worker directlyCopy Anchor Link

A direct local run needs the organization and profile that own the connection:

NAKAMA_CHANNEL_ORG_ID="org_your_org" \
NAKAMA_CHANNEL_PROFILE_ID="your-profile" \
bun run dev:discord

Save the connection in the same Nakama config directory first. Set NAKAMA_SERVER_URL and NAKAMA_CONFIG_DIR if you use a separate server or config root.

TroubleshootingCopy Anchor Link

Bridge worker logs Used disallowed intentsCopy Anchor Link

The Discord bridge cannot start because Message Content Intent is off for this bot.

Fix:

1. Discord Developer Portal → your app → Bot
2. Under Privileged Gateway Intents, turn Message Content Intent on
3. Save, then restart the Discord bridge worker in Agent → your agent → Channels → Discord

If the bot was already in your server before you enabled the intent, generate a fresh invite (Step 1b) and add the bot again.

This is not something Nakama can enable for you — Discord only exposes this as a portal toggle, not an API setting.

The bot does not answer at allCopy Anchor Link

Check these first:

1. The bot token is saved correctly
2. The Discord bridge worker is running (start it from Agent → your agent → Channels → Discord)
3. The Nakama server is running
4. The Discord user is paired or allowlisted

Private chat works but server channels do notCopy Anchor Link

Usually one of these is true:

• Message Content Intent is off — turn the toggle on under Bot → Privileged Gateway Intents (see Step 1a)
• the bot was invited before Message Content Intent was enabled — re-invite with a fresh URL (Step 1b)
• the user has not paired or been allowlisted
• the message was not a slash command, reply, bot @mention, or @mention of a role the bot holds

Mentions do not work in serversCopy Anchor Link

1. Turn Message Content Intent on (Step 1a), then re-invite the bot (Step 1b)
2. Make sure only one Discord bridge worker is running
3. Confirm the user is paired or allowlisted
4. @mention the bot user (or a role assigned to the bot) or reply to one of its messages

If Discord autocomplete offers both a role and the bot user with similar names, either works when the bot holds that role. Mentioning an unrelated role does not trigger a reply.

Unlinked users get no server replyCopy Anchor Link

Server channels stay quiet until that Discord user pairs in a private DM or is added to the profile's allowed-user list. Pairing codes only work in DMs — paste one in a server and an authorized user still gets a short DM redirect.

Next stepsCopy Anchor Link

• Quickstart
• Profiles
• Telegram
• WhatsApp